§01  Identity & Access

An OpenID Connect ID Token Is Not a User Profile, Or How to Read It Properly

Identity & Access

Fedora7 login / Reiskeks, CC BY-SA 3.0

An OpenID Connect ID token is not a user-identity data blob. It's a compact cryptographic artifact that only speaks to authentication when the issuer, subject, audience, freshness, and session-binding claims all resolve to expected values. Understand that, and any relying party can tell a good token from a useless fake.

What an ID Token Is

At the core, an OpenID Connect ID Token is a JSON Web Token. OpenID Connect Core 1.0 defines it as a security token that contains claims about the authentication event. It may also contain other claims, depending on the exchange flow.

But the ID token's reason for being, and its only guaranteed content, are the core three: issuer, subject, and audience. Beyond that, the token claims depend on request parameters, flow type, and the provider's issuer profile.

OpenID describes the access token hash value as the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access token, using the hash algorithm associated with the ID Token’s JWS alg.

The Identity Core: iss, sub, aud

The issuer, subject, and audience claims are the identity foundations in an ID Token. These claims bind the cryptographic token to the provider that issued it, the end-user identity that the token represents, and the client that is the coin of these tokens.

The iss claim identifies the issuer, the authority or service that generated the token. This tells the relying party which verification profile and claim expectations to apply.

The sub claim is the identifier for the user. OpenID Connect explicitly calls this out as the subject identifier, the stable user-centric reference for this authentication event. In every flow, this is the key user identity claim.

Finally, aud is the audience claim, telling the relying party which clients are allowed to accept this token. This claim can include multiple identifiers, each representing a valid audience for this token.

Freshness and Replay Checks: exp, iat, nonce

Authentication tokens are bearer tokens — anyone can read or present them. That's why an ID token must include a set of freshness, issued-by, and replay-protection claims to defend against attacks.

The exp claim provides the expiration time, after which a client must reject the token as stale. The iat claim shows the issued-at time, giving the relying party a timestamp to compare to the current time and any reasonable tolerance.

OpenID Connect defines a nonce claim to ensure that a token can be attributed to a specific authentication event. If the client sends a nonce parameter in the authentication request, the token must include a matched nonce value. Clients must verify this to identify replay attacks and prevent one token being used in multiple client sessions.

Proof of the Right Authentication: at_hash, acr, amr

ID tokens can also include claims that attach them to a specific authentication event and give clarity to the assurance level of the authentication.

The at_hash claim, when present, binds an ID token to a specific access token. It describes an access token hash value, required when an access token and ID token are both issued in the implicit flow.

Two forms of assurance are also possible. The acr claim is an Authentication Context Class Reference, providing a reference to the documented authentication context or class being used. It can take multiple semantic values across different flows, and any relying party must understand its profile's usage and available values.

Finally, the Authentication Methods References (amr) claim is a JSON array describing the specific authentication methods used.

What Must Match Across Responses

OIDC specifications introduce tables of claims to verify in an ID token, including iss, sub, aud, nonce and more. But claims also matter in the broader interaction.

Most importantly, the sub value in the ID token must match the sub value in the userinfo response. The user claims fetched by the client should directly relate to the subject ID in the token.

Audience claims also drive consistency checks. In a typical scenario, the full list audiences in the token and the client identifier should match; not verifying this leads to acceptance of tokens intended for other clients.

The Common Failures

Comparing an ID token against its own properties is the minimum check. But the most dangerous failure is a relying party that ignores those verifications. Here are some of the places developers could fail:

• Checking sub-fields of the token without verifying the signature, or trusting the claims within without verifying hash.
• Skipping issuer and audience verification. Every token must be subject to those tests.
• Taking nonce as optional in a flow where the parameters said nonce was required, or treating the at_hash value as an optional hash.
• Interpreting acr and amr as stronger authentication guarantees than the spec text reveals.

The Token Is Only As Good As What You Checked

When relying on an OpenID Connect token, start with the question of what the token claims, and then check it against your own understanding of the request and your configuration. Verify the presence of the right claims, verify their values, and model out any validity checks according to the expected fulfillment of the token type and the security profile it was fulfilled in.

It's only then, when each property of the token has been checked and any matches and references are valid, that the token is trustworthy. Without this strategy, an ID token can never be applied to a trusted authentication.