Skip to main content

ID Tokens

In the context of OpenID Connect (OIDC), an ID token is a JSON Web Token (JWT) that contains information about the authenticated user, or subject. ID tokens are central to OIDC’s purpose of enabling authentication. When a client uses OpenID Connect to authenticate a user, the OpenID provider (such as Stalwart Mail Server when configured as an OIDC server) issues an ID token to the client, confirming the identity of the user who has logged in.

The ID token is a compact, secure token that includes various claims (pieces of information) about the user and the authentication process. It allows the client to verify the user’s identity without the need to handle sensitive information like passwords directly. In contrast to OAuth, which focuses on authorization (granting access to resources), OIDC with ID tokens specifically addresses authentication, allowing services to confirm who the user is.

An ID token typically includes the following information, known as claims:

  • iss (Issuer): The URL of the OpenID provider that issued the token.
  • sub (Subject): A unique identifier for the authenticated user. This claim identifies the user across different sessions and services.
  • aud (Audience): The intended recipient of the token, which is usually the client application.
  • iat (Issued At): The timestamp indicating when the ID token was issued.
  • exp (Expiration Time): The time after which the ID token is no longer valid.
  • nonce: A unique value generated by the client to prevent replay attacks.
  • auth_time: The time when the user was authenticated.

Additionally, ID tokens may include other optional claims, such as the user’s email address, name, and profile information, depending on the configuration and the scope of the authentication request.

ID vs Access Tokens​

Although ID tokens and access tokens are both used in OAuth 2.0 and OpenID Connect, they serve different purposes and contain different information:

  • ID Token (Authentication): An ID token is designed to authenticate the user and confirm their identity. It contains claims that describe the user and the authentication event (such as when the user logged in and the identity provider that verified them). ID tokens are primarily consumed by the client to understand who the user is.
  • Access Token (Authorization): An access token, in contrast, is used to authorize access to protected resources. It grants the client permission to access specific resources on behalf of the user. Access tokens contain scopes and permissions, defining what actions the client can perform (such as reading email or accessing a user’s profile data). Access tokens are consumed by resource servers (such as APIs) to control access to protected data.

In short, the ID token proves the identity of the user, while the access token authorizes access to resources. Both tokens can coexist in an OIDC authentication flow, with the ID token being passed to the client to confirm the user’s identity and the access token being sent to resource servers to grant access to specific resources.

JSON Web Token (JWT)​

ID tokens are typically encoded as JSON Web Tokens (JWTs). A JWT is a compact, URL-safe token format that consists of three parts:

  • Header: Contains metadata about the token, including the type of token (JWT) and the signing algorithm used (e.g., RS256).
  • Payload: Contains the claims, which include the information about the user and the authentication event.
  • Signature: A cryptographic signature that ensures the token's integrity. The signature is created by combining the header and payload and signing them with a private key.

The JWT format is both efficient and secure, allowing the ID token to be transmitted between parties (such as the OpenID provider and the client) in a compact and verifiable way.

Signing and Encryption​

To ensure the security and integrity of the ID token, OpenID Connect supports both signing and encryption.

Signing​

ID tokens are usually signed to prevent tampering and to allow the client to verify that the token was indeed issued by a trusted OpenID provider. The signature is created using a private key held by the provider, and the client can verify the signature using the corresponding public key. For example, in the RS256 signing algorithm (RSA with SHA-256), the OpenID provider signs the token with its private key, and the client verifies it using the public key, often obtained from the provider’s .well-known endpoint. Signing ensures that the ID token has not been altered in transit and that it comes from a legitimate source.

Encryption​

In some cases, ID tokens may also be encrypted for additional confidentiality. When encryption is used, the payload of the ID token is encrypted using the client’s public key, ensuring that only the intended recipient (the client) can decrypt and read the token’s claims. Encryption is less common than signing but may be required in sensitive environments where the content of the ID token itself needs to be protected from intermediaries.

Summary​

ID tokens play a crucial role in OpenID Connect by enabling authentication and providing information about the user to clients in a secure, verifiable manner. Unlike OAuth access tokens, which are used for authorization, ID tokens are specifically designed to authenticate the user and are issued as JWTs, ensuring that they are compact, secure, and verifiable. Through signing and, optionally, encryption, ID tokens provide both integrity and confidentiality, ensuring that the authentication process is both secure and trustworthy. Stalwart Mail Server, when configured as an OpenID provider, can issue ID tokens that allow clients to securely identify users and provide them with seamless access to resources and services.