{"canonical_url":"https://engineer.company/glossary/openid-connect/","content_markdown":"# OpenID Connect\n\n## What it is\n\nOpenID Connect is a standard way for an application to learn who a person is\nfrom a service that has just signed them in. Its specification calls it a\nsimple identity layer on top of OAuth 2.0, and that is how it works: the same\nredirects, endpoints and tokens as OAuth, plus one more token, one more endpoint\nand the rules for checking them. It is usually shortened to OIDC. The core\nspecification became final in February 2014; the current text, which folds in\nits second set of corrections, is dated 15 December 2023 and is maintained by a\nworking group of the OpenID Foundation.\n\nOAuth on its own answers the question \"what may this application do?\" It hands\nthe application an access token meant for an API, and the application is not\nsupposed to read it. OpenID Connect adds the question \"who signed in?\" and\nanswers it with an ID token: a JSON Web Token, addressed to the application\nitself, that states who the person is, who vouches for that, when\nit was issued and which application it is meant for. ID tokens must be signed,\nexcept that the specification permits `alg: none` only if the response type returns no ID token\nfrom the authorization endpoint and the client explicitly requested `none` at\nregistration.\n\nThe specification renames the OAuth roles for this job. The OpenID Provider\n(OP) is an OAuth authorization server that authenticates people and issues ID\ntokens. The Relying Party (RP) is the OAuth client that needs to know who the\nperson is. The person is the End-User. A request becomes an OpenID Connect\nrequest by putting `openid` in its scope, and that value is required: \"If the\nopenid scope value is not present, the behavior is entirely unspecified.\"\n\nFurther scope values ask for profile data. `profile` covers name, nickname,\npicture, locale and similar claims, `email` adds `email` and `email_verified`,\nand `address` and `phone` do what they say. The application can fetch those\nclaims from the provider's UserInfo endpoint, an ordinary OAuth-protected API\ncalled with the access token.\n\nThere are three ways to run it. The authorization code flow sends only a\nshort-lived code through the browser and collects the tokens with an HTTPS\nrequest to the token endpoint; the implicit flow returns tokens straight in the redirect; the hybrid flow\nmixes the two. A companion specification, OpenID Connect Discovery 1.0, lets\nthe application look up every endpoint and signing key from a single address.\n\n## Why it matters\n\nThe reason to adopt it is single sign-on. With one identity provider in front of\nmany applications, people keep one set of credentials, the applications store\nnone, and the policy that decides how someone signs in, from password rules to\na second factor, is set once at the provider.\nDisabling an account at the provider stops it from starting a new session in any\napplication that relies on it, which is what makes offboarding a single step\nrather than a list.\n\nIt also closes a hole that teams fall into when they build login on plain\nOAuth. RFC 6749 warns that in the implicit flow a public client has no way to\ntell which client an access token was issued to, so one that assumes only the\nresource owner can hand it a valid token is open to impersonation: an attacker\nholding a token issued to another application can present it and be taken for\nthe person behind it. An ID token names the application it is for in its `aud`\nclaim, and the application checks it.\n\nBecause it is a standard, the work transfers. The specification promises\nprofile information in an interoperable manner, so the code that signs people in\nthrough one provider can sign them in through another, and with Discovery the\napplication learns the provider's endpoints and signing keys from its issuer URL\ninstead of from hand-copied settings.\n\nFinally, OpenID Connect gives each person a stable identifier. The specification\nis explicit that the pair of `iss` (who issued the token) and `sub` (the subject\nidentifier) is the only claim pair an application can rely on as a stable\nidentifier for a person. The `sub` value is unique within the issuer, never\nreassigned and at most 255 ASCII characters. A provider may even issue a\ndifferent `sub` to each application, a pairwise identifier, so that\napplications cannot correlate a person's activities without permission.\n\n## What it looks like in practice\n\nTake a web application registered with an OpenID Provider at\n`https://server.example.com` under the client ID `s6BhdRkqt3`; the values below\ncome from the specification's own examples. The application starts by reading\nthe provider's configuration from the well-known address under the issuer:\n\n```http\nGET /.well-known/openid-configuration HTTP/1.1\nHost: server.example.com\n```\n\nThe answer is a JSON document. A shortened version:\n\n```json\n{\n  \"issuer\": \"https://server.example.com\",\n  \"authorization_endpoint\": \"https://server.example.com/connect/authorize\",\n  \"token_endpoint\": \"https://server.example.com/connect/token\",\n  \"userinfo_endpoint\": \"https://server.example.com/connect/userinfo\",\n  \"jwks_uri\": \"https://server.example.com/jwks.json\",\n  \"scopes_supported\": [\"openid\", \"profile\", \"email\", \"address\", \"phone\"],\n  \"id_token_signing_alg_values_supported\": [\"RS256\", \"ES256\", \"HS256\"]\n}\n```\n\nDiscovery requires the `issuer` in that document to be identical to the issuer\nURL the application put in front of the well-known path, and the application\nstops if it differs. Then it sends the person's browser to the authorization\nendpoint with the code flow, the `openid` scope and two random values it has\nstored against the browser session: `state` for the redirect and `nonce` for\nthe ID token. A public client would add the PKCE parameters as well, which\nRFC 9700 makes mandatory for it; they are left out here to keep lines short.\n\n```http\nGET /connect/authorize?response_type=code\u0026client_id=s6BhdRkqt3\n    \u0026redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb\n    \u0026scope=openid%20profile%20email\n    \u0026state=af0ifjsldkj\u0026nonce=n-0S6_WzA2Mj HTTP/1.1\nHost: server.example.com\n```\n\nThe provider signs the person in, sends the browser back with a code, and the\napplication redeems the code at the token endpoint exactly as in plain OAuth.\nThe difference is in the answer, which now carries an `id_token` next to the\naccess token (shortened here):\n\n```json\n{\n  \"access_token\": \"SlAV32hkKG\",\n  \"token_type\": \"Bearer\",\n  \"refresh_token\": \"8xLOxBtZp8\",\n  \"expires_in\": 3600,\n  \"id_token\": \"eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc...\"\n}\n```\n\nThe ID token is three base64url parts separated by dots. The first decodes to\n`{\"alg\":\"RS256\",\"kid\":\"1e9gdk7\"}`: the signing algorithm and the ID of the key\nin the provider's published key set. The middle part holds the claims, and the\nspecification's example reads:\n\n```json\n{\n  \"iss\": \"https://server.example.com\",\n  \"sub\": \"24400320\",\n  \"aud\": \"s6BhdRkqt3\",\n  \"nonce\": \"n-0S6_WzA2Mj\",\n  \"exp\": 1311281970,\n  \"iat\": 1311280970,\n  \"auth_time\": 1311280969,\n  \"acr\": \"urn:mace:incommon:iap:silver\"\n}\n```\n\nBefore the application trusts a word of it, it validates the token, and the\nspecification lists the steps. The `iss` must match the provider's issuer\nexactly. The `aud` must contain the application's own client ID and no audience\nit does not trust. The signature must verify with the provider's keys from\n`jwks_uri`, using the algorithm in the header; when the token arrived straight\nfrom the token endpoint over TLS, as here, checking the server's TLS\ncertificate may stand in for the signature check. The current time must be\nbefore `exp`. The `nonce` must equal the value the application sent. Only then\ndoes it sign the person in, keyed on `https://server.example.com` plus\n`24400320`, and use the access token to fetch email and profile claims from the\nUserInfo endpoint if it needs them.\n\nA single provider for many systems is as much an organisational change as a\ntechnical one. One of this site's projects,\n[access management across M365 and SSO](/portfolio/led-access-management-across-m365-and-sso/),\nconsolidated identities and access across M365, 1Password, Red Hat SSO and OKTA\nSSO, enforced least privilege, and standardised onboarding and offboarding so\nthat access was revoked promptly when someone moved on.\n\n## Where it goes wrong\n\n**The email address is used as the account key.** It is the obvious choice and\nthe wrong one. The specification says a provider may reuse an email address for\na different person over time, and that `email`, `phone_number`,\n`preferred_username` and `name` must not be used as unique identifiers. An\napplication that looks people up by email can hand one person's account to the\nnext owner of that address. Store `iss` and `sub` together as the key, keep the\nemail as an attribute, and before relying on an address for anything, check\nthat `email_verified` is true.\n\n**An access token is taken as proof of who signed in.** Some applications\nreceive an access token, call an API with it, and treat the answer as a login.\nThe token may have been issued to a different application altogether, which is\nthe impersonation RFC 6749 warns about. Sign people in on the ID token, and\nonly after confirming that its `aud` names your own client ID.\n\n**The ID token is decoded but never checked.** Reading the claims out of a\ntoken takes a base64url decode and no key at all, and that ease is the trap. A\ntoken whose signature, `iss`, `aud` or `exp` goes unverified can be forged,\nbelong to another application or have expired. Use a maintained library, give\nit the issuer and client ID, and let it run every check in the specification's\nlist rather than picking the convenient ones.\n\n**The nonce is missing, fixed, or never compared.** Without it, an ID token\ncaptured from one sign-in can be replayed into another. RFC 9700 adds that the\nnonce must be specific to one sign-in and bound to the browser that started it.\nThe specification suggests one way to do that: keep a cryptographically random\nvalue in an HttpOnly session cookie, send its hash as the `nonce`, and compare\nthe two when the ID token comes back.\n\n**Signing keys are cached for good.** Providers rotate keys, and an application\nholding yesterday's key set rejects every token signed with the new one. The\nspecification expects the provider to publish keys at `jwks_uri` and mark each\ntoken with a `kid`, and the application to fetch the key set again when it\nmeets a `kid` it does not know. Cache the keys, but treat an unfamiliar `kid` as\na signal to refresh rather than a reason to fail the login.\n\n**Two tenants on one host are treated as one issuer.** A provider can run\nseveral issuers on one host, and the path is part of the issuer identifier: the\nsubject `1234` at `https://example.com` and the subject `1234` at\n`https://example.com/sales` are different people. Store the full issuer string,\ncompare it exactly, and never trim it to a host name.\n\n## Further reading\n\n- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)\n  — the ID token, the three flows, the standard claims and the validation steps,\n  in the edition incorporating errata set 2 of December 2023.\n- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)\n  — the well-known configuration document and the rule that its issuer must\n  match the issuer URL it was fetched under.\n- [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)\n  — the framework OpenID Connect builds on, with the warning in section 10.16\n  about using access tokens to identify people.\n- [RFC 7519: JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519) — the\n  token format every ID token uses.\n- [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://www.rfc-editor.org/rfc/rfc9700)\n  — current guidance on PKCE, the nonce and the redirect, which applies to\n  OpenID Connect as much as to OAuth.\n\n\u003chttps://engineer.company/glossary/openid-connect/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How OpenID Connect signs people in on top of OAuth: the ID token and its claims, a sign-in traced from discovery to validation, and six ways it goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/openid-connect/index.gmi","gopher":"https://engineer.company/glossary/openid-connect/gophermap","html":"https://engineer.company/glossary/openid-connect/","json":"https://engineer.company/glossary/openid-connect/index.json","markdown":"https://engineer.company/glossary/openid-connect/index.md","pdf":"https://engineer.company/glossary/openid-connect/index.pdf"},"kind":"page","language":"en","title":"What is OpenID Connect?","url":"https://engineer.company/glossary/openid-connect/","version":1}