Authentication levels with ACR and AMR claims

Amazon Cognito can record how strongly a user authenticated and which methods they used. You provide a target authentication level as an input when a user signs in, and Amazon Cognito reports the level that the user reached and the methods that they completed as claims in the tokens that it issues. These claims apply to any sign-in, including a user's initial sign-in.

You request an authentication level with the acr_values parameter on the managed login authorize and login endpoints, or with the equivalent TARGET_ACR_VALUES parameter in the USER_AUTH API flow. Both accept an ordered list of target authentication levels. You can add the optional max_age parameter (MAX_AGE in the API) to require that the user authenticated within a recent time window. In response to these inputs, Amazon Cognito adds two claims to the tokens that it issues:

The acr and amr claims follow the definitions in the OpenID Connect Core specification. Amazon Cognito uses its own ACR level URIs. You can translate the Amazon Cognito levels to whatever standard your application requires.

Step-up authentication is a common use case for these claims. In step-up authentication, your application requires a user to authenticate with a stronger method before they perform a sensitive operation. To decide whether to prompt, your application compares the acr level and the auth_time claim in the user's ID token against the level and freshness that the operation requires, and requests step-up only when they aren't already met. When step-up is needed, redirect the user to the managed login authorize or login endpoint with acr_values, or call the USER_AUTH API flow with TARGET_ACR_VALUES. For an example, see the Step-up authentication scenario.

You can request ACR and AMR from any Amazon Cognito sign-in entry point. The mechanics for each entry point are documented with that entry point.

Requesting step-up authentication requires the Essentials or Plus feature plan. For more information, see Feature plan requirements.

Authentication levels and methods

Amazon Cognito evaluates the authentication factors that a user completes and expresses the result as an authentication level in the acr claim and a list of authentication methods in the amr claim.

ACR authentication levels

Amazon Cognito defines four fixed authentication levels. The authentication factor combinations that satisfy each level are fixed and you can't change them. You can customize only the URI name of each level for your user pool. For more information, see Configuring ACR level names.

Amazon Cognito assigns the highest authentication level that the user's completed factors fully satisfy.

Level 1 represents password-only authentication. Federation doesn't satisfy a level through this table. Instead, Amazon Cognito derives the authentication level of a federated user from the response of the identity provider (IdP). For more information, see Step-up authentication for federated users.

AMR values

The amr claim is a list of strings. Each authentication factor that the user completes adds its value to the list. Amazon Cognito can add the following values.

ACR and AMR token claims

Amazon Cognito adds the acr and amr claims to access tokens and ID tokens. Your application inspects the acr and amr claims in the access token or ID token to evaluate the authentication level. When a user refreshes their tokens, Amazon Cognito preserves the same acr and amr values on the new access and ID tokens, so the user isn't asked to step up again after every refresh. For more information about token contents, see Using the ID token and Using the access token.

The following example shows an ID token after a user authenticates with a password and a TOTP.

{
  "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE",
  "aud": "abc123def456",
  "exp": 1759348800,
  "iat": 1759345200,
  "auth_time": 1759345200,
  "token_use": "id",
  "acr": "urn:cognito:loa:4",
  "amr": ["pwd", "otp", "mfa"],
  "email": "user@example.com",
  "cognito:username": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

When a user refreshes their tokens, Amazon Cognito sets the same acr and amr values on the new access and ID tokens. The values carry over without modification. This behavior provides a smoother experience because users aren't asked to step up again after every refresh.

Refreshing a token doesn't reset the auth_time claim. If you want to force a user to authenticate again after a period of time, use the max_age parameter, which compares the current time to auth_time regardless of how many times the user refreshed their tokens.

When a user completes step-up authentication, Amazon Cognito issues new access, ID, and refresh tokens with the updated acr and amr claims and a fresh validity period.

Configuring ACR level names

You can customize the URI name of each authentication level for your user pool with the AcrConfiguration field. Configure this field when you create or update a user pool with the CreateUserPool or UpdateUserPool operation. The factor combinations that satisfy each level stay fixed. You customize only the names.

Configuring custom ACR level names with the AcrConfiguration field requires the Essentials or Plus feature plan. For more information, see Feature plan requirements.

The AcrConfiguration field is a map with the keys Level1 through Level4. Each value is an object with a single AcrValue string. You can override only the levels that you want to customize. The following example request customizes the names of levels 2 and 3.

{
  "AcrConfiguration": {
    "Level2": { "AcrValue": "urn:my-standard:loa:2" },
    "Level3": { "AcrValue": "urn:my-standard:loa:3" }
  }
}

The response always returns the effective configuration, with the default names merged in for any levels that you didn't customize.

{
  "AcrConfiguration": {
    "Level1": { "AcrValue": "urn:cognito:loa:1" },
    "Level2": { "AcrValue": "urn:my-standard:loa:2" },
    "Level3": { "AcrValue": "urn:my-standard:loa:3" },
    "Level4": { "AcrValue": "urn:cognito:loa:4" }
  }
}

The following validation rules apply to each AcrValue.

If you change your ACR level names, a user might later present an access token whose acr value no longer matches any configured level. Amazon Cognito doesn't respect the stale value and treats it as an unrecognized level, but this isn't an error. Amazon Cognito still honors the token's amr values and prompts only for factors that aren't already listed in the amr claim, without crediting any particular level.

Feature plan requirements

The following capabilities require the Essentials or Plus feature plan.

The behavior when you request step-up authentication on an insufficient feature plan depends on the entry point.

For more information about feature plans, see User pool feature plans.

Your responsibilities for step-up authentication

Amazon Cognito issues tokens with the authentication level that the user achieved. Your application is responsible for the following.