Skip to main content

Customizing MFA configuration

  • Updated
 

Partners can configure an application to allow specific types of MFA using one of four options:

  • Any MFA, remember device allowed (AAL1): Users can choose any supported MFA option and can check “Remember this device” for up to 30 days.
  • Any MFA, remember device disallowed (AAL2): Users can choose any MFA option but must always complete MFA at each sign-in.
  • Phishing-resistant MFA required (AAL2): Users must sign in with a phishing-resistant MFA option: face or touch unlock, security key, or PIV/CAC card.
  • Government employee ID required (AAL2): Users must sign in with a PIV/CAC card.

In accordance with NIST’s Digital Identity Guidelines, agencies select an appropriate authentication assurance level based on their service’s risks and applicable requirements. Login.gov defaults identity verification integrations to AAL2 unless the partner selects a more restrictive authentication configuration.

How to Configure MFA Requirements

There are two ways to set the MFA requirement:

  • Authentication request (recommended): Specify the desired AAL value in the acr_values parameter (OIDC) or within a <saml:AuthnContextClassRef> node (SAML) of each authentication request. This approach is configured within your application’s codebase or within your third-party identity platform (e.g., Okta). See the OIDC developer documentation and SAML developer documentation for supported values and examples.
  • Partner Portal default: Set a default AAL value in the Partner Portal. This default only applies if the authentication request does not specify an AAL value. If the request specifies a value, it overrides the portal setting.

Troubleshooting MFA Configuration

Users prompted for MFA every time despite AAL1 portal setting:

This is usually caused by one of two things:

  • Your authentication request specifies an AAL2 value, which overrides the portal setting. See the troubleshooting steps below to inspect your request.
  • Your application’s Level of Service is set to “Identity verification permitted” in the Partner Portal. When IdV is permitted, MFA is always required regardless of AAL settings.

Users only see phishing-resistant MFA options despite AAL2 portal setting:

Your authentication request is likely specifying the phishing-resistant AAL2 value (http://idmanagement.gov/ns/assurance/aal/2?phishing_resistant=true), which overrides the portal setting. See the troubleshooting steps below.

Inspecting Your Authentication Request

To verify what AAL values your application is sending:

For OIDC:

  • Open your browser’s developer tools.
  • Click the “Sign in with Login.gov” button in your application.
  • In the Network tab, click “authorize” in the Name column.
  • Check the full request URL for the acr_values parameter.

For SAML:

  1. Open your browser’s developer tools.
  2. Click the “Sign in with Login.gov” button in your application.
  3. In the Network tab, click “auth2025” or “auth2026” in the Name column.
  4. Find the SAMLRequest in the Payload tab (Chrome) or Query String Parameters (Safari).
  5. Copy the SAMLRequest value.
  6. Decode it at https://www.samltool.com/decode.php (paste in the “Deflated and Encoded XML” box and click “Decode and Inflate XML”).
  7. Look for values within the <saml:AuthnContextClassRef> nodes.

AAL2 Configuration

The primary difference between default-AAL and AAL2 authentication relates to the “Remember this device” feature:

  • Default-AAL: “Remember this device” works as described above.
  • AAL2: “Remember this device” is not honored. Users must always complete MFA at each sign-in session.

In accordance with NIST’s Digital Identity Guidelines, agencies select an appropriate authentication assurance level based on their service’s risks and applicable requirements. Login.gov defaults identity verification integrations to AAL2 unless the partner selects a more restrictive authentication configuration. 

Phishing-Resistant Authentication

Login.gov supports phishing-resistant MFA options, which use cryptographic methods rather than user-entered codes:

  • Face or touch unlock – see the [Face or Touch Unlock guide] for details
  • FIDO2 security keys
  • PIV/CAC cards

Partners can require phishing-resistant authentication by specifying the appropriate AAL value in their authentication request. See OIDC ACR values and SAML ACR values for implementation details.

Users Without Phishing-Resistant MFA Configured

When a user who only has weaker MFA options (e.g., SMS or authentication app) tries to sign in to an application requiring phishing-resistant MFA, they will first be prompted to sign in with their existing MFA. This is a security measure: if Login.gov allowed a phishing-resistant setup without first verifying identity, a bad actor with a stolen password could add their own phishing-resistant MFA and take over the account.

After signing in with their existing MFA, the user will see a screen prompting them to set up a phishing-resistant option. If they do not set one up, they will not be able to sign in to the partner application.

Enforcing Phishing-Resistant MFA for a Subset of Users

To require phishing-resistant MFA for only some users (e.g., based on role or data sensitivity), implement a step-up authentication flow:

  1. Initial sign-in: Configure your default authentication request with a standard AAL value (AAL1 or AAL2 without phishing resistance).
  2. Evaluate the user: After Login.gov redirects the user back to your application, look up the user (by UUID, email, or other attributes) and determine whether they require phishing-resistant MFA.
  3. Step-up request: If phishing-resistant MFA is required, make a second authentication request to Login.gov specifying the phishing-resistant AAL value. 
  4. If the user already used phishing-resistant MFA: They are immediately redirected back with no additional prompts. The experience is seamless.
  5. If the user used a weaker MFA: They will be prompted to choose or set up a phishing-resistant option. Login.gov displays a message explaining that your application requires this higher-security method.

Many third-party identity platforms support step-up authentication natively.

Why Login.gov Does Not Provide a Phishing-Resistant MFA Attribute

Login.gov does not return an attribute indicating whether a user signed in with a phishing-resistant MFA method. The supported user attributes do not include MFA method information.

This is intentional for several reasons:

  • A phishing-resistant MFA attribute alone is not sufficient to enforce the requirement. Without a step-up request, the partner application has no way to require the user to re-authenticate with a stronger method, leading to sign-out/sign-in loops and a poor user experience.
  • The step-up authentication flow described above is the supported and recommended approach. It produces a seamless user experience that Login.gov can troubleshoot and support.