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

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 using JSON Web Signature and MAY optionally be Encrypted with JSON Web Encryption 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 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"
  }

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

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 successful response to the grant request. 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 its value as a response parameter when issuing either a successful response or an error response. The default Response Mode for this Response_type is the fragment 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:

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-44) was last changed on 26-Jun-2017 08:32 by jim