OpenID Connect (OIDC) is OAuth plus an authentication layer.
OAuth answers “can this client call this API?”
OIDC answers:
“Who is the user?” and “How did they authenticate?”
It does this by introducing a new token type (ID Token) and standardizing discovery/metadata so clients can configure themselves consistently.
The important artifacts
- ID Token: a JWT that represents the authentication event
- Access Token: used for APIs (not necessarily a JWT)
- UserInfo response: optional endpoint to fetch user claims
- Discovery document:
/.well-known/openid-configuration - JWK Set: keys used to validate JWT signatures
Diagram: OIDC Authorization Code flow
Diagram
Two OIDC-specific pieces to notice:
scopeincludes openidnoncebinds the authentication response to the client’s session
ID Token: what it is (and what it is not)
An ID token is a signed statement from the OP about an authentication event.
Typical claims:
iss(issuer)sub(subject / user id)aud(client id)exp,iatnonce(if used)- optional:
email,name,groups(depends on scopes/claims mapping)
ID token is not an API authorization token
Do not send ID tokens to APIs as bearer tokens. Use access tokens for APIs.
Validation checklist (must-do)
When validating an ID token:
- Verify signature using the correct JWK
- Verify issuer matches expected OP
- Verify audience contains your client id
- Verify expiration
- Verify nonce matches the one you generated
If you don’t validate these, you’re not doing OIDC—you’re doing “JWT-shaped hope.”
Discovery and metadata (why OIDC scales)
OIDC standardizes how clients learn endpoints:
- authorization endpoint
- token endpoint
- JWKS URI
- supported algorithms
This makes multi-tenant or multi-environment setups manageable.
Common failure modes
invalid_nonce(nonce not stored/replayed correctly)- wrong issuer (mixing Okta “org” issuer vs custom authorization server issuer)
- key rotation causes signature verification failures if JWKS caching is wrong
- using ID token where access token should be used
Security hardening
- Use Authorization Code + PKCE
- Keep sessions and refresh tokens protected
- Prefer short-lived access tokens
- Consider token binding (DPoP/mTLS)
Where to go next
- OAuth foundations: /topic/specifications/oauth-2-0-roles-flows-and-tokens
- OAuth best practices: /topic/specifications/oauth-2-1-best-practices-pkce-rotation-threat-model
- JWT/JOSE: /topic/specifications/jwt-and-jose-jws-jwe-jwk-the-token-toolbox
