Authgear
Start BuildingHomePortalCommunity
  • Authgear Overview
  • Get Started
    • Start Building
    • 5-Minute Guide
    • Single-Page App
      • JavaScript (Web)
      • React
      • Angular
      • Vue
    • Native/Mobile App
      • iOS SDK
      • Android SDK
        • Android Kotlin coroutine support
        • Android OKHttp Interceptor Extension (Optional)
      • Flutter SDK
      • React Native SDK
      • Ionic SDK
      • Xamarin SDK
      • Using Authgear without SDK (Client side)
    • Regular Web App
      • Express
      • Next.js
      • Python Flask App
      • Java Spring Boot
      • ASP.NET Core MVC
      • Laravel
      • PHP
    • Backend/API Integration
      • Validate JWT in your application server
      • Forward Authentication to Authgear Resolver Endpoint
    • AI Coding tools
      • Cursor/Windsurf
  • How-To Guides
    • Authenticate
      • Add Passkeys Login
      • Add WhatsApp OTP Login
      • Add Email Magic Link Login
      • Add Biometric Login
      • Add Anonymous Users
      • Add authentication to any web page
      • Enable Two-Factor Authentication (2FA)
      • How to Use the OAuth 2.0 State Parameter
      • Reauthentication
      • How to Use Social/Enterprise Login Providers Without AuthUI
      • Passwordless Login for Apple App Store Review
      • Setup local development environment for Cookie-based authentication
      • Forgot/Reset Password settings
      • Phone number validation
      • Set Password Expiry
    • Single Sign-on
      • App2App Login
      • Pre-authenticated URLs
      • SSO between Mobile Apps / Websites
      • Force Authgear to Show Login Page
      • Single Sign-On with OIDC
      • Single Sign-On with SAML
        • Use Authgear as SAML Identity Provider for Salesforce
        • Use Authgear as SAML Identity Provider for Dropbox
        • SAML Attribute Mapping
    • Social Login / Enterprise Login Providers
      • Social Login Providers
        • Connect Apps to Apple
        • Connect Apps to Google
        • Connect Apps to Facebook
        • Connect Apps to GitHub
        • Connect Apps to LinkedIn
        • Connect Apps to WeChat
      • Enterprise Login Providers
        • Connect Apps to Azure Active Directory
        • Connect Apps to Microsoft AD FS
        • Connect Apps to Azure AD B2C
      • Force Social/Enterprise Login Providers to Show Login Screen
    • Built-in UI
      • Branding in Auth UI
      • User Settings
      • Privacy Policy & Terms of Service Links
      • Customer Support Link
      • Custom Text
    • Custom UI
      • Authentication Flow API
      • Implement Authentication Flow API using Express
      • Implement Authentication Flow API using PHP
      • Add Custom Login/Signup UI to Native Apps
      • Manually Link OAuth Provider using Account Management API
      • Implement a custom account recovery UI using Authentication Flow API
    • Integrate
      • Add custom fields to a JWT Access Token
      • User Analytics by Google Tag Manager
      • Track User Before and After Signup
      • Custom domain
      • Custom Email Provider
      • Custom SMS Provider
        • Twilio
        • Webhook/Custom Script
    • Monitor
      • Audit Log For Users Activities
      • Audit Log for Admin API and Portal
      • Analytics
    • User Management
      • Account Deletion
      • Import Users using User Import API
      • Export Users using the User Export API
      • Manage Users Roles and Groups
      • How to Handle Password While Creating Accounts for Users
    • User Profiles
      • What is User Profile
      • Access User Profiles
      • Update User Profiles
      • Profile Custom Attributes
      • Update user profile on sign-up using Hooks
    • Events and Hooks
      • Event List
      • Webhooks
      • JavaScript / TypeScript Hooks
      • Only Allow Signups from Inside the Corporate Network using Hooks
    • Mobile Apps
      • Use SDK to make authorized API calls to backend
      • Force authentication on app launch
      • Customize the Login Pop-up / Disable the login alert box
    • Languages and Localization
    • Custom Email and SMS Templates
    • Directly accessing Authgear Endpoint
    • Migration
      • Bulk migration
      • Rolling migration
      • Zero-downtime migration
    • Troubleshoot
      • How to Fix SubtleCrypto: digest() undefined Error in Authgear SDK
      • How to Fix CORS Error
  • Concepts
    • Identity Fundamentals
    • Authgear use cases
    • User, Identity and Authenticator
  • Security
    • Brute-force Protection
    • Bot Protection
    • Non-HTTP scheme redirect URI
    • Password Strength
  • Reference
    • APIs
      • Admin API
        • Authentication and Security
        • API Schema
        • Admin API Examples
        • Using global node IDs
        • Retrieving users using Admin API
        • User Management Examples
          • Search for users
          • Update user's standard attributes
          • Update user's picture
          • Generate OTP code
      • Authentication Flow API
      • OAuth 2.0 and OpenID Connect (OIDC)
        • UserInfo
        • Supported Scopes
      • User Import API
      • User Export API
    • Tokens
      • JWT Access Token
      • Refresh Token
    • Glossary
    • Billing FAQ
    • Rate Limits
      • Account Lockout
  • Client App SDKs
    • Javascript SDK Reference
    • iOS SDK Reference
    • Android SDK Reference
    • Flutter SDK Reference
    • Xamarin SDK Reference
  • Deploy on your Cloud
    • Running locally with Docker
    • Deploy with Helm chart
    • Authenticating HTTP request with Nginx
    • Configurations
      • Environment Variables
      • authgear.yaml
      • authgear.secrets.yaml
    • Reference Architecture Diagrams
      • Google Cloud Reference Architecture
      • Azure Reference Architecture
      • AWS Reference Architecture
      • Throughput Scaling Reference
Powered by GitBook
On this page
  • Prerequisites
  • 1. How to Enable 2FA
  • Step 1: Open 2FA Settings Page
  • Step 2: Select a 2FA Requirements Policy
  • Step 3: Add Available 2-Factor Methods
  • 2. Grace Period in Mandatory 2FA
  • How to roll out Mandatory 2FA
  • Step 1: Enable Global Grace Period
  • Step 2: Enable Individual Grace Period

Was this helpful?

Edit on GitHub
  1. How-To Guides
  2. Authenticate

Enable Two-Factor Authentication (2FA)

Guide on how to add Two-Factor Authentication to your application.

PreviousAdd authentication to any web pageNextHow to Use the OAuth 2.0 State Parameter

Last updated 1 month ago

Was this helpful?

Authgear supports Two-Factor Authentication (2FA) or Multi-Factor Authentication (MFA) for additional layers of security in your application.

When you enable MFA on your application, Authgear will require your users to present two or more factors in order to log in. These factors could be their password and a One-time Password (OTP) that is sent to their registered email address or phone number. As a result, an attacker can not gain access to a user's account with only a compromised password.

In this post, you'll learn how to enable MFA or 2FA for your Authgear project and how to configure 2FA grace period.

Prerequisites

  • An Authgear account. Create one for free .

  • An Authgear Project.

  • And basic experience with Authgear.

1. How to Enable 2FA

Step 1: Open 2FA Settings Page

You can enable 2FA and configure other settings from the 2-Factor Authentication page in Authgear Portal.

To open the 2-Factor Authentication page, log in to Authgear Portal, select your project, then navigate to Authentication > 2FA.

Step 2: Select a 2FA Requirements Policy

Next, use the 2FA Requirements dropdown on the 2-Factor Authentication page to set when to require users to use 2-Factor Authentication to sign in.

The available options are:

  • Disabled: When this is selected, 2FA will not be required to log in for any user, including users who already have 2FA set up for their account.

  • Optional: This policy will only require 2FA to log in for users who already have 2FA set up for their account. Users who have not set up 2FA can continue to log in without it.

Toggle the Show "Do not ask again on this device" for 2FA switch on if you wish to require 2FA only the first time a user logs in from a specific device.

Step 3: Add Available 2-Factor Methods

The Available 2-Factor sub-section on the 2-Factor Authentication page shows a list of supported second-factor authentication methods. The supported methods include:

  • Google Authenticator/Authy

  • Additional Password

  • OTP Code/Login Link via Email

  • OTP Code via Phone

Check the box for each 2FA method you wish to enable for your project.

Use the up and down allows on the right of each method to order the priority of the 2FA methods.

Once you're done, click on the Save button at the top-left of the 2-Factor Authentication page to keep your new settings.

2. Grace Period in Mandatory 2FA

The 2FA Grace Period feature grants your users some time to set up 2FA for their accounts. This is very helpful for the Mandatory enforcement of 2FA.

The following are the two types of 2FA grace periods you can set for your Authgear project:

Global Grace Period: When this type of grace period is enabled, all users who do not have 2FA set up for their account will be asked to set up 2FA the next time they log in. When the Global Grace Period is disabled, users who have not set up 2FA for their account cannot log in. Instead, they'll get an error message requesting them to contact an admin.

Individual Grace Period: This is a type of grace period that is set per user. It grants a user 10 days to set up 2FA for their account. This is ideal for allowing individual users to set up 2FA when the Global Grace Period is disabled.

How to roll out Mandatory 2FA

The following steps show how to roll out Mandatory 2FA using grace periods:

  1. Change 2FA requirement policy to Mandatory

  2. Enable Global Grace Period so that all users who haven't set up 2FA are required to do so the next time they login.

  3. Use your own channel to notify user's about the duration of the global grace period you've decided.

  4. Disable the Global Grace Period once the date you notified users of has passed. After you do this, users that still haven't set up 2FA will be unable to log in.

Step 1: Enable Global Grace Period

To enable the Global Grace Period, navigate to Authentication > 2FA in the Authgear Portal. Then, set 2FA Requirements to Mandatory so that you can view the Enable global grace period switch.

Toggle the Enable global grace period switch on so that your users without 2FA will be required to set up 2FA the next time they log in. Or set Enable global grace period off, if you do not want users without 2FA to log in, or set up 2FA without contacting an admin.

Step 2: Enable Individual Grace Period

When you set the 2FA requirement for your project to Mandatory and Global Grace Period is turned off, you can still use the individual grace period to grant a specific user a grace period to set up 2FA for their account.

To set individual grace period, navigate to User Management > User in Authgear Portal. Then, select the user you wish to set individual grace period for by clicking on the row with their ID in your project's users' list.

From the selected user's details page, click on the Account Security tab, then the Grant grace period to set up 2FA button. You will see a prompt to confim your action, click Confirm to continue.

The duration of the individual grace period is 10 days. However, you can extend or cancel it from the user's details page.

Mandatory: Use the mandatory policy to require 2FA for all users. That means users who have not set up 2FA will not be able to log in if no grace period is set. To use this option, consider further actions like .

When users that could not set up their 2FA during the Global Grace Period contact you (the admin), enable individual grace period for them using the instructions in .

setting up a grace period for rollout
step 2
here
getting started