JA

Understanding OpenID Connect with diagrams

Here is what this post covers:

Introduction

In the post before last I walked through the OAuth authorization code flow, and in the previous post I covered PKCE, both with the example of a photo print service importing photos from Instagram. In both posts the question was “may the print service read my photos?”

This time, the same print service adds “Log in with Instagram”. Users can log in with their Instagram account without signing up, and their order history is tied to that account.

What the service needs here is not “what may I do” but “who just logged in”. OAuth was not designed to answer that, so OpenID Connect (OIDC) is layered on top of it. This post sorts out what OIDC adds to OAuth, using the same example and sequence diagrams as before.

The cast and the domains are the same as in the previous posts. Whether the real Instagram supports OIDC is beside the point; here, the authorization server (auth.example.net) is assumed to support it.

What goes wrong when you log in with OAuth alone

At the end of the flow from the previous posts, the print service holds an access token. An access token is like a building pass that says “you may read photos”. It does not say who its holder is, and the print service may not even be able to read what is inside it.

If you still want to know who the user is, the usual approach is to call a profile API with the access token and log the user in with the ID it returns. This approach has two problems.

First, the shape of the profile API differs from service to service. You need one implementation for Instagram, another for X, another for Google.

Second, the party that receives an access token cannot check whom the token was issued to. For example, if your service logs users in with an access token handed over from a browser or a mobile app, it cannot tell when someone brings in a token issued to a different app. Whoever brings it in gets logged in as the token’s owner.

OIDC solves both by defining a dedicated container that says who logged in, along with rules for passing it around.

What OpenID Connect is

OpenID Connect is a specification for authentication (checking who logged in) that sits on top of OAuth 2.0. It does not build a new flow from scratch. It adds a few parameters and a token to the authorization code flow from the previous posts.

The OAuth 2.0 authorization code flow is the base layer, with PKCE and OpenID Connect sitting side by side on top of it. PKCE stops authorization codes from being intercepted, and OpenID Connect tells the app who logged in. OAuth 2.0 itself decides what the app may do. PKCE (last time) code_verifier code_challenge Stops code interception OpenID Connect (this time) scope=openid, ID token, nonce UserInfo, Discovery Tells the app who logged in OAuth 2.0 authorization code flow Authorization code, access token Decides what the app may do

PKCE and OIDC are both extensions to the same authorization code flow, and you can use them together. PKCE protects the handoff of the authorization code, while OIDC adds a way to say who the user is, so their roles do not overlap.

OIDC uses different names for the OAuth roles.

Name in OIDCName in OAuthIn the photo print example
OP (OpenID Provider)Authorization serverInstagram's authorization server (auth.example.net)
RP (Relying Party)ClientThe photo print service (print.example.com)
End userResource ownerYou, logging in with Instagram

The OP is the side that vouches for who the user is, and the RP is the side that relies on that and logs the user in. It is also called an IdP (Identity Provider), but this post sticks with OP.

ID tokens and access tokens

The biggest addition in OIDC is the ID token. When the RP exchanges the authorization code, the OP returns an ID token along with the access token. The RP now holds two tokens.

Where the ID token and the access token go. The OP hands both to the RP. The RP reads the ID token to learn who logged in, and the ID token stops there. Only the access token is sent to the API. OP auth server RP client API resource server ID token Access token Not sent Access token Issues both Learns who Checks access

The two tokens have different readers and different destinations.

ID tokenAccess token
Like aPhoto IDBuilding pass
SaysWho logged inWhat the app may do
Read byRPAPI (resource server)
AudienceRP (its client_id is inside)API
FormatAlways a JWTUp to the OP (not always a JWT)

The RP reads the ID token, and that is where the ID token’s job ends. When calling an API, send only the access token, never the ID token. The reverse also holds: as “What goes wrong when you log in with OAuth alone” showed, do not use an access token as proof of who the user is.

The ID token names its audience (the RP’s client_id) and carries the OP’s signature. So the RP can check on its own that the token was issued by the right OP and addressed to itself. That solves the second problem from earlier, where a token issued to a different app is brought in.

The authorization code flow with OIDC

The big picture

In the diagram, the parts OIDC adds are green and the PKCE part from last time is purple. This time the print service is a web app, so the redirect URI is https://print.example.com/callback.

Sequence diagram of the whole OpenID Connect authorization code flow. The green steps 2, 4, 10, 11 and 12 are what OIDC adds; the purple step 9 is PKCE from last time. In 2 the RP creates state, code_verifier and nonce, and in 4 it sends the authorization request with scope=openid and the nonce. In 10 the OP returns an ID token and an access token, and in 11 the RP validates the ID token and the login is done. In 12 the RP can fetch more attributes from UserInfo, and in 13 it calls the API with the access token. User (browser) RP / Client (photo print) print.example.com OP / Auth server (Instagram) auth.example.net Resource server (Instagram API) api.example.net 1 Clicks "Log in with Instagram" 2 Create and store state, verifier, nonce 3 Open the auth screen 4 Auth request (scope=openid, nonce) 5 Show login and consent 6 Log in and allow 7 Redirect (with code) 8 Pass code and state 9 code + verifier 10 ID token + access token 11 Validate ID token → logged in 12 UserInfo (if needed) 13 API request with the token

The steps are almost the same as in the previous posts. The differences are creating a nonce (2), adding scope=openid and the nonce to the authorization request (4), getting an ID token back (10), and the RP validating it to finish the login (11). UserInfo in step 12 is only for when you need attributes that are not in the ID token.

If all you need is login, you can skip the API call in step 13. If you also want to read photos, you can use the access token from the same flow as is.

The authorization request (step 4 in the diagram)

The request the browser sends to the OP looks like this (line breaks added for readability).

GET /authorize?response_type=code
  &client_id=s6BhdRkqt3
  &redirect_uri=https%3A%2F%2Fprint.example.com%2Fcallback
  &scope=openid%20profile%20email%20photos.read
  &state=35ce
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256 HTTP/1.1
Host: auth.example.net

Compared with the request from the post before last, this adds openid, profile and email to scope, the nonce, and the two PKCE parameters from last time.

ParameterMeaning
scope=openidThe signal that this is an OIDC request. Without it the request is treated as plain OAuth and no ID token comes back
profile, emailThe attributes you want, such as name and email address. These scopes are defined by OIDC
nonceA single-use random value created by the RP. The OP puts it into the ID token as is (more on this below)

photos.read is the scope for reading photos from the post before last. You do not need it if all you want is login.

The token response (step 10 in the diagram)

The request that exchanges the authorization code combines the ones from the two previous posts. Since this is a web app, it sends the client secret, and it also sends the PKCE code_verifier. What OIDC changes is the response.

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.eyJpc3Mi...(truncated)"
}

The only change from the response in the post before last is the extra id_token. That string is the ID token, and we look inside it below.

Three single-use values

The RP now creates three single-use values in step 2. All of them are random, but who checks them, where, and what they prevent are different.

ValueChecked byChecked atPrevents
state (OAuth)RPCallback (step 8)CSRF (being pulled into a flow the attacker started)
code_verifier (PKCE)OPToken request (step 9)Authorization code interception
nonce (OIDC)RPInside the ID token (step 11)ID token replay

The nonce travels much like state. The RP creates it, stores it in the session, and attaches it to the authorization request. The difference is where it comes back: state returns in the redirect URL, while nonce returns inside the ID token, which the OP has signed. The RP compares it with the value in the session and refuses the login if they do not match.

This way, if someone brings in an ID token that was issued earlier in a different context, its nonce will not match the current one and it gets rejected. Because the nonce is covered by the signature, it cannot be rewritten either.

Inside the ID token

The JWT format

An ID token is a JWT (JSON Web Token): a string made of three parts joined by ..

eyJhbGciOiJSUzI1NiIs...  .  eyJpc3MiOiJodHRwczov...  .  NHVaYe26MbtOYhSKkoKY...
 header                      payload                      signature

The header holds the signing algorithm (alg) and the key ID (kid), and the payload holds information about the user. The signature is made with the OP’s private key, and the RP verifies it with the OP’s public key. The header and payload are only Base64URL-encoded, so anyone can read them. They are not the place for secrets.

The payload

Decoding the payload gives JSON like this. Each item in a JWT is called a claim.

{
  "iss": "https://auth.example.net",
  "sub": "248289761001",
  "aud": "s6BhdRkqt3",
  "exp": 1793581200,
  "iat": 1793577600,
  "nonce": "n-0S6_WzA2Mj",
  "auth_time": 1793577590,
  "amr": ["pwd", "otp"],
  "name": "Hanako Yamada",
  "email": "hanako@example.com",
  "picture": "https://auth.example.net/p/248289761001.jpg"
}
ClaimMeaning
issThe OP that issued the token. Required
subThe user's ID within the OP. Required
audThe audience. Holds the RP's client_id. Required
exp, iatExpiry time and issue time. Required
nonceThe value the RP sent in the authorization request. Always present if the request included one
auth_time, acr, amrWhen the user logged in, how strong the authentication was, and which methods were used (password and one-time password in this example). Optional
name, email, pictureUser attributes requested with the profile and email scopes. Some OPs leave them out of the ID token and return them only from UserInfo

To identify a user inside the RP, use the pair of iss and sub. sub is only unique within one OP, so without iss it could collide with the same sub from another OP. email can be changed by the user, so it is not a good key.

What the RP validates

When the RP receives an ID token, it checks the following before logging the user in (step 11).

WhatHow
SignatureVerify it has not been tampered with, using the OP's public key (published at jwks_uri, covered below)
issMatches the identifier of the OP you are talking to
audContains your own client_id
expThe expiry time is in the future
nonceMatches the value stored in the session in step 2

If any of them fails, the user is not logged in. The aud check is the answer to the problem from “What goes wrong when you log in with OAuth alone”, where a token issued to a different app is brought in.

Once everything passes, the RP looks up the user by iss and sub (creating one if needed), creates its own session, and the login is done. An ID token proves who the user was at the moment of login. It is not meant to be carried around as a session cookie.

In practice, an OIDC library does almost all of this, including verifying the signature. Still, knowing what it checks makes it easier to notice a missing setting.

UserInfo and Discovery

UserInfo

When you need attributes that are not in the ID token, call the UserInfo endpoint with the access token (step 12).

GET /userinfo HTTP/1.1
Host: auth.example.net
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
{
  "sub": "248289761001",
  "name": "Hanako Yamada",
  "email": "hanako@example.com",
  "email_verified": true
}

UserInfo is an API on the OP side that you call with the access token. The RP checks that the sub it returns matches the sub in the ID token, so it does not take in someone else’s information.

Discovery

To talk to an OP, the RP needs to know the authorization endpoint, the token endpoint, where the public keys are, and so on. In OIDC, the OP publishes these as JSON at a fixed URL. This is called Discovery.

The URL is the OP’s identifier (iss) followed by /.well-known/openid-configuration. Here is an excerpt from Google’s real one.

https://accounts.google.com/.well-known/openid-configuration
{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["plain", "S256"]
}
FieldUsed for
issuerCompared with the ID token's iss
authorization_endpointWhere the authorization request goes (step 4)
token_endpointWhere the code is exchanged for tokens (step 9)
userinfo_endpointWhere extra attributes come from (step 12)
jwks_uriWhere the public keys for verifying the ID token's signature live
code_challenge_methods_supportedSupported PKCE methods. As covered last time, use S256

The usual setup is to configure only the OP’s identifier and the client ID and secret in the RP, and load the rest from Discovery. When the OP rotates its keys, the RP just fetches the new ones from jwks_uri, with no configuration change.

Wrapping up

  • OAuth decides what an app may do; OIDC tells the app who logged in
  • OIDC is not a new flow but the authorization code flow plus scope=openid, a nonce and an ID token, and it works together with PKCE
  • An ID token is a signed JWT addressed to the RP, and the RP checks the signature, iss, aud, exp and nonce before logging the user in
  • Identify users by the pair of iss and sub, and load endpoints and key locations from Discovery

References