Authorization Basics

ID Token: Concept, Purpose, Way It Works

Find out what the ID token is and what purpose it has. Check how to acquire the ID token and how to use it.

ID Token in a Nutshell

The ID token is the key concept in OpenID Connect (OIDC). OIDC is a simple identity layer built on top of OAuth 2.0 that provides authentication and identity assertion.

The ID token is a security token that includes claims regarding the authentication of the user by the authorization server with the use of an OAuth client application. The ID token may also include other requested claims. It is created on the authorization server’s side to encode the user’s authentication information. Unlike access tokens intended to be consumed by the resource server, ID tokens are intended to be consumed by the third-party application.

ID tokens are for storing user data and delivering it to the client application. Since the client application receives the ID token only after the user gets authenticated, the ID token becomes a proof of the user’s identity to the client. Also, since the ID token can carry basic profile information on the user, it can serve as a source of user data that the client can use for different purposes (for example, to enhance the user experience).

ID Token vs Access Token

The OIDC flow returns not only the ID token but also the access token to ensure compatibility with OAuth and support identity authorization scenarios. The ID token is for the client’s consumption and can be passed around its different components as the representation of the successful authentication and the store of user’s profile information. Yet, it should not be used to access APIs. For requesting the access to protected resources, you still need to use access tokens. Unlike the ID token, the access token is not intended to carry the user data (except for ID passed as the sub claim) but to transit authorization information, such as scopes determining actions allowed to be taken by the client on the API. Access tokens are for access protected API resources and ID tokens should not used for API access.

ID Token Structure

Typically, the ID token uses the JSON format and takes the form of JSON Web Token (JWT). Its JSON payload is signed with the private key of the issuer (Cloudentity) and can be verified by the client.

The ID token includes defined property names that constitute the information on the user to be consumed by the client. Required property names are as follows:

  • Authorization server’s identifier (iss)
  • User’s identifier (sub)
  • Client’s identifier (aud)
  • Expiration time of the ID token (exp)
  • Time at which JWT was issued (iat)

Sample ID Token

{
  "acr": "1",
  "aid": "default",
  "amr": [
    "pwd"
  ],
  "aud": "default-demo",
  "auth_time": 1631696786,
  "email": "",
  "email_verified": false,
  "exp": 1631700395,
  "iat": 1631696795,
  "idp": "default",
  "iss": "https://cloudentity-user.authz.cloudentity.io/cloudentity-user/default",
  "jti": "261e658f-b40a-42f5-9e98-3eb022dfccac",
  "name": "John Doe",
  "nbf": 1631696795,
  "nonce": "c50rf23o825ulrjk38qg",
  "rat": 1631696795,
  "scp": [
    "email",
    "openid",
    "profile"
  ],
  "st": "public",
  "sub": "user",
  "tid": "cloudentity-user"
}

Enable ID tokens in Cloudentity

If you want to receive ID tokens, you need to configure your application settings accordingly. See the video for the guidelines on how to enable the id_token response type and the openid scope for your application. Alternatively, check the instructions in Configure response types and Configure scopes.

Configure Response Types

To enable the id_token response type, take the following steps:

  1. In Cloudentity, navigate to the workspace where your application can be accessed for configuration. Select the application and go to its OAuth view.

  2. Navigate to Response Types and add id_token from the drop-down list. Save the changes.

Configure Scopes

To be able to receive ID tokens, your client needs to have the openid scope enabled. With the openid scope enabled, your client application is returned both ID token and access token.

To enable the openid scope, the the following steps:

  1. In Cloudentity, navigate to the workspace where your application can be accessed for configuration. Select the application and go to its Scopes view.

  2. Select the Profile service to expand the list of available scopes and select the openid toggle.

Configure TTL

TTL specifies how long a particular ID token is valid and how long it can be used by the client application.

In Cloudentity, there are TTLs for ID tokens predefined per workspace (authorization server). You can modify them by entering a particular workspace and navigating to Auth Server > Tokens > TTL > ID token TTL.

ID Token Encryption

A client can choose to receive encrypted ID Tokens. The client that receives the encrypted ID Token can choose what information to share with the browser, for example via an API call. It also prevents the browser from leaking Personally Identifiable Information (PII) and protects against the ID Token being logged and having its content exposed. This is also a requirement for Financial-grade API (FAPI).

ID Token Encryption is done following the JSON Web Encryption specification - RFC-7516.

There are two serialization mechanisms for JWEs as per RFC7516:

  • a compact, URL-safe serialization called the JWE Compact Serialization
  • a JSON serialization called the JWE JSON Serialization.

Cloudentity uses the JWE Compact Serialization.

To enable ID Token Encryption in Cloudentity the client must provide a public key to be used for encrypting the Content Encryption KEY (CEK) using their public key. Cloudentity encrypts the ID Token using this public key and the ID Token encryption algorithm configured at client level.

  1. In the workspace navigate to Auth Settings > Tokens > Signing and encryption. Under Encryption settings turn on ID TOKEN ENCRYPTION by toggling the switch.

  2. Then in the client application in Cloudentity, add the JSON Web Key to the JSON Web Key Set.

  3. Under ID Token key encryption algorithm set the correct algorithm for encrypting the key.

  4. Under ID Token content encryption algorithm set the algorithm for content encryption.

How It Works

The client application requests the authorization from Cloudentity. Next, the user needs to authenticate with their IDP. Only then Cloudentity can respond with the user’s identity context in the form of the ID token.

The diagram illustrates how to obtain the ID token along the authorization process using the Cloudentity hybrid flow.

[mermaid-begin]
sequenceDiagram participant User participant Client application participant Cloudentity tenant participant API activate User User->>Client application: Access activate Client application Client application->>Cloudentity tenant: Request authorization activate Cloudentity tenant deactivate Client application Cloudentity tenant->>User:Display consent User->>Cloudentity tenant: Authenticate deactivate User Cloudentity tenant->>Client application: Issue authorization code and one or more parameters activate Client application Client application->>Cloudentity tenant: Request token note right of Client application: scope = openid & response_type = ID token Cloudentity tenant->>Cloudentity tenant: Verify the authorization code Cloudentity tenant->>Client application: Return token deactivate Cloudentity tenant

Validate an ID Token

The ID token is a signed JWT, that is, JWS. It is signed using the server’s private JWK. Optionally, it can be both signed and encrypted. Since each ID token is an encoded and signed JWT, its validation needs to start with decoding all its three parts with base64url decode.

After decoding the token parts, you need to verify the following:

  • Signature: Check if the signing algorithm indicated in the alg header parameter is as expected and verify the signature with the public key.
  • Standard claims: After decoding the payload, verify if it contains relevant claims with expected values.