oauth2.dev

acr

OpenID_Foundation_Artifact_Binding_Working_Group

Registry Context

The acr claim is an optional ID Token claim that carries the Authentication Context Class Reference satisfied by the end-user authentication.

Technical Summary

acr is a case-sensitive string claim in an OpenID Connect ID Token. Its value identifies the Authentication Context Class satisfied by the authentication. The value "0" has a special low-confidence meaning. Values should be absolute URIs or RFC 6711 registered names, and registered names must retain their registered meaning.

When Used

Used in OpenID Connect ID Tokens when a relying party needs to know or request the authentication context level or class used for the end-user authentication.

Normative Requirements

Authorization servers

MUST
2
  1. openid-connect-core-1_0 - Section 5.5.1.1

    return an acr Claim Value that matches one of the requested values.

    Condition: if the acr Claim is requested as an Essential Claim for the ID Token with a value or values parameter requesting specific Authentication Context Class Reference values and the implementation supports the claims parameter

    If the acr Claim is requested as an Essential Claim for the ID Token with a value or values parameter requesting specific Authentication Context Class Reference values and the implementation supports the claims parameter, the Authorization Server MUST return an acr Claim Value that matches one of the requested values.

  2. openid-connect-core-1_0 - Section 5.5.1.1

    treat the outcome as a failed authentication attempt.

    Condition: if the acr Claim is Essential and the requirement cannot be met

    If this is an Essential Claim and the requirement cannot be met, then the Authorization Server MUST treat that outcome as a failed authentication attempt.

SHOULD
1
  1. openid-connect-core-1_0 - Section 5.5.1.1

    return the session's current acr as the value of the acr Claim.

    Condition: if the Claim is not Essential and a requested value cannot be provided

    If the Claim is not Essential and a requested value cannot be provided, the Authorization Server SHOULD return the session's current acr as the value of the acr Claim.

MAY
1
  1. openid-connect-core-1_0 - Section 5.5.1.1

    ask the End-User to re-authenticate with additional factors.

    Condition: to meet an Essential acr Claim request

    The Authorization Server MAY ask the End-User to re-authenticate with additional factors to meet this requirement.

ID Token issuer

OPTIONAL
1
  1. openid-connect-core-1_0 - Section 2

    include the acr claim as an Authentication Context Class Reference claim.

    Condition: within an ID Token

    OPTIONAL. Authentication Context Class Reference.

implementations relying on level 0 authentications

SHOULD NOT
1
  1. openid-connect-core-1_0 - Section 2

    use authentications with level 0 to authorize access to resources of monetary value.

    Condition: when the acr value is "0"

    Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value.

parties generating or using acr values

SHOULD
1
  1. openid-connect-core-1_0 - Section 2

    use an absolute URI or an RFC 6711 registered name as the acr value.

    An absolute URI or an RFC 6711 registered name SHOULD be used as the acr value;

parties using registered acr names

MUST NOT
1
  1. openid-connect-core-1_0 - Section 2

    use registered names with a meaning different from the registered meaning.

    Condition: when an RFC 6711 registered name is used as the acr value

    registered names MUST NOT be used with a different meaning than that which is registered.

Relying Party

MAY
1
  1. openid-connect-core-1_0 - Section 5.5.1.1

    request the acr Claim as a Voluntary Claim.

    Condition: by using the acr_values request parameter or by not including "essential": true in an individual acr Claim request

    Note that the RP MAY request the acr Claim as a Voluntary Claim by using the acr_values request parameter or by not including "essential": true in an individual acr Claim request.

Validation Guidance

info

Treat acr as optional in an ID Token, but when present validate it as a case-sensitive string Authentication Context Class Reference value.

warning

Warn when acr is "0" and the token is being used to authorize access to a resource with monetary value.

warning

Warn when acr is neither an absolute URI nor an RFC 6711 registered name.

error

Reject or flag registered acr names that are used with a meaning different from their registered meaning.

error

For Essential acr requests with specific value or values parameters, verify that the returned acr matches one of the requested values when the claims parameter is supported.

error

For Essential acr requests that cannot be satisfied, verify the authorization server fails the authentication attempt rather than returning a non-matching acr.

warning

For non-Essential acr requests where the requested value cannot be provided, expect the session's current acr when an acr claim is returned.

Security Notes

openid-connect-core-1_0 - Section 2

The value "0" indicates the authentication did not meet ISO/IEC 29115 level 1 and should not be used for authorizing access to resources of monetary value.

Reference

Details

Entry Id
acr
Claim Name
acr
Claim Description
Authentication Context Class Reference
Change Controller
OpenID_Foundation_Artifact_Binding_Working_Group
Reference
OpenID Connect Core 1.0 - Section 2