LDAPWiki: Identity Token

Overview#

Identity Token (id_token) is a signed (JSON Web Signature) and possibly Encrypted (JSON Web Encryption) 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 Connect 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 Client request an Identity Token in OpenID Connect with an Authentication Request

Additional Claims for the Authenticated End-User may be available by submitting the Access_token to the userinfo_endpoint

Features of the Identity Token:#

is a JSON Web Token (JWT)
Asserts the Digital Identity of the user, called subject in OpenID (sub).
Specifies the issuing authority (iss).
Is generated for a particular audience, i.e. client (aud).
May contain a nonce (nonce).
May specify when (auth_time)
May specify how, in terms of strength (acr), the user was authenticated.
Has an issue (iat) and expiration time (exp).
May include additional requested details about the subject, such as name and email address.
Has a JSON Web Signature (JWS), so it can be verified by the intended recipients.
May optionally have JSON Web Encryption (JWE) for confidentiality.

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
at_hash
c_hash

Identity Token Claims #

The ID token resembles the concept of an identity card, in a standard JWT format, signed by the OpenID Provider (OP). To obtain one the client needs to send the user to their OP with an authentication request.

The Identity Token Claims are used within the Identity Token for all OAuth 2.0 flows used by OpenID Connect.

Digital Signatures and Encryption #

Identity Token MUST be signed using JSON Web Signature and MAY 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 Openid-configuration 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"
  }

id_token Response_type #

The intended purpose of the id_token when supplied as the response_type parameter in an OAuth 2.0 Authorization Request, a successful response MUST include the parameter id_token.

The Authorization Server SHOULD NOT return an OAuth 2.0 Authorization Code, Access Token, or Access Token Type in a unsuccessful response Authorization Response.

If a redirect_uri is supplied, the User-agent SHOULD be redirected there after granting or denying access.

The request MAY include a OAuth state parameter, and if so, the Authorization Server MUST echo the OAuth state parameter value as a response parameter when issuing either a successful response or an OAuth Error response. The default Response Mode for this Response_type is the Fragment Response Mode encoding and the query encoding MUST NOT be used. Both successful and error responses SHOULD be returned using the supplied Response Mode, or if none is supplied, using the default Response Mode.

Returning the id_token in a fragment reduces the likelihood that the id_token leaks during transport and mitigates the associated risks to the privacy of the Resource Owner.

More Information#

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

[#1] - OpenID Connect explained - based on information obtained 2015-12-03