What Is OpenID Connect (OIDC)?
The complete beginner-to-production guide to the protocol behind "Sign in with Google" — and how identity servers like Keycloak use it under the hood.
Think about checking into a hotel using your passport. The passport itself was issued by a government agency you trust — not by the hotel. The hotel doesn’t re-investigate your entire life history; it simply looks at the passport, confirms it’s genuine (checking the watermark, the photo, the government seal), and trusts the claims printed inside it: your name, your date of birth, your nationality. OpenID Connect, often shortened to OIDC, works the same way for software. It’s a standardized way for one system (the “hotel”) to trust a proof of identity issued by a separate, dedicated identity provider (the “passport office”) — without ever seeing the user’s actual password.
This guide explains what OIDC is, why it exists, exactly how it works step by step, the tokens it produces, and how systems like Keycloak use it as their core protocol. No prior identity or security background is assumed — every term is explained the moment it appears.
1Core Concepts
What Is OpenID Connect?
OpenID Connect is an open standard that lets an application confirm a user’s identity by relying on a separate, trusted identity provider — without the application ever handling that user’s password directly. It’s the protocol behind buttons labeled “Sign in with Google,” “Sign in with Microsoft,” or, in the enterprise world, “Sign in with Keycloak.”
OIDC Is Built on Top of OAuth2
To understand OIDC, you first need to know about its foundation: OAuth2. OAuth2 is an older standard designed to let one application access a limited slice of a user’s data on another system — for example, letting a photo-printing website access just your Google Photos library, without ever seeing your Google password. OAuth2 was built for authorization (delegated access to resources), not for confirming identity. OIDC takes OAuth2’s machinery and adds a standardized identity layer on top of it, purpose-built for the specific question “who is this person?”
OAuth2 answers “can this application access this resource on my behalf?” OIDC answers “who is this user, exactly?” OIDC is often described as “a thin identity layer on top of OAuth2” — it reuses OAuth2’s flows but adds a dedicated, verifiable proof of identity called an ID Token, covered in Chapter 3.
The Three Roles in OIDC
Every OIDC interaction involves three distinct parties, and getting comfortable with these names makes everything else in this guide click into place:
- End User — the actual human sitting at the keyboard, trying to log in.
- Relying Party (RP) — the application that wants to know who the user is (this is the same concept as a “Client” in Keycloak’s own terminology).
- OpenID Provider (OP) — the identity server that authenticates the user and issues the proof (Keycloak plays this role).
Back to the passport analogy: the End User is the traveler, the OpenID Provider is the government passport office that verified their identity and issued the document, and the Relying Party is the hotel that trusts that document without doing its own background investigation. The hotel never talks to the government directly during check-in — it just examines the passport the traveler hands over, exactly as OIDC’s Relying Party examines the token the user’s browser delivers.
2Architecture & Components
graph TD
U["End User
(the human)"] -->|"1. Wants to log in"| RP["Relying Party
(the application / Keycloak Client)"]
RP -->|"2. Redirects to"| OP["OpenID Provider
(Keycloak / Google / etc.)"]
OP -->|"3. Authenticates user"| U
OP -->|"4. Issues tokens"| RP
OP --> DISC["Discovery Document
(.well-known/openid-configuration)"]
OP --> JWKS["JWKS Endpoint
(public signing keys)"]
RP -->|"5. Verifies token signature using"| JWKS
Discovery Document
A standardized, machine-readable document at a well-known URL listing every endpoint and capability an OpenID Provider offers, so applications can configure themselves automatically.
Authorization Endpoint
Where the user’s browser is sent to actually log in and approve the request.
Token Endpoint
Where the application exchanges a temporary code for real, usable tokens.
UserInfo Endpoint
A place the application can query to fetch additional details about the logged-in user beyond what’s already inside the token.
JWKS Endpoint
Publishes the OpenID Provider’s public cryptographic keys, letting any application verify a token’s signature is genuine without contacting the provider every single time.
JWT (JSON Web Token)
The compact, digitally signed text format that OIDC tokens are almost always encoded in.
3The Three Token Types
ID Token
The ID Token is OIDC’s signature contribution. It’s a small, digitally signed document containing facts (called “claims”) about the user who just logged in — their unique identifier, when they logged in, and often their name and email. It is meant to be read by the application itself, proving “this specific user really did log in, and here’s who they are.”
Access Token
The Access Token is inherited from OAuth2. It’s not meant to describe the user — it’s a credential the application attaches to API calls, proving to some other backend service “this request is authorized to act on the user’s behalf.”
Refresh Token
The Refresh Token is a longer-lived credential that lets an application quietly obtain new Access and ID Tokens later, without forcing the user to log in again every time their short-lived tokens expire.
| Token | Purpose | Who Reads It |
|---|---|---|
| ID Token | Proves who the user is | The application (Relying Party) itself |
| Access Token | Authorizes API calls on the user’s behalf | Backend APIs the application calls |
| Refresh Token | Obtains new tokens without re-login | Only the OpenID Provider’s token endpoint |
A frequent mistake is using the Access Token to determine who a user is, treating it like an identity document. The Access Token was never designed to be read or interpreted that way by the application — that job belongs strictly to the ID Token.
4Internal Working
Login Initiated
The user clicks “log in,” and the application redirects their browser to the OpenID Provider’s Authorization Endpoint, specifying which application is asking and what it wants to know about the user.
User Authenticates
The user proves their identity directly to the OpenID Provider — entering a password, possibly completing a second factor — never revealing any of it to the application itself.
Consent (If Required)
The user may be shown a screen listing exactly what information the application is requesting, and asked to approve it.
Authorization Code Returned
The browser is redirected back to the application with a short-lived, single-use code attached — not a real token yet, just a claim ticket.
Code Exchanged at the Token Endpoint
The application’s backend sends that code directly to the OpenID Provider’s Token Endpoint — this exchange happens server-to-server, invisible to the browser — and receives the ID Token, Access Token, and Refresh Token in response.
Token Signature Verified
The application checks the ID Token’s digital signature against the OpenID Provider’s public keys (from the JWKS Endpoint) to confirm it’s genuine and untampered.
User Considered Logged In
With a verified ID Token in hand, the application now knows exactly who the user is and starts a local session for them.
5Data Flow & Lifecycle
Initial Authentication. Covered fully in Chapter 4 — the full Authorization Code Flow that establishes trust for the first time.
Token Usage. The Access Token is attached to outbound API calls; the ID Token is used by the application to know who’s logged in and to populate its own session.
Silent Refresh. When the short-lived Access Token expires, the application uses its Refresh Token to quietly obtain new tokens from the Token Endpoint, without interrupting the user.
Session Expiry. Eventually the Refresh Token itself expires (often after hours, days, or a configured maximum session length), at which point the user must fully log in again.
Logout. OIDC defines standardized logout flows so a user’s session can be properly ended both at the application and at the identity provider — important so that “logging out” of one app doesn’t leave a lingering, still-valid session at the identity server.
graph LR
A["Initial Login
(Authorization Code Flow)"] --> B["Tokens Issued
(ID + Access + Refresh)"]
B --> C["Access Token Used
on API calls"]
C --> D{"Access Token Expired?"}
D -->|"Yes"| E["Silent Refresh
using Refresh Token"]
E --> B
D -->|"Session ended"| F["Logout
(App + Identity Provider)"]
6Advantages, Disadvantages & Trade-offs
Advantages
- Applications never see or store user passwords, dramatically reducing what a breach of any single app can expose
- A standardized protocol means one identity provider can serve countless different applications interoperably
- Users get a single login experience across multiple otherwise-unrelated applications (single sign-on)
- Built-in cryptographic verification means tokens can’t be forged without the provider’s private signing key
Disadvantages & Trade-offs
- Adds architectural complexity compared to a simple local username/password check
- Creates a dependency on the identity provider’s availability — if it goes down, no application relying on it can authenticate new logins
- Correctly implementing token verification, redirect validation, and PKCE requires real security diligence, not just following a tutorial blindly
- Debugging cross-service login issues can be harder, since the failure could be at the application, the identity provider, or the token itself
7Security
Signature Verification Is Mandatory
An application must always verify an ID Token’s digital signature before trusting anything inside it. Skipping this check would let anyone hand the application a forged token claiming to be any user at all.
Redirect URI Validation
Just as with any Client registration, the OpenID Provider must strictly validate that the redirect address supplied during login matches a pre-approved list — otherwise an attacker could redirect a legitimate login’s authorization code to a malicious destination instead.
PKCE for Public Clients
For applications that can’t safely hold a secret (mobile apps, single-page apps), OIDC’s underlying OAuth2 layer adds PKCE (Proof Key for Code Exchange) — a mechanism ensuring that only the exact application that started a login can complete it, even if the authorization code is somehow intercepted along the way.
Problem
Some implementations decode an ID Token’s contents and read the claims inside without ever checking its cryptographic signature.
Why It Fails
A JWT’s contents are readable by anyone without any special key — decoding it is trivial. Without verifying the signature, there is nothing stopping an attacker from crafting their own token claiming to be an administrator.
Correct Approach
Always verify a token’s signature against the OpenID Provider’s published public keys before trusting any claim inside it — this is a non-negotiable step, not an optional hardening measure.
8Monitoring, Logging & Metrics
Endpoint Uptime
Since every application depends on the OpenID Provider’s endpoints, their availability and latency are monitored closely as a shared point of failure.
Failed Signature Checks
A rise in tokens failing signature verification can indicate misconfiguration or an active attempted attack.
Login Success Rate
Tracking how often the full Authorization Code Flow completes successfully versus errors out helps catch integration bugs quickly.
Token Endpoint Load
Every login and silent refresh across every connected application hits the same Token Endpoint, making its throughput a key capacity metric.
9Design Patterns & Anti-patterns
Good Patterns
- Use a well-tested OIDC library rather than hand-rolling token parsing and signature verification from scratch
- Rely on the discovery document to auto-configure endpoints, rather than hardcoding URLs that may change
- Always request PKCE for any public client, even when it’s not strictly enforced by the provider
- Keep Access Tokens short-lived and rely on Refresh Tokens for longer sessions, bounding the damage window if one leaks
Anti-patterns to Avoid
Common Mistakes
- Skipping signature verification on the ID Token
- Reading user identity from the Access Token instead of the ID Token
- Storing tokens insecurely in browser storage accessible to any script running on the page
- Using overly broad redirect URI patterns instead of an exact, narrow allow-list
10Real-World & Industry Examples
“Sign in with Google” / “Sign in with Microsoft”
These familiar buttons on countless websites are OIDC in action — the website is a Relying Party trusting Google or Microsoft as the OpenID Provider, never seeing the user’s actual account password.
Enterprise Single Sign-On via Keycloak
Organizations running Keycloak configure it as their OpenID Provider, letting dozens of internal applications (each registered as a Keycloak Client, acting as a Relying Party) share one unified login experience across the entire company.
Mobile Banking Apps
Many banking apps use OIDC with PKCE to authenticate users, ensuring the app never directly handles the user’s core banking credentials, and that stolen authorization codes can’t be redeemed by any app other than the genuine one.
11Frequently Asked Questions
12Summary and Key Takeaways
Key Takeaways
- OpenID Connect is a standardized identity layer built on top of OAuth2, letting applications confirm who a user is without ever handling their password.
- Three roles matter: the End User, the Relying Party (the application), and the OpenID Provider (the identity server, like Keycloak).
- Three token types serve different purposes: the ID Token proves identity, the Access Token authorizes API calls, and the Refresh Token obtains new tokens without re-login.
- The Authorization Code Flow is the standard sequence: redirect to login, authenticate, receive a code, exchange it server-to-server for tokens.
- Always verify the ID Token’s signature before trusting its claims — this is non-negotiable, not optional hardening.
- PKCE protects public clients (mobile apps, single-page apps) that cannot safely hold a secret.
- OIDC underpins both consumer logins (“Sign in with Google”) and enterprise single sign-on systems built on identity providers like Keycloak.