oauth2.dev

c_hash

OpenID_Foundation_Artifact_Binding_Working_Group

Registry Context

c_hash is the code hash value included in an ID Token. It is used in OpenID Connect Hybrid Flow to bind an authorization code to the ID Token.

Technical Summary

The c_hash value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the authorization code, using the hash algorithm associated with the ID Token JOSE alg header parameter. The value is case-sensitive.

When Used

Used for ID Tokens returned from the Authorization Endpoint in Hybrid Flow, especially response_type values code id_token and code id_token token.

Normative Requirements

Clients

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

    ensure the c_hash value in the ID Token matches the value produced by hashing the authorization code as specified.

    Condition: if c_hash is present in the ID Token

    The value of c_hash in the ID Token MUST match the value produced in the previous step if c_hash is present in the ID Token.

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

    validate an Authorization Code issued from the Authorization Endpoint with an ID Token by following the specified c_hash calculation procedure.

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

    To validate an Authorization Code issued from the Authorization Endpoint with an ID Token, the Client SHOULD do the following:

Authorization servers

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

    include c_hash in the ID Token.

    Condition: if the ID Token is issued from the Authorization Endpoint with a code, which is the case for response_type values code id_token and code id_token token

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

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

    include c_hash in the ID Token.

    Condition: otherwise, when the ID Token is not issued from the Authorization Endpoint with a code

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

Validation Guidance

error

When c_hash is present, recompute it from the ASCII representation of the authorization code using the hash algorithm implied by the ID Token JOSE alg header, then compare it with the ID Token c_hash value.

error

Require c_hash for ID Tokens issued from the Authorization Endpoint with a code in Hybrid Flow response types code id_token and code id_token token.

info

Treat c_hash as optional outside the condition where the ID Token is issued from the Authorization Endpoint with a code.

Reference

Details

Entry Id
c_hash
Claim Name
c_hash
Claim Description
Code hash value
Change Controller
OpenID_Foundation_Artifact_Binding_Working_Group
Reference
OpenID Connect Core 1.0 - Section 3.3.2.11