OIDC Discovery Document
The discovery document
Section titled “The discovery document”Every Keycloak realm publishes an OpenID Connect discovery document at /.well-known/openid-configuration under /realms/<realm>.
Full URL:
https://<keycloak-host>/realms/<realm>/.well-known/openid-configurationThis is the single source of truth for every endpoint your app needs. Fetch it once at startup and you have everything — authorization endpoint, token endpoint, JWKS URI, and more.
Key endpoints in the discovery document
Section titled “Key endpoints in the discovery document”| Endpoint name | JSON key | Purpose |
|---|---|---|
| Authorization endpoint | authorization_endpoint | Redirects users to the login page |
| Token endpoint | token_endpoint | Exchanges codes for tokens |
| UserInfo endpoint | userinfo_endpoint | Returns claims about the authenticated user |
| JWKS URI | jwks_uri | Public keys for verifying JWT signatures |
| End session endpoint | end_session_endpoint | Logs the user out |
Fetching the discovery document
Section titled “Fetching the discovery document”Replace KC_URL and REALM with your values. The response is a JSON object with all the endpoint URLs listed above.
curl https://${KC_URL}/realms/${REALM}/.well-known/openid-configuration | jq .Trade-offs
Section titled “Trade-offs”| Option | Benefit | Cost |
|---|---|---|
| Use the OIDC discovery document | The app fetches its configuration automatically, with no endpoint URLs hardcoded | Adds a network call at startup, and it must be cached properly so it isn’t refetched on every request |
| Hardcode the endpoint URLs yourself | Faster to get started, no dependency on the discovery document | When Keycloak moves the realm or changes its URL, every place you hardcoded it needs a code change |
Common mistakes
Section titled “Common mistakes”- Confusing OAuth2 with OIDC — OAuth2 is an authorization framework (grants access to a resource), while OIDC is an identity layer built on top of OAuth2 (tells you who the user is). You must request
scope=openidto get anid_tokenback. - Not verifying
issuerin the discovery document — before trusting any endpoint, verify thatissuermatches the expected Keycloak realm, or you risk being tricked by a forged discovery document. - Caching the discovery document forever and never refreshing it — if Keycloak rotates keys or moves an endpoint, an app that cached the old value permanently breaks with no warning. Set a TTL or refresh it periodically.
Real-world example
The “Log in with Google” or “Log in with GitHub” button — behind it is full OIDC: the app fetches Google’s/GitHub’s discovery document first to learn the authorization and token endpoints, then starts the flow.
Auth0 and Okta — commercial identity providers that use the same discovery-document pattern as Keycloak, so an app can switch provider with almost no code change, because they all speak the same OIDC language.