Overview#

Identity Token is a JSON Web Token which provides Identity and security assertion issued by the Authorization Server and consumed by an OAuth Client.

The Identity Token resembles the concept of an identity card, in a standard JWT format, signed by the OpenID Provider (OP). To obtain one the OAuth Client needs to send the user to their OP with an authentication request.[1]

The primary extension that OpenID Connect makes to OAuth 2.0 to enable End-Users to be Authenticated is the Identity Token data structure. The Identity Token is a security Token that contains Claims about the Authentication of an End-User by an Authorization Server when using a OAuth Client, and potentially other requested Claims. The Identity Token is represented as a JSON Web Token.

Requesting an Identity Token#

How can an OAuth Clientclient request an Identity Token in OpenID Connect?

Authentication of the user must take place at the Identity Provider (IDP), where the user’s session or credentials will be checked. For that a trusted agent is required, and this role is usually played by the web browser. Browser popups is the preferred way for web apps to redirect the user to the IdP. Mobile apps on platforms such as Android or iOS should launch the system browser for that purpose.

Embedded web views are not be trusted, as there’s nothing to prevent the app from snooping on the user password.

User authentication must always occur in a trusted context separate from the app’s context (e.g. the browser).

Note that OpenID Connect doesn’t specify how users should actually be authenticated, this is left up to providers.

Identity Tokens are requested via the OAuth 2.0 protocol (RFC 6749). OAuth was originally devised as a simple authorisation mechanism for apps to obtain access tokens for web APIs or other Protected Resources. OAuth 2.0 has flows designed for all application types.

The delivery of the Identity Token from the Authorization Server to the OAuth Client that enables web single sign-on (SSO) for the Resource Owner when they visit the OAuth Client. The id_token typically includes:

The Identity Token is signed, typically with the IDP's RSA Private Key. It may optionally be Encrypted for confidentiality.

Identity Token Contents#

The following Claims are used within the Identity Token for all OAuth 2.0 flows used by OpenID Connect.
The OpenID Connect Identity Token are the same as the default JSON Web Token Claims. Several OpenID Connect JSON Web Token Claims are REQUIRED
CLAIMREQUIREDDescription
issREQUIREDIssuer Identifier for the Issuer of the response. The iss value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.
subREQUIREDSubject Identifier. A locally unique and never re-assigned identifier within the Issuer for the End-User, which is intended to be consumed by the OAuth Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length. The sub value is a case-sensitive string.
audREQUIREDAudience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string.
expREQUIREDExpiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 for details regarding date/times in general and UTC in particular.
iatREQUIREDTime at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
auth_time Time when the End-User authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. When a max_age request is made or when auth_time is requested as an Essential Claim, then this Claim is REQUIRED; otherwise, its inclusion is OPTIONAL. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE OpenID.PAPE auth_time response parameter.)
nonce String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request. If present in the Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authentication Request. Authorization Servers SHOULD perform no other processing on nonce values used. The nonce value is a case sensitive string.
acr Authentication Context Class Reference.
amr Authentication Method Reference.
azp Authorized party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 Client_id of this party. This Claim is only needed when the ID Token has a single audience value and that audience is different than the authorized party. It MAY be included even when the authorized party is the same as the sole audience. The azp value is a case sensitive string containing a String Or URI value.
jti (JWT ID) is an optional claim and is the unique identifier of a JWT Token. When present, the same JWT ID cannot be reused by an issuer. For example, if client01 issues a JWT whose jti is id6098364921, then no other JWT issued by client01 can have a jti value of id6098364921. A JWT with a jti claim identical to another JWT is considered to be a replay attack.

Identity Token MAY contain other Claims. Any Claims used that are not understood MUST be ignored. See Sections 3.1.3.6, 3.3.2.11, 5.1, and 7.4 for additional Claims defined by this specification.

Digital Signatures and Encryption#

Identity Token MUST be signed using JSON Web Signature and optionally both signed and then JSON Web Encryption, thereby providing authentication, Integrity, Non-Repudiation, and optionally, Confidentiality, per Section 16.14. If the Identity Token is encrypted, it MUST be signed then encrypted, with the result being a Nested JSON Web Token, as defined in JSON Web Token.

Identity Token MUST NOT use none as the alg value unless the Response Type used returns no Identity Token from the Authorization Endpoint (such as when using the Authorization Code Flow) and the OAuth Client explicitly requested the use of none at Registration time.

Identity Token SHOULD NOT use the JSON Web Signature or JSON Web Encryption x5u, x5c, jku, or jwk Header Parameter fields. Instead, references to keys used are communicated in advance using Discovery and Registration parameters, per Section 10.

The following is a non-normative example of the set of Claims (the JWT Claims Set) in an ID Token:

  {
   "iss": "https://server.example.com",
   "sub": "24400320",
   "aud": "s6BhdRkqt3",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "auth_time": 1311280969,
   "acr": "urn:mace:incommon:iap:silver"
  }

When using the Hybrid Flow, these additional requirements for the following Identity Token Claims apply to an Identity Token returned from the Authorization Endpoint:

nonce#

REQUIRED. Use of the nonce Claim is REQUIRED for this flow.

at_hash#

Access Token hash value. Its value is the base64 url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the Identity Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string. 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.

c_hash#

Code hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the Identity Token's JOSE Header. For instance, if the alg is HS512, hash the code value with SHA-512, then take the left-most 256 bits and base64url encode them. The c_hash value is a case sensitive string. 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.

More Information#

There might be more information for this subject on one of the following:

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-36) was last changed on 25-Sep-2016 23:40 by jim