OpenID Connect (OIDC)

What is OpenID Connect?

OpenID Connect (OIDC) is an identity protocol layered on top of OAuth 2.0. OAuth on its own answers "what is this client app allowed to do on the user's behalf?" — it deliberately says nothing about who the user is. OIDC fixes that by adding an ID token that the identity provider signs and returns alongside OAuth's access token.

OIDC is the protocol behind most "Sign in with Google / Apple / Microsoft" buttons, behind modern enterprise SSO into web and mobile apps, and behind CIAM platforms like Auth0, Clerk, and FusionAuth.

How OIDC works

The recommended flow for almost every app today is the Authorization Code flow with PKCE:

1. Your app redirects the user to the IdP's authorize endpoint with response_type=code, a list of scopes (openid email profile), and a PKCE code challenge.
2. The IdP authenticates the user and asks for consent (for first-party apps this is usually invisible).
3. The IdP redirects back to your app's redirect_uri with a short-lived authorization code.
4. Your app's backend exchanges the code at the token endpoint for an ID token, an access token, and (optionally) a refresh token.
5. Your app verifies the ID token's signature using the IdP's public JWKS keys, checks iss, aud, exp, and nonce, and creates a local session.

The ID token is a JWT containing standard claims (sub, email, name, auth_time) and any custom claims the IdP is configured to issue.

Why OIDC over SAML for new work

• Discovery. /.well-known/openid-configuration exposes every endpoint and key — no manual XML metadata exchange.
• JSON, not XML. JWTs are easy to parse, debug, and propagate across services.
• Mobile-native. SAML was designed for browsers. OIDC works cleanly in native mobile apps via the system browser plus PKCE.
• Built on OAuth. You get authorization (scopes, access tokens for APIs) and authentication in one protocol family.

Use SAML when you must integrate with an older SP that doesn't support OIDC; otherwise prefer OIDC.

Common pitfalls

• Treating the access token as an ID document. The access token is opaque to your client and meant for APIs. Never make authentication decisions from its contents — use the ID token.
• Skipping signature verification. "It came from the IdP redirect" is not verification. Always verify the JWT signature against the IdP's JWKS.
• Not validating aud and iss. A token signed by your IdP for a different client is still cryptographically valid but not for you.
• Implicit flow. The old implicit flow (response_type=id_token token) is deprecated. Use Authorization Code + PKCE.

FAQ

Is OIDC the same as OAuth?

No. OAuth 2.0 is an authorization framework. OIDC is an identity layer built on top of it. You can use OAuth without OIDC (for API access delegation), but you should not use OAuth alone for authentication.

Do I need a refresh token?

For long-lived sessions in web apps, yes — store it server-side. For SPAs, prefer short-lived access tokens with silent re-authentication via the IdP session, or use the refresh token rotation pattern.

What is PKCE?

Proof Key for Code Exchange. It binds the authorization request to the token exchange so an intercepted authorization code cannot be redeemed by an attacker. Required for public clients (SPAs, mobile) and recommended for all clients.