OpenID Connect (OIDC): ID Tokens, Discovery, Claims & Logout

OpenID Connect (OIDC)

OAuth 2.0 is an authorization framework: it lets an app obtain tokens to call APIs. It deliberately doesn't define how the app learns who the user is. OpenID Connect (OIDC) adds that identity layer. With the openid scope, the authorization server (now called an OpenID Provider) also returns an ID token, a signed JWT stating who authenticated, when, how, and for which app.

OIDC is what powers "Sign in with Google/Microsoft/Apple", enterprise SSO with Entra ID, Okta, or Keycloak, and login in most modern applications. It standardizes discovery, signing keys, user claims, and logout, so apps can integrate with any compliant provider using the same library.

TL;DR

OIDC = OAuth 2.0 + an ID token + standard claims, discovery, and a UserInfo endpoint.
Request the openid scope (plus profile, email…) in the authorization code flow with PKCE.
The ID token is for the client to learn who logged in. Don't send it to APIs; use access tokens for that.
Validate ID tokens: signature (JWKS), iss, aud, exp/iat, nonce, and azp when relevant.
Identify users by iss + sub, not by email.
Handle logout with RP-initiated, front-channel, or back-channel logout, and manage local sessions separately from provider sessions.

Quick Example

An authorization request with OIDC scopes:

The token response includes an ID token whose decoded payload looks like:

Validating it with a library (Node.js, jose):

Core Concepts

What OIDC Adds to OAuth

The ID Token

A JWT signed by the provider, containing:

iss: the issuer (the provider).
sub: the subject, a stable, unique user identifier within that issuer.
aud: the audience, your client ID.
exp, iat, and auth_time: timing.
nonce: echoes the value from the request (replay protection).
acr/amr: how the user authenticated (MFA level, methods).
Optional profile claims, depending on scopes and provider policy.

The ID token is meant for the client application. It proves the login to your app. APIs should receive access tokens with the right audience and scopes, not ID tokens.

Validating ID Tokens

Verify the signature with the provider's public keys from its JWKS endpoint (discovered via metadata), and reject alg: none and unexpected algorithms.
Check iss exactly equals the expected issuer.
Check aud contains your client ID (and azp when there are multiple audiences).
Check exp (and iat freshness), allowing small clock skew.
Check nonce matches what you stored for this login.

Certified libraries do all of this; don't write it by hand.

Scopes and Claims

Standard scopes map to claim groups: profile (name, picture, locale…), email (email, email_verified), address, phone, and offline_access (refresh tokens). Providers may return claims in the ID token or only from UserInfo. Enterprise providers often add group, role, or tenant claims. Be careful with large group lists, which bloat tokens.

User Identity and Account Linking

Use iss + sub as the durable key for a user. Emails change, can be reassigned, and aren't always verified: trusting an unverified email claim to link accounts across providers has led to account takeovers. Link identities explicitly, and only on verified emails from trusted issuers.

Discovery and Keys

https://issuer/.well-known/openid-configuration returns metadata: authorization, token, UserInfo, JWKS, and end-session endpoints, supported scopes, and algorithms. Libraries configure themselves from it. Providers rotate signing keys, so cache JWKS and refresh it on an unknown kid.

Sessions and Logout

Logging in via OIDC typically creates two sessions: one at the provider and one in your app (a cookie). Logout options:

Local logout: end your app's session only. The user may be silently logged back in via the provider's session.
RP-initiated logout: redirect to the provider's end_session_endpoint with id_token_hint and post_logout_redirect_uri.
Front-channel and back-channel logout: the provider notifies your app when the user logs out elsewhere. Back-channel (server-to-server logout tokens) is more reliable.

Design logout according to how SSO should behave across your apps.

OIDC vs SAML

New integrations generally choose OIDC. Many providers support both. See SSO.

Best Practices

Use Authorization Code + PKCE

All OIDC logins should use the code flow with PKCE, and a nonce. Implicit and hybrid flows returning tokens in URLs are discouraged. See authorization code with PKCE.

Keep Your Own Session

After validating the ID token, create your application session (an HttpOnly cookie), rather than repeatedly re-validating or storing ID tokens in the browser. Tie session lifetime to your security needs, with re-authentication (max_age, prompt=login) for sensitive actions.

Check Authentication Strength When It Matters

Use acr_values or max_age in requests, and verify acr/amr/auth_time claims, to require MFA or a recent login for high-risk operations.

Minimize Claims

Request only needed scopes, and avoid putting sensitive or bulky data (full group lists, personal data) in tokens that travel widely.

Common Mistakes

Sending ID Tokens to APIs

APIs should validate access tokens intended for them (their audience). An ID token's audience is the client, so accepting ID tokens at APIs breaks audience separation, and can allow token misuse across apps.

Keying Users by Email

Emails aren't stable or globally unique across providers. Use iss + sub, and store email as an attribute.

Skipping Nonce or Audience Checks

Without nonce validation, ID tokens can be replayed. Without aud validation, a token issued for another app at the same provider could log users into yours.

FAQ

What's the difference between OAuth and OpenID Connect?

OAuth 2.0 lets applications obtain access tokens to call APIs on a user's behalf; it's about authorization. OpenID Connect builds on OAuth to provide authentication: an ID token and standard user info, telling the app who the user is. Login ("Sign in with…") uses OIDC.

What's the difference between an ID token and an access token?

An ID token is a JWT for the client application, describing the authenticated user and login event. An access token is a credential for calling APIs (resource servers), with scopes and an audience for those APIs. Clients consume ID tokens, and APIs consume access tokens.

How do I get user information in OIDC?

From claims in the ID token (depending on scopes and provider configuration), or by calling the UserInfo endpoint with the access token. Request profile and email scopes for standard profile and email claims.

How does logout work with OIDC?

Your app ends its local session, and optionally redirects the user to the provider's end-session endpoint to end the provider session (RP-initiated logout). Providers can also notify apps of logouts via front-channel or back-channel logout, so SSO sessions end consistently across applications.