Assurance and method values
The acr values an application can ask for, the amr values a token can carry, and which sign-in produces which.
On this page
Two claims in an ID token and an access token describe how a person signed in. acr is the assurance level reached, and amr lists the methods used. An application reads them to decide whether a sign-in is strong enough for what it is about to do. Both are omitted from a client_credentials token, because no person signed in.
acr values#
Discovery lists three values in acr_values_supported. They are the authenticator assurance levels of NIST SP 800-63B, spelled out.
| Value | Level | Reached by |
|---|---|---|
aal1 | 1 | A password alone, an emailed sign-in link, or a sign-in with an external provider that did not assert multi-factor. |
aal2 | 2 | A passkey with user verification, a password plus an authenticator code or a recovery code, or an external provider the platform trusts that asserted multi-factor. |
aal3 | 3 | Reserved for a passkey on an attested hardware authenticator. Identity does not verify attestation yet, so no sign-in reaches it today. Status: Planned. |
Some sign-in steps look like a second factor but stay at aal1. A password typed after an emailed link or an external sign-in, an emailed code typed after a password, and the extra steps a person can turn on all add a check without raising the level. A password alone is aal1 with amr ["pwd"] however it ends, including a limited session opened with Continue with my password only (limited session), which an application asking for aal2 in acr_values does not accept. The sign-in page says so: This is an extra step you turned on. It adds a check, but it does not make your sign-in two-factor.
Asking for a level#
Send acr_values on the authorization request with one or more values. Identity uses the highest one you list. If the person's current session is below it, they are asked to confirm with a stronger method before the code is issued. Any other value is refused with invalid_request.
The level is a minimum, not a list of alternatives: asking for aal2 is satisfied by a session at aal2 or above.
An organization can also set a minimum level for its own sign-ins, and an organization inside another can only tighten what the one above it sets. A sign-in that does not reach it is not completed, and the person is told the method is not strong enough. The acr in your token is the level the sign-in actually reached, so check it even when you asked for a level.
An organization that requires single sign-on (behind the sso_enforcement flag, which defaults OFF) can refuse a token request with insufficient_user_authentication, acr_values of aal1 and a max_age. The level named is the lowest because the requirement is a recent sign-in through the organization's connection, which max_age expresses.
Related authorization parameters#
| Parameter | Effect |
|---|---|
prompt=login | Asks the person to sign in again even with a live session. |
max_age | A number of seconds. If the session's auth_time is older, the person signs in again. When acr_values also asks for aal2 or aal3, the person instead confirms a fresh second factor on their live session (a step-up). A session that a passkey alone signed in, or that is at aal3, signs in again instead. It must be a non-negative integer. |
prompt=none | Never shows a page. If a sign-in or a stronger method would be needed, the answer is the error login_required. |
When more than one applies, an explicit prompt=login is handled first, then max_age, then acr_values.
amr values#
amr is a list of method tokens. The tokens below are the ones identity can place in it.
| Token | Meaning | Defined by |
|---|---|---|
pwd | A password was verified. | RFC 8176 |
otp | An authenticator app code was verified. | RFC 8176 |
hwk | A passkey was used. | RFC 8176 |
user | The person was verified on their device, for example with a fingerprint or a screen lock. Added with hwk. | RFC 8176 |
fed | An external provider signed the person in. | Identity |
mfa | The external provider asserted multi-factor. Added with fed. | RFC 8176 |
ml | An emailed sign-in link or code was used. | Identity |
rcv | A recovery code was used as the second factor. | Identity |
eml | An emailed second-step code was used. | Identity |
The list has no duplicates, and its order carries no meaning. Do not test amr for an exact array; test whether it contains the token you care about.
Common combinations#
| How the person signed in | amr contains | acr |
|---|---|---|
| Password | pwd | aal1 |
| Password and authenticator code | pwd, otp | aal2 |
| Password and recovery code | pwd, rcv | aal2 |
| Passkey | hwk, user | aal2 |
| Emailed link | ml | aal1 |
| Emailed link, then password | ml, pwd | aal1 |
| Password, then emailed code | pwd, eml | aal1 |
| External provider | fed | aal1 |
| External provider with multi-factor | fed, mfa | aal2 |
After a second-factor step-up on a live session, amr lists the first factor the session already had (for example pwd) with the fresh second factor (otp). auth_time is the time of that second factor, so only the second factor is that recent.
What the account shows#
The Devices page names the method of each session, for example Passkey or Password; see Sessions and devices. Why a sign-in asks for more is explained in Signing in.