What is the OIDC /.well-known discovery endpoint, and which core endpoints does Spring Authorization Server expose by default?

middleshould knowfreq 45%

answer

/.well-known/openid-configuration = JSON metadata
issuer + authorize/token/jwks/userinfo URLs
jwks_uri = public keys to verify JWT
AuthorizationServerSettings holds paths + issuer
issuer must match iss claim + resource server

basics

~10 s

The discovery endpoint /.well-known/openid-configuration returns JSON metadata (issuer plus URLs of the authorize, token, jwks, and userinfo endpoints) so clients can auto-configure. Spring Authorization Server also exposes /oauth2/authorize, /oauth2/token, and /oauth2/jwks.

solid answer

~30 s

OIDC defines a discovery document at /.well-known/openid-configuration — a JSON metadata file advertising the issuer and the absolute URLs of the provider's endpoints (authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint, end_session_endpoint) plus supported scopes, grant types, and signing algorithms. Clients fetch it once to self-configure instead of hardcoding URLs. Spring Authorization Server serves it automatically and, by default, exposes: /oauth2/authorize (start the authorization_code flow), /oauth2/token (exchange code/credentials for tokens), /oauth2/jwks (public keys to verify JWT signatures), /oauth2/revoke, /oauth2/introspect, /userinfo, and OIDC's /connect/register if enabled. All of these paths and the issuer are configurable through AuthorizationServerSettings. There's also an OAuth2 authorization-server metadata document at /.well-known/oauth-authorization-server.

OIDC defines a discovery document at `/.well-known/openid-configuration` — a JSON metadata file advertising the `issuer` and the absolute URLs of the provider's endpoints (authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint, end_session_endpoint) plus supported scopes, grant types, and signing algorithms. Clients fetch it once to self-configure instead of hardcoding URLs. Spring Authorization Server serves it automatically and, by default, exposes: `/oauth2/authorize` (start the authorization_code flow), `/oauth2/token` (exchange code/credentials for tokens), `/oauth2/jwks` (public keys to verify JWT signatures), `/oauth2/revoke`, `/oauth2/introspect`, `/userinfo`, and OIDC's `/connect/register` if enabled. All of these paths and the issuer are configurable through `AuthorizationServerSettings`. There's also an OAuth2 authorization-server metadata document at `/.well-known/oauth-authorization-server`.

code

java · 11 lines

java

@Bean
AuthorizationServerSettings authorizationServerSettings() {
    return AuthorizationServerSettings.builder()
        .issuer("https://auth.example.com")   // becomes the iss claim + discovery prefix
        // paths shown are the defaults; override only if you must
        .authorizationEndpoint("/oauth2/authorize")
        .tokenEndpoint("/oauth2/token")
        .jwkSetEndpoint("/oauth2/jwks")
        .oidcUserInfoEndpoint("/userinfo")
        .build();
}

go deeper

for a junior

Know discovery is a JSON file listing the provider's endpoints and issuer.

for a middle

Name the default Spring endpoints and where paths/issuer are configured.

for a senior

Explain issuer-matching across discovery, iss claim, and resource server, and proxy pitfalls.

for a principal

Design issuer/hostname strategy across environments and proxies; decide which optional endpoints (introspect, dynamic registration) to enable.

The problem discovery solves. A client (or a resource server) needs to know several URLs and parameters of an identity provider: where to send users to log in, where to swap an authorization code for tokens, and where to fetch the public keys that verify token signatures. Hardcoding all of that is brittle. OIDC Discovery standardizes a single metadata endpoint so clients can bootstrap from just the issuer URL.

The discovery document. At GET {issuer}/.well-known/openid-configuration the provider returns JSON including at minimum:

issuer — the identifier that must exactly match the iss claim in issued tokens.
authorization_endpoint — where the browser is redirected to authenticate/consent.
token_endpoint — where tokens are minted/exchanged.
jwks_uri — URL of the JWK Set (the public keys, in JSON Web Key format, used to verify JWT signatures).
userinfo_endpoint — returns claims about the authenticated user given an access token.
end_session_endpoint, revocation_endpoint, introspection_endpoint — logout, revoke, and introspect.
Capability lists: scopes_supported, response_types_supported, grant_types_supported, id_token_signing_alg_values_supported, code_challenge_methods_supported (PKCE), etc.

Default endpoints in Spring Authorization Server. Registered automatically by OAuth2AuthorizationServerConfigurer:

/oauth2/authorize — the authorization endpoint (front channel, browser redirect).
/oauth2/token — the token endpoint (back channel, POST).
/oauth2/jwks — the JWK Set endpoint, driven by the JWKSource<SecurityContext> bean.
/oauth2/revoke — token revocation.
/oauth2/introspect — token introspection (opaque-token validation for resource servers).
/userinfo — OIDC UserInfo.
/connect/register — OIDC Dynamic Client Registration (off by default).
/.well-known/openid-configuration and /.well-known/oauth-authorization-server — the two metadata documents.

Where the paths come from. AuthorizationServerSettings is the bean that holds the issuer and every endpoint path. You override defaults via its builder: AuthorizationServerSettings.builder().issuer("https://auth.example.com").tokenEndpoint("/oauth2/v2/token").build(). If you change a path here, it is reflected automatically in the discovery document.

The issuer gotcha. The iss claim, the discovery URL prefix, and the value a resource server is configured with (spring.security.oauth2.resourceserver.jwt.issuer-uri) must all match. A mismatch (e.g. behind a reverse proxy that rewrites the host) causes token validation to fail. If you don't set an explicit issuer, the server derives it from the incoming request, which can be wrong behind proxies — set it explicitly in production.

Security note. The discovery and jwks endpoints are public by design (resource servers must reach jwks_uri without credentials). Don't accidentally lock them behind authentication.

When to care. Whenever you integrate a resource server or a client library — point it at the issuer and let discovery do the rest; and whenever you deploy behind a proxy, verify the issuer.

**The problem discovery solves.** A client (or a resource server) needs to know several URLs and parameters of an identity provider: where to send users to log in, where to swap an authorization code for tokens, and where to fetch the public keys that verify token signatures. Hardcoding all of that is brittle. **OIDC Discovery** standardizes a single metadata endpoint so clients can bootstrap from just the issuer URL. **The discovery document.** At `GET {issuer}/.well-known/openid-configuration` the provider returns JSON including at minimum: - `issuer` — the identifier that must exactly match the `iss` claim in issued tokens. - `authorization_endpoint` — where the browser is redirected to authenticate/consent. - `token_endpoint` — where tokens are minted/exchanged. - `jwks_uri` — URL of the **JWK Set** (the public keys, in JSON Web Key format, used to verify JWT signatures). - `userinfo_endpoint` — returns claims about the authenticated user given an access token. - `end_session_endpoint`, `revocation_endpoint`, `introspection_endpoint` — logout, revoke, and introspect. - Capability lists: `scopes_supported`, `response_types_supported`, `grant_types_supported`, `id_token_signing_alg_values_supported`, `code_challenge_methods_supported` (PKCE), etc. **Default endpoints in Spring Authorization Server.** Registered automatically by `OAuth2AuthorizationServerConfigurer`: - `/oauth2/authorize` — the **authorization endpoint** (front channel, browser redirect). - `/oauth2/token` — the **token endpoint** (back channel, POST). - `/oauth2/jwks` — the **JWK Set endpoint**, driven by the `JWKSource<SecurityContext>` bean. - `/oauth2/revoke` — token revocation. - `/oauth2/introspect` — token introspection (opaque-token validation for resource servers). - `/userinfo` — OIDC UserInfo. - `/connect/register` — OIDC Dynamic Client Registration (off by default). - `/.well-known/openid-configuration` and `/.well-known/oauth-authorization-server` — the two metadata documents. **Where the paths come from.** `AuthorizationServerSettings` is the bean that holds the `issuer` and every endpoint path. You override defaults via its builder: `AuthorizationServerSettings.builder().issuer("https://auth.example.com").tokenEndpoint("/oauth2/v2/token").build()`. If you change a path here, it is reflected automatically in the discovery document. **The issuer gotcha.** The `iss` claim, the discovery URL prefix, and the value a resource server is configured with (`spring.security.oauth2.resourceserver.jwt.issuer-uri`) must all match. A mismatch (e.g. behind a reverse proxy that rewrites the host) causes token validation to fail. If you don't set an explicit issuer, the server derives it from the incoming request, which can be wrong behind proxies — set it explicitly in production. **Security note.** The discovery and jwks endpoints are public by design (resource servers must reach jwks_uri without credentials). Don't accidentally lock them behind authentication. **When to care.** Whenever you integrate a resource server or a client library — point it at the issuer and let discovery do the rest; and whenever you deploy behind a proxy, verify the issuer.

A resource server fails to validate tokens after you moved behind an nginx proxy. What's the likely cause?
The issuer no longer matches: the iss claim / discovery document reflects the wrong host. Set an explicit issuer in AuthorizationServerSettings and align the resource server's issuer-uri.
Why must jwks_uri be publicly accessible?
Resource servers fetch the public keys from it (without credentials) to verify JWT signatures; locking it down breaks token validation.

saying these in an interview costs you the question

Thinking discovery returns tokens or secrets (it returns public metadata only)
Assuming endpoint paths are hardcoded rather than configured via AuthorizationServerSettings
Not setting an explicit issuer behind a proxy

What is the OIDC /.well-known discovery endpoint, and which core endpoints does Spring Authorization Server expose by default?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~2 min

▾common follow-ups2 questions

▾red flags3 flags

§ context

▾related questions4 questions

▾related topics3 topics

answer

go deeper

context