OAuth2, OIDC & Resource Server

JwtTimestampValidator checks the token's time claims: it rejects tokens that are expired (exp) or not yet valid (nbf). It allows a default 60-second clock skew so tokens are not rejected just because server clocks differ slightly.

An OAuth2AuthorizedClient holds the access token (and optional refresh token) your app got to call another API on a user's behalf. oauth2Client() lets your app CALL other APIs; oauth2Login() logs the USER into your app.

oauth2Login() lets users sign in to your app using an external provider like Google or GitHub. It uses the OAuth2 authorization-code flow: Spring redirects the user to the provider, gets a code back, and exchanges it for tokens to log the user in.

In the SecurityFilterChain, call http.oauth2ResourceServer(oauth2 -> oauth2.jwt(...)). Add a jwk-set-uri or issuer-uri in application.yml so Spring can fetch the keys and verify each incoming Bearer token's signature.

An opaque token is a random string with no readable content. The resource server can't decode it, so it calls the authorization server's introspection endpoint to check it. You enable it with oauth2ResourceServer().opaqueToken().

The access token authorizes API calls (it says what the client may do); the id token is proof of the user's identity for the client (it says who logged in). The id token is only issued when the client requests the openid scope.

Combine validators with DelegatingOAuth2TokenValidator, which runs each in turn and aggregates errors, then attach it via decoder.setJwtValidator(...). JwtValidators.createDefaultWithIssuer(issuer) is preferred because it bundles the timestamp validator plus issuer check so you don't accidentally drop the defaults.

Add an OAuth2AuthorizedClient parameter annotated @RegisteredOAuth2AuthorizedClient("registration-id") to your controller method. Spring resolves it, authorizing (or refreshing) as needed, and you read client.getAccessToken().getTokenValue().

A ClientRegistration holds the config for one OAuth2 provider — client id/secret, scopes, and the provider's endpoint URLs. ClientRegistrationRepository is the store of all registrations, looked up by registrationId. Spring Boot builds them from your application.yml properties.

OAuth2User is the authenticated principal for plain OAuth2 logins, exposing the provider's user attributes and granted authorities. OidcUser extends it for OIDC logins, adding access to the id_token and standard OIDC claims. OAuth2UserService loads that principal after the token exchange.

NimbusJwtDecoder downloads the authorization server's public keys (the JWK set), picks the key matching the token header's kid, and checks the signature. jwk-set-uri points straight at the keys; issuer-uri discovers the jwks URL and also validates the iss claim.

OpaqueTokenIntrospector has one method, introspect(token), that calls the introspection endpoint and returns an OAuth2AuthenticatedPrincipal with the token's attributes and authorities. Spring's OpaqueTokenAuthenticationProvider calls it and builds a BearerTokenAuthentication.

By default Spring reads the scope (or scp) claim and turns each value into a SCOPE_<value> authority. To use different claims — like Keycloak realm roles — supply a JwtAuthenticationConverter with a custom JwtGrantedAuthoritiesConverter (prefix + claim name) via oauth2ResourceServer().jwt().jwtAuthenticationConverter(...).

JWTs are validated locally (fast, no network) but can't be revoked until they expire and expose claims to anyone. Opaque tokens require a network introspection call per request (slower, central dependency) but give instant revocation and keep claims private. Choose opaque when revocation matters, JWT for scale/latency.

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.

Register an OAuth2TokenCustomizer<JwtEncodingContext> bean to add or change claims per token type. Provide a JWKSource<SecurityContext> bean holding your signing key(s); the server signs JWTs with the private key and publishes the public key at /oauth2/jwks.

Implement OAuth2TokenValidator<Jwt>, check that jwt.getAudience() contains your API's identifier, and return OAuth2TokenValidatorResult.success() or failure with an OAuth2Error. It matters because it stops a token minted for another API from being accepted by yours.

Create a NimbusJwtEncoder backed by a JWKSource holding your signing key. Build a JwtClaimsSet (issuer, subject, audience, issuedAt, expiresAt, custom claims) and a JwsHeader (algorithm), then call jwtEncoder.encode(JwtEncoderParameters.from(header, claims)) to get a signed Jwt whose getTokenValue() is the JWT string.

Register a client with authorization-grant-type: client_credentials (client id, secret, token-uri, scopes). No user is involved — the app authenticates itself. A ClientCredentialsOAuth2AuthorizedClientProvider fetches the token; you attach it to downstream calls.

Manager orchestrates authorizing a client; Provider does the actual grant (code/client_credentials/refresh); Service stores authorized clients application-wide; Repository is the per-request/session store that (by default) delegates to the Service for logged-in users.

If an OAuth2AuthorizedClient has a refresh token and its access token is expired, the RefreshTokenOAuth2AuthorizedClientProvider trades the refresh token for a fresh access token automatically when you next request the client. It never does the initial login.

For OIDC logins Spring parses the id_token JWT, checks its signature against the provider's public keys (JWK set), and verifies claims like issuer, audience, expiry, and the nonce. Only if all checks pass is the OidcUser created and the user logged in.

Validate exp/nbf (timestamps) and iss (issuer) — the defaults cover these when you use issuer-uri. Add an audience (aud) check with a custom OAuth2TokenValidator<Jwt> combined via DelegatingOAuth2TokenValidator and set it on the NimbusJwtDecoder.

Wrap the OpaqueTokenIntrospector in a cache keyed by the token so repeated requests skip the introspection call. Bound the cache by a short TTL and the token's exp. The cost is that a revoked token stays accepted until its cache entry expires.

Persist clients and authorizations in a shared database (Jdbc*Repository, not in-memory), load stable signing keys from a secret store with a rotation plan, set an explicit issuer that matches the public URL behind your proxy, and enforce PKCE/consent and short token TTLs.

Each resource server keeps the default timestamp validator, adds issuer validation bound to the trusted authorization server, and adds an audience validator for its own identifier. Keep clock skew tight, verify signatures against a rotating JWK set by kid, and fail closed on any error.

Plug in a custom OAuth2UserService/OidcUserService that delegates to the default, then enriches the principal: look up or just-in-time create a local account keyed by issuer+subject, and translate provider claims into GrantedAuthorities. Return a custom OAuth2User/OidcUser carrying those authorities.

Use short-lived JWTs internally for low-latency, no-network validation, and opaque tokens (with introspection) where instant revocation or claim confidentiality matters. A common topology: opaque tokens at the edge, exchanged for internal JWTs, with introspection or a denylist guarding sensitive operations.

For many issuers, use a JwtIssuerAuthenticationManagerResolver so each tenant's iss routes to its own decoder. Choose local JWT validation for speed and offline verification; choose opaque-token introspection when you need instant revocation and central control, at the cost of a network call per request.