ID Tokens & Claims

The ID Token is a core component of OpenID Connect (OIDC). Think of it as a digital ID card for the user.

Its main purpose is to provide your application with verified identity information about the end-user who just logged in. It tells you who the user is.

Crucially, an ID Token is different from an Access Token. While an Access Token is for authorization (what you can do), an ID Token is for authentication (who you are).

Every ID Token is a JSON Web Token (JWT). JWTs are a compact, URL-safe means of representing claims to be transferred between two parties.

Being a JWT means ID Tokens have a specific, standardized structure that allows for secure and verifiable information exchange.

This standardized format makes it easy for different systems to understand and process identity information.

A JWT consists of three parts, separated by dots (.):

• Header: Describes the token's type and the signing algorithm.
• Payload: Contains the actual "claims" (identity information).
• Signature: Used to verify the token hasn't been tampered with.

Both the Header and Payload are Base64Url-encoded JSON objects. The Signature is created using the encoded Header, Payload, and a secret key.

The most important part of the ID Token for identity is its Payload. This is a JSON object containing various statements about the user and the authentication event.

These statements are called claims. Each claim is a key-value pair, like "name": "Jane Doe". They tell your application specific details about the user.

Claims are standardized by OIDC, but can also include custom information depending on the OpenID Provider (OP).

Certain claims are essential for an ID Token to be valid and useful:

• iss (Issuer): Identifies the entity that issued the token. This is typically the URL of the OpenID Provider.
• sub (Subject): A unique identifier for the end-user. It's usually a string that's unique to the user within the issuer's system.
• aud (Audience): Identifies the recipient(s) the JWT is intended for. This must be your application's client_id.

ID Tokens also include important time-related claims:

• exp (Expiration Time): The time after which the ID Token MUST NOT be accepted. It's a Unix timestamp.
• iat (Issued At Time): The time at which the ID Token was issued. Also a Unix timestamp.
• auth_time (Authentication Time): The time when the end-user last authenticated. Useful for session management policies.

Always check exp to ensure the token is still valid!

The nonce claim is a unique, one-time value generated by your client application and sent to the Authorization Server.

When the ID Token is returned, it will include the same nonce. Your application then verifies that the nonce in the token matches the one it sent.

This helps mitigate replay attacks, ensuring that the ID Token wasn't captured and reused by a malicious party.

Beyond the core claims, ID Tokens often carry additional user information, known as "User Profile Claims". These are usually requested via scopes.

Common examples include:

• name: The user's full name.
• given_name: The user's first name.
• family_name: The user's last name.
• email: The user's email address.
• picture: A URL to the user's profile picture.

These claims provide a rich set of data for your application.

When you receive and decode an ID Token, its payload might look something like this (simplified JSON):

{
  "iss": "https://accounts.coddykit.com",
  "sub": "user_id_xyz_789",
  "aud": "my_mobile_app_123",
  "exp": 1678886400,
  "iat": 1678882800,
  "auth_time": 1678882700,
  "nonce": "a1b2c3d4e5",
  "name": "Coddy User",
  "email": "coddy.user@example.com"
}

Each key-value pair is a specific claim providing identity details.

You've learned about the different claims within an ID Token.

Which of the following claims is primarily used to identify the recipient (your client application) for whom the ID Token is intended?

Great job! You've successfully explored the core of OpenID Connect: the ID Token and its claims.

• ID Tokens are JWTs carrying identity data.
• They contain a Header, Payload (claims), and Signature.
• Key claims like iss, sub, aud, exp, iat, and nonce are crucial.
• User Profile Claims like name and email enrich the identity.

Next, we'll dive into the different OIDC flows that use these tokens!