Skip to main content

ID Token

OpenID Connect Core 1.0 incorporating errata set 2 - ID Token (openid.net)

An ID Token in OpenID Connect is a digital security document, specifically a JSON Web Token (JWT) (datatracker.ietf.org), that acts as proof a user has been authenticated by an OpenID Provider (OP). It contains claims (information) about the user and the authentication event.

OpenID Connect introduces the ID Token as an extension to OAuth 2.0 that allows users to be authenticated. The ID Token contains information in form of Claims about the authentication.

ID Tokens are signed using JWS (datatracker.ietf.org) and optionally the signed token is encrypted using JWS and JWE (datatracker.ietf.org) to provide integrity, authenticity, and confidentiality.

Example of an ID Token​

ID Token
{
  "iss": "https://server.example.com", // Issuer that created and signed this token
  "sub": "24400320", // Subject for the End-User whom the token refers to
  // Audiences who the ID Token is intended for as
  // one or multiple OAuth 2.0 client_id
  "aud": [
    "170084138865393921",
    "170084137741451521"
  ],
  "exp": 1311281970, // Expiration time (Unix Timestamp)
  "iat": 1311280970, // Issued at (Unix Timestamp)
  "auth_time": 1311280969, // Time when end-user authentication occurred (Unix Timestamp)
  "nonce": "n-0S6_WzA2Mj", // Associates Client session to token
  // Identifies the Authentication Context Class or Level of Assurance that
  // the authentication performed satisfies
  "acr": "urn:mace:incommon:iap:silver",
  // Authentication Methods References array
  "amr": [
    "user", // User presence test
    "mfa" // Multiple-factor authentication
  ],
  // Authorized party as OAuth 2.0 client_id to which the ID Token was issued
  "azp": "170084138898948353",
  "at_hash": "", //Authorized Party
  "c_hash": "", // Code hash value mitigating token substitution (Hybrid Flow)
}

ID Token vs. Access Token​

While both are tokens, they serve distinct purposes in the OAuth 2.0 and OIDC ecosystem.

FeatureID TokenAccess Token
PurposeAuthentication (Who is the user?)Authorization (What can the user do?)
AudienceClient ApplicationResource Server (API)
FormatAlways a JWTCan be any format (often opaque)
ContentUser identity claims (sub, name, email)Permissions, scopes, user ID
Client UseValidate signature, read claims for user info.Treat as opaque, send to API in Authorization header.

How to use ID Tokens​

ID Tokens are a proof of authentication for the Client, while Access Tokens are for accessing a Resource Server (eg, API). The client application is the intended audience of an ID Token to get more information about who authenticated. During an OIDC flow, the client also receives an Access Token and uses the Access Token to make requests to a protected resource server (API). The client should not attempt to inspect the Access Token.

The information provided in the ID Token is crucial to prevent a class of attacks called Token Substitution (openid.net), where an attacker "copy and paste" the attacker's token into a http message from another user. Clients must retain the sub, c_hash, and at_hash that were issued during authentication in the ID Token to validate responses from the Authorization Server (eg, UserInfo Response).

Don't send ID Tokens to an API. APIs should be protected using Access Tokens. Sending an ID Token to an API as a bearer token is a common mistake. The API should require an Access Token and validate its scope and permissions.

The ID Token can also serve as protection against denial of service attacks during logout. The client should send the ID Token in theid_token_hint to the end_session_endpoint when initiating a logout (openid.net).

Resources​