EXPLAINER

OpenID Connect

OpenID Connect (OIDC) is a thin identity layer on OAuth 2.0. It gives your app an ID token that says who signed in. OAuth alone gives an access token for an API. Most sign-in-with buttons are OIDC.

Short answer: OpenID Connect (OIDC) is login on top of OAuth 2.0. The ID token says who the user is. The access token calls an API. Validate the ID token's issuer, audience and signature. Do not use an access token as proof of identity.

What it is

OpenID Connect (OIDC) is an identity protocol built on OAuth 2.0. Where OAuth says "this client may call an API with these scopes", OIDC says "this human authenticated, and here is an identifier". The extra artifact is an ID token, a JWT with claims such as the subject (sub), the issuer, the audience (your client id), and an expiry. Optional claims include email and name. You should treat those as profile hints and still key your own user row by the issuer plus sub, not by email, because email can change.

People mix the names up. People say they use OAuth to sign users in usually means OIDC. They say they use OAuth to read a calendar means OAuth access tokens. You often do both in one redirect.

Why and when it is used

Use OIDC when users should sign in with an identity provider you do not want to replace: a company directory (Entra ID), Google, or any provider with a discovery document. You get multifactor and account recovery from them. Use it for a workforce app and for consumer "sign in with" if that matches the product.

Do not use OIDC as the permission system for every row in your database. It authenticates. Your session and your authorisation rules take over after that. Do not build a password store for employees who already have a directory. Do not accept an ID token from a provider you did not ask for.

How it works

You register a client and request the openid scope (and usually profile or email). The flow is the OAuth authorisation-code flow. The token response includes an ID token and, if you asked for APIs, an access token. You validate the ID token: signature against the provider's published keys, issuer, audience, expiry, and nonce if you sent one. Discovery (/.well-known/openid-configuration) tells you the URLs and key set so you do not hard-code them carelessly, though you should still pin the issuer you expect.

Then you create your own session (a cookie). The ID token is proof for that moment, not a session you replay for a week. Access tokens go to APIs and are not a substitute for the ID token. They may be JWTs or opaque, and their audience is the API, not your login client.

Technologies and dependencies

A provider, a current OIDC client library, and HTTPS. JSON Web Tokens explains the token shape. Authentication versus Authorization is the split you must keep. Microsoft Entra ID is a common provider in the Microsoft stack. Your user table stores the provider's subject. API Keys are unrelated to user login.

How to get started

  1. Pick one provider and register a client with a localhost redirect.
  2. Use a library's OIDC example, not a JWT decode with verification turned off.
  3. Sign in. Log the sub and issuer. Create a row in your database keyed by those, not by email alone.
  4. Set a session cookie. Call a page as that user. Sign out and confirm the cookie is gone.
  5. Tamper with a copied ID token (change a character) and confirm you reject it.
  6. Add a second provider only when the first path is solid. Linking accounts by unverified email is a takeover bug.

Read the library's default clock skew and nonce behaviour. "It works" with verification disabled is not a login.

Cautions and trade-offs

The classic bug is decoding a JWT without checking the signature, or checking the signature but not the audience, so a token for another app is accepted. Another is trusting the email claim from a provider that does not verify email. Another is using the access token as the user id.

Do not log ID tokens. They are bearer credentials for the login moment and they contain personal data. Session fixation and redirect handling are still your job; the protocol does not secure a sloppy cookie. And OIDC does not mean every user is equal. After login, authorisation (roles, tenant, ownership) is an application decision the identity provider only partially knows.