Protocol practice · Federation & Identity Standards

OpenID Connect: sign-in, and the ID token that proves it

Objective: Lumen Notes adds “Sign in with Harbor”. Get an ID token for Rui, check every part of it before you believe it, and find out who they really are.

About 10 minutes · simulated, no real servers

1Ask for sign-in
2Read the response
3Check token A
4Accept token B
5Keys

Where OpenID Connect fits

Sign-inWho is this?

OpenID ConnectYou are hereSAMLenterprise single sign-on KerberosWindows domains

AccessWhat may this app do?

OAuthaccess for an app

AccountsDoes the account exist?

SCIMjoiners, movers, leavers

Not sure? Which protocol?

OpenID Connect at work, every day

Each of these signs someone in with an account they already have.

“Sign in with your work account”A web app trusts the company’s provider instead of keeping passwords.
A mobile app’s sign-inThrough the phone’s browser, so the app never handles the password.
One sign-in across internal toolsEach tool checks the same provider’s ID tokens.

Step 1 of 5

Ask for sign-in, not just access

OpenID Connect is OAuth with one addition: an ID token that says who signed in. Your app sends the browser to Harbor’s OpenID provider, and three values decide what comes back.

GET https://id.harbor.example/authorize
  ?response_type=______
  &client_id=lumen-notes
  &redirect_uri=https://notes.example/callback
  &scope=______
  &state=af0ifjsldkj
  &nonce=______
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Fill in the three blanks, then send the user.

scope: what makes this sign-in

response_type

nonce: what ties the ID token to this sign-in

Pick an answer for each blank to continue.

This step

OpenID Connect: A sign-in layer on OAuth 2.0. OAuth grants access; OpenID Connect adds an ID token that says who the user is.
Relying party: The app that relies on the provider to sign users in: here, Lumen Notes.
OpenID provider: Signs the user in and issues the ID token. Here, Harbor.
openid scope: The scope that makes a request a sign-in. Without it, there’s no ID token.
Nonce: A random value the app sends and the provider copies into the ID token, tying the token to this sign-in.

Earlier steps (0)

All terms (16)

OpenID Connect: A sign-in layer on OAuth 2.0. OAuth grants access; OpenID Connect adds an ID token that says who the user is.
Relying party: The app that relies on the provider to sign users in: here, Lumen Notes.
OpenID provider: Signs the user in and issues the ID token. Here, Harbor.
openid scope: The scope that makes a request a sign-in. Without it, there’s no ID token.
Nonce: A random value the app sends and the provider copies into the ID token, tying the token to this sign-in.
ID token: A signed statement for the app: who signed in, at which provider, for which app, and until when.
JWT: JSON Web Token: header, payload and signature, base64url-encoded and joined with dots. Readable by anyone; trusted only once verified.
UserInfo endpoint: Returns the user’s profile claims, called with the access token.
iss: Issuer: which provider made the token. Must match the one you used, exactly.
aud: Audience: which app the token is for. Must be your client ID.
exp and iat: When the token expires, and when it was issued. Minutes, not hours.
sub: Subject: the user’s permanent identifier at the issuer. Never reassigned. Store it with iss.
email_verified: Whether the provider confirmed the user controls the email. Don’t link accounts on an unverified one.
Discovery document: The provider’s published configuration, at /.well-known/openid-configuration: its endpoints, keys and algorithms.
JWKS: JSON Web Key Set: the provider’s public signing keys, at jwks_uri. Tokens name the key they used with kid.
alg: The signing algorithm in the token’s header. Accept only the one you expect; never none.