# OpenID Connect (OIDC)

OpenID Connect adds a standard identity layer to OAuth 2.0 with ID tokens, so apps can sign users in through an identity provider. Learn how it works.

## Overview

OpenID Connect, usually shortened to OIDC, is an identity layer built on top of [OAuth 2.0](/tools/oauth-2-0). OAuth on its own answers "may this application access this API?". OIDC adds a standard answer to a different question: "who is the user who just signed in?". It does this with an ID token, a signed [JSON Web Token](/tools/jwt) that the identity provider issues to the application, containing the user's identifier, when and how they authenticated, and which application the token was meant for.

An everyday analogy is a passport checked at a hotel reception. The hotel does not issue passports or verify citizenship itself. It trusts a government it recognises, checks that the document is genuine, that the photo matches, and that it has not expired, then gives you a room key. In OIDC the identity provider is the government, the ID token is the passport, the application is the hotel, and the session the application creates is the room key.

OIDC is what sits behind "Sign in with" buttons on consumer sites and behind enterprise single sign-on to cloud tools. It also secures internal platforms: dashboards such as [Grafana](/tools/grafana), deployment tools such as [Argo CD](/tools/argocd), notebooks and model registries commonly delegate login to a company identity provider through OIDC. Workloads use it too, for example when a CI pipeline proves its identity to a cloud provider with an OIDC token instead of a stored secret.

## What it is

OIDC adds a small set of elements on top of OAuth 2.0.

| Element | What it is |
|---|---|
| OpenID Provider (OP) | The identity provider that authenticates users and issues ID tokens |
| Relying Party (RP) | The application that relies on the provider for sign-in |
| `openid` scope | The scope that turns an OAuth request into an OIDC request |
| ID token | A signed JWT describing the authentication event and the user |
| UserInfo endpoint | An OAuth-protected API returning claims about the user |
| Standard claims | Defined attributes such as `sub`, `name`, `email`, `email_verified` |
| Discovery | A metadata document at `/.well-known/openid-configuration` listing endpoints and capabilities |
| JWKS | The provider's published public keys, used to verify token signatures |
| Dynamic client registration | An optional way for clients to register automatically |

Key ID token claims include `iss` (issuer), `sub` (subject, the stable user ID at that issuer), `aud` (audience, the client ID), `exp` and `iat` (expiry and issued-at times), `nonce` (binds the token to the login request), and optionally `auth_time`, `acr` and `amr`, which describe when and how the user authenticated.

## Where it came from

Earlier versions of OpenID, an open standard for decentralised sign-in, appeared from 2005, with OpenID 2.0 in 2007. They were not built on OAuth and saw limited adoption. Separately, many companies used OAuth 2.0 for sign-in in non-standard ways, which created security problems because access tokens were never designed to prove identity to the client.

The OpenID Foundation developed OpenID Connect to standardise identity on top of OAuth 2.0, and published OpenID Connect Core 1.0 and related specifications such as Discovery and Dynamic Client Registration in February 2014. In 2024 OpenID Connect Core 1.0, incorporating errata, was also published as an international standard, ISO/IEC 26131:2024. The foundation continues related work, including the FAPI security profiles for high-assurance APIs and specifications for logout and federation.

## How it works

### Authorisation code flow with PKCE

1. The user clicks "Sign in". The relying party redirects the browser to the provider's authorisation endpoint with `response_type=code`, `scope=openid email profile`, its client ID, an exact redirect URI, a random `state`, a random `nonce` and a PKCE code challenge.
2. The provider authenticates the user, possibly with multi-factor authentication, and may ask for consent to share claims.
3. The provider redirects back with an authorisation code and the `state`.
4. The relying party checks `state` and exchanges the code, together with its PKCE verifier and client authentication, at the token endpoint.
5. The provider returns an ID token, an access token and possibly a refresh token.
6. The relying party validates the ID token: signature against the provider's JWKS, `iss` equals the expected issuer, `aud` contains its client ID, `exp` is in the future, and `nonce` matches the one it sent.
7. It identifies the user by the pair (`iss`, `sub`), creates its own session and, if needed, calls the UserInfo endpoint with the access token for more claims.

### Discovery and keys

Instead of hard-coding endpoints, the relying party reads the discovery document from the issuer URL. It caches the JWKS and refreshes it when it sees a new key ID, which lets the provider rotate signing keys.

### Logout

OIDC defines optional logout mechanisms: the relying party can redirect to the provider's end-session endpoint, and providers can notify applications through front-channel or back-channel logout.

## Key concepts and terms

| Term | Meaning |
|---|---|
| Authentication | Verifying who a user is. |
| Identity provider | A service that authenticates users for other applications. |
| Relying party | An application that trusts an identity provider. |
| ID token | A signed token about the authentication event, for the client. |
| Access token | A token for calling APIs, for the resource server. |
| `sub` claim | Stable, unique user identifier within one issuer. |
| Nonce | Random value tying an ID token to one login request. |
| Discovery document | JSON metadata describing a provider's endpoints and keys. |
| JWKS | JSON Web Key Set of public signing keys. |
| Single sign-on | One login giving access to many applications. |
| Claims | Name-value statements about the user. |
| Workload identity federation | Using OIDC tokens issued to machines to obtain cloud credentials. |

## A worked example

This scenario is illustrative. A data platform team runs six internal tools: a notebook server, an experiment tracker, a dashboard, a deployment console, a feature store UI and a labelling tool. Each has its own local accounts. When people leave, some accounts stay active for months.

The team connects all six to the company's identity provider using OIDC. Each tool is registered as a client with an exact redirect URI and requests `openid email profile groups`. The provider requires multi-factor authentication. Each tool validates the ID token on the callback and maps the `groups` claim to roles: `ml-admins` become administrators in the deployment console, `annotators` get access only to the labelling tool.

On day one, 140 users sign in without creating new passwords. When an employee leaves and is disabled at the provider, they cannot start new sessions in any tool; sessions are set to expire after 8 hours. The team also replaces a long-lived cloud access key used by CI with workload identity federation: the CI system presents an OIDC token about the pipeline run, and the cloud provider exchanges it for 1-hour credentials scoped to one storage bucket. One leaked secret fewer exists to rotate.

## Strengths and limitations

**Strengths:**

- A widely implemented standard for sign-in and single sign-on.
- Applications never handle user passwords.
- Signed ID tokens with clear validation rules.
- Discovery and JWKS simplify configuration and key rotation.
- Works for web, mobile and machine identities.
- Builds on OAuth, so the same infrastructure handles API access.

**Limitations:**

- Many options; misconfiguration, such as skipping nonce or audience checks, causes vulnerabilities.
- Logout across many applications is still complex.
- Claims beyond the basics, such as group membership, vary between providers.
- Applications become dependent on the identity provider's availability.
- Enterprise environments may still need SAML for older applications.

## How it compares with alternatives

| Approach | What it is | When it fits better |
|---|---|---|
| SAML 2.0 | XML-based federation and single sign-on | Legacy enterprise applications that only support SAML |
| Plain [OAuth 2.0](/tools/oauth-2-0) | Delegated authorisation without identity semantics | API access where the client does not need to know the user |
| Local username and password | Application-managed credentials | Isolated systems with no identity provider |
| Passkeys / WebAuthn | Phishing-resistant authentication with public-key credentials | How users authenticate at the provider; complements OIDC |
| [mTLS](/tools/mtls) client certificates | Certificate-based identity | Service-to-service authentication |

## Practical guidance and best practices

1. Use the authorisation code flow with PKCE; avoid the implicit flow.
2. Validate every ID token: signature, issuer, audience, expiry and nonce.
3. Identify users by the issuer and `sub` pair, not by email address.
4. Use discovery and cache JWKS with refresh on unknown key IDs.
5. Register exact redirect URIs and keep client secrets server-side.
6. Use the access token for APIs and the ID token only for the client's login decision.
7. Map groups or roles from claims to application permissions, and review mappings regularly.
8. Prefer workload identity federation over long-lived cloud keys in pipelines.
9. Require strong authentication at the provider, ideally phishing-resistant methods.

## Common mistakes

- Treating an access token as proof of identity, or sending ID tokens to APIs.
- Skipping audience checks, so a token issued for another app is accepted.
- Using email as the user key, which can change or be reassigned.
- Hard-coding signing keys, so the app breaks when the provider rotates them.
- Accepting tokens with `alg` set to `none` or unexpected algorithms.
- Keeping very long local sessions after sign-in, defeating central deprovisioning.

## Frequently asked questions

### What is the difference between OAuth 2.0 and OIDC?

OAuth 2.0 delegates access to APIs. OIDC adds authentication on top: an ID token and standard claims that tell the application who signed in and how.

### What is in an ID token?

Claims about the authentication: issuer, subject, audience, issue and expiry times, nonce, and optionally authentication time, methods and user profile claims. It is signed by the provider.

### Should my API accept ID tokens?

No. ID tokens are for the client application. APIs should accept access tokens issued for them, with the correct audience.

### Is OIDC an official standard?

It is an OpenID Foundation specification, finalised in 2014, and OpenID Connect Core 1.0 has also been published as ISO/IEC 26131:2024.

### What is workload identity federation?

A pattern where a platform, such as a CI system or Kubernetes, issues OIDC tokens about a workload, and a cloud provider trusts those tokens to grant short-lived credentials, removing the need for stored keys.

### Does OIDC replace SAML?

For new applications, OIDC is usually preferred because it is simpler and works well with mobile and APIs. SAML remains common in established enterprise systems.

## Glossary

- OIDC: OpenID Connect.
- OP: OpenID Provider, the identity provider.
- RP: Relying Party, the application.
- ID token: a signed statement that a user authenticated.
- UserInfo: an endpoint returning user claims.
- Issuer: the identifier of the provider.
- Subject: the stable user ID at the issuer.
- JWKS: a set of public keys for verifying signatures.
- SSO: single sign-on.
- Nonce: a value preventing token replay in login.

## Summary

OpenID Connect adds identity to OAuth 2.0 through signed ID tokens, standard claims, discovery and published keys. Finalised by the OpenID Foundation in 2014 and published as ISO/IEC 26131 in 2024, it underpins consumer sign-in, enterprise single sign-on and workload identity federation. Use the code flow with PKCE, validate every ID token carefully, key users by issuer and subject, keep ID tokens and access tokens in their proper roles, and let central deprovisioning take effect through reasonable session lifetimes.