oauth2.dev

at_hash

OpenID_Foundation_Artifact_Binding_Working_Group

Registry Context

at_hash is the Access Token hash value used in OpenID Connect ID Tokens to bind an access token to the ID Token.

Technical Summary

The value is the base64url encoding of the left-most half of the hash of the octets of the ASCII access_token value, using the hash algorithm associated with the ID Token JOSE alg header. The at_hash value is a case-sensitive string.

When Used

Used in OpenID Connect ID Tokens, especially Implicit and Hybrid flows, to validate or bind an Access Token returned with the ID Token.

Normative Requirements

Clients

MUST
1
  1. openid-connect-core-1_0 - Section 3.2.2.9

    ensure that the at_hash value in the ID Token matches the computed Access Token hash value.

    Condition: when validating an Access Token issued from the Authorization Endpoint with an ID Token

    The value of at_hash in the ID Token MUST match the value produced in the previous step.

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

    validate an Access Token issued from the Authorization Endpoint with an ID Token by hashing the ASCII access_token value, taking the left-most half of the hash, base64url-encoding it, and comparing it to at_hash.

    Condition: when validating an Access Token issued from the Authorization Endpoint with an ID Token

    To validate an Access Token issued from the Authorization Endpoint with an ID Token, the Client SHOULD do the following: Hash the octets of the ASCII representation of the access_token with the hash algorithm specified in JWA for the alg Header Parameter of the ID Token's JOSE Header.

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

    use the at_hash claim to validate the Access Token in the same manner as for the Implicit Flow, using the ID Token and Access Token returned from the Token Endpoint.

    Condition: when using the Authorization Code Flow and the ID Token contains an at_hash Claim

    When using the Authorization Code Flow, if the ID Token contains an at_hash Claim, the Client MAY use it to validate the Access Token in the same manner as for the Implicit Flow, as defined in ImplicitTokenValidation, but using the ID Token and Access Token returned from the Token Endpoint.

Authorization servers

REQUIRED
2
  1. openid-connect-core-1_0 - Section 3.2.2.10

    include the at_hash claim in the ID Token.

    Condition: when using the Implicit Flow and the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for response_type value id_token token

    If the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for the response_type value id_token token, this is REQUIRED;

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

    include the at_hash claim in the ID Token.

    Condition: when using the Hybrid Flow and the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for response_type value code id_token token

    If the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for the response_type value code id_token token, this is REQUIRED; otherwise, its inclusion is OPTIONAL.

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

    include the at_hash claim as an Access Token hash value in an ID Token returned from the Token Endpoint.

    Condition: when using the Authorization Code Flow

    When using the Authorization Code Flow, these additional requirements for the following ID Token Claims apply: OPTIONAL. Access Token hash value.

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

    include the at_hash claim in the ID Token.

    Condition: when using the Hybrid Flow and the ID Token is not issued from the Authorization Endpoint with an access_token value

    If the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for the response_type value code id_token token, this is REQUIRED; otherwise, its inclusion is OPTIONAL.

Validation Guidance

error

For generated or parsed at_hash values, compute base64url(left-most half(hash(ASCII(access_token)))) using the hash algorithm associated with the ID Token JOSE alg header, then compare to the ID Token at_hash value.

error

Require at_hash in Implicit Flow ID Tokens issued from the Authorization Endpoint with an access_token value.

error

Require at_hash in Hybrid Flow ID Tokens issued from the Authorization Endpoint with an access_token value.

info

Treat at_hash as optional in Authorization Code Flow Token Endpoint ID Tokens unless present and used for validation.

Security Notes

openid-connect-core-1_0 - Section 16.11

OpenID Connect describes at_hash as a mechanism that enables Clients to prevent Access Token substitution.

Reference

Details

Entry Id
at_hash
Claim Name
at_hash
Claim Description
Access Token hash value
Change Controller
OpenID_Foundation_Artifact_Binding_Working_Group
Reference
OpenID Connect Core 1.0 - Section 2