OpenID Connect

OpenID Connect adds authentication to OAuth 2.0 with a signed ID token, discovery metadata, and standard claims, enabling single sign-on across applications and providers.

security

Definition

OpenID Connect is an interoperable identity layer built on OAuth 2.0. It defines an ID token, a signed JSON Web Token carrying issuer, subject, audience, and expiry claims, plus discovery metadata and a UserInfo endpoint, allowing clients to verify who a user is rather than only what they may access.

Context and scope

OpenID Connect is used for single sign-on, social login, and enterprise federation. It relies on OAuth 2.0 authorization code flow with PKCE and is distinct from the access tokens used to call APIs.

Common misconceptions

An OAuth access token can be used as proof of user identity
A valid ID token signature is sufficient without checking issuer, audience, expiry, and nonce

Anti-patterns

Sending an ID token to an API as a bearer credential
Accepting tokens issued for another client because only the signature was verified

Related concepts

Related examples

Authoritative source

https://openid.net/specs/openid-connect-core-1_0.html

How OpenID Connect works

OpenID Connect is an identity layer on top of OAuth 2.0. The client runs an authorization code flow with PKCE and requests the openid scope. The authorization server returns an ID token, a signed JWT with iss, sub, aud, exp, and a nonce, plus an access token for APIs. Discovery metadata at /.well-known/openid-configuration publishes endpoints and signing keys, so clients do not hardcode provider details.

When to use OpenID Connect

Use it for single sign-on, social login, and federation across products. The ID token answers “who is this user”; the access token answers “what may this client call”. Validate the ID token’s signature, issuer, audience, expiry, and nonce before creating a session. For APIs, validate access tokens separately and never accept an ID token as an API credential.

Trade-offs

OpenID Connect adds moving parts: discovery caching, key rollover, clock skew, redirect URI registration, and logout semantics that vary by provider. Session management specifications are optional in practice. Vendors differ in claim shape and refresh behavior, so every provider needs testing. The payoff is standardized integration and fewer custom password flows.

Example

import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(
  new URL('https://auth.example.com/.well-known/jwks.json'),
);
const { payload } = await jwtVerify(idToken, jwks, {
  issuer: 'https://auth.example.com',
  audience: 'client-123',
});
if (payload.nonce !== expectedNonce) throw new Error('nonce mismatch');

OpenID Connect is not a replacement for OAuth; it profiles OAuth 2.0. An access token is not a user identity, and an ID token must not be sent to APIs as authorization. A valid signature alone is insufficient, because audience and issuer checks prevent token substitution. Related concepts include OAuth scopes, OAuth 2.0 PKCE, and JWT.