OpenID Connect: Login on Top of OAuth

OpenID Connect adds an ID token that tells the app who the user is, which OAuth alone never did.

OpenID Connect, or OIDC, is a layer on OAuth 2.0 that lets an application sign a user in. When the client includes the openid scope in the code flow, the authorization server returns an ID token alongside the access token: a JWT, addressed to the client, that states who the user is and when they signed in. The client can also call the server's UserInfo endpoint with the access token for more profile details.

json

{
  "iss": "https://login.photos.example",
  "sub": "248289761001",
  "aud": "printing-app",
  "exp": 1791370800,
  "nonce": "n-0S6_WzA2Mj",
  "iat": 1791367200,
  "auth_time": 1791367190,
  "name": "Maria Silva",
  "email": "[email protected]"
}

An illustrative decoded ID token payload, with the claims the client must check

The claims. iss is the provider, sub the user's stable id at that provider, aud the client the token was issued to, and exp its expiry. nonce is a random value the client sent at the start of the flow; finding it here ties the token to that request and stops an old token being replayed.

The client checks it. Unlike an access token, the ID token is for the client, and the client validates it like any JWT: signature, iss, aud equal to its own client id, exp, and nonce.

Who the user is. The pair of iss and sub identifies the user. An email address can change or be reused, so it should not be the key an application stores.

UserInfo. The client calls the provider's UserInfo endpoint with the access token to get profile claims such as name and picture, according to the scopes granted, such as profile and email.

Same flow. OIDC reuses the code flow with PKCE; the only differences are the openid scope, the nonce and the extra token in the response.

← → move through sections and cards