Spring Boot Flow Recipes

RFC 6749 §4.1 + RFC 7636 — see Authorization Code and PKCE for the full protocol treatment. This grant already has two complete Spring worked examples elsewhere in the repository, so there is no third one here:

RFC 6749 §4.4 — see Client Credentials and Client Authentication for the full grant and the client-authentication-method comparison. This is service-to-service: there is no user, no browser redirect and (per that page) no refresh token, so the whole recipe is a registration plus a manager plus an interceptor.

Client-side config — register the partner API as an OAuth2 client with the client_credentials grant:

Every call through partnerApiClient runs the interceptor first; the interceptor asks the manager for an OAuth2AuthorizedClient, which requests (and caches) a token the first time and reuses it until it is close to expiry, at which point the manager silently requests a fresh one — there is no user session to redirect and no refresh token in this grant, so "refreshing" here just means asking the token endpoint again with the same client credentials.

The resulting exchange, once per token acquisition (not once per API call):

followed by the actual API call carrying that token: GET /orders HTTP/1.1 with Authorization: Bearer eyJhbGciOiJSUzI1NiIs…​.

RFC 6749 §6 — see Access and Refresh Tokens for rotation, reuse detection and the absolute-vs-idle-expiry distinction at the protocol level. On the client side there is usually no recipe to write: add .refreshToken() to the same provider builder used above and Spring handles the rest transparently.

What actually happens on expiry: every OAuth2AuthorizedClientManager.authorize(…​) call re-checks the stored the OAuth2AuthorizedClient access token against its expires_at (with a small clock-skew allowance) before handing it back. If it is expired (or close to it) and a refresh token is present, the refresh-token provider added by .refreshToken() silently exchanges it at the token endpoint and the manager saves the new OAuth2AuthorizedClient — including whatever new refresh token the authorization server chose to issue — back into the OAuth2AuthorizedClientRepository, before your interceptor or filter ever sees a stale token. If the refresh attempt itself fails (the refresh token was rotated-and-reused, revoked, or has hit its absolute lifetime), the manager reports the client as no longer authorized: for authorization_code, that means the next request has to go through the interactive /oauth2/authorization/{registrationId} redirect again; for client_credentials, which is issued no refresh token at all, "refreshing" is simply requesting a brand-new token with the same client credentials, which the clientCredentials() provider already does on every expiry.

None of this is configurable from the client side beyond adding or omitting .refreshToken() to the builder — rotation policy, reuse detection and token lifetimes are entirely the authorization server’s decision, covered on Access and Refresh Tokens.

RFC 8628 — see Device Authorization Grant for the polling loop and the cross-device phishing mitigations. Spring supports this grant fully on the authorization-server side; on the client side there is a real gap.

RFC 8693 — see Token Exchange and Assertion Grants for impersonation vs. delegation and the act claim. Spring Authorization Server accepts this grant at the token endpoint alongside the others listed above; as a client, use the dedicated provider and response client:

TokenExchangeOAuth2AuthorizedClientProvider talks to the token endpoint through a RestClientTokenExchangeTokenResponseClient. The wire exchange, a service exchanging a caller’s token for one scoped down to an internal call:

The response is an ordinary token response with issued_token_type echoing back urn:ietf:params:oauth:token-type:access_token.

RFC 7523 (the JWT profile of the RFC 7521 assertion framework) — see Token Exchange and Assertion Grants. This is a client-side-only grant in Spring Authorization Server’s own vocabulary: it is not in the list of grants the authorization server’s token endpoint documents accepting from arbitrary registered clients (that list is authorization_code, refresh_token, client_credentials, device code and token exchange) — jwt-bearer is the client presenting an assertion it already holds, most often issued by a different trusted party, to obtain a token without a fresh interactive login.

JwtBearerOAuth2AuthorizedClientProvider talks to the token endpoint through a RestClientJwtBearerTokenResponseClient. Wire exchange:

RFC 7523 (client authentication) — see Client Credentials and Client Authentication for the full comparison of client-authentication methods. ClientAuthenticationMethod documents client_secret_basic, client_secret_post, private_key_jwt, client_secret_jwt and none.

client_secret_jwt uses the same NimbusJwtClientAuthenticationParametersConverter, with a resolver that builds an OctetSequenceKey from clientRegistration.getClientSecret() instead of an asymmetric keypair, and client-authentication-method: client_secret_jwt; wire it onto a RestClientClientCredentialsTokenResponseClient the same way for the client_credentials grant.

RFC 9449 — see Sender-Constrained Tokens: DPoP and mTLS for the proof-JWT anatomy (htm, htu, iat, jti, ath) and the cnf/jkt confirmation claim in full.

Authorization-server side. Spring Authorization Server issues DPoP-bound tokens automatically when the client includes a DPoP proof header on its request to the token endpoint — there is no separate enabling switch documented for the authorization-server side; sending the header is what turns a request from bearer to DPoP.

Resource-server side. Once oauth2ResourceServer(o → o.jwt(…​)) is configured — the same configuration already documented on Spring Security — Spring Security supports verifying DPoP-bound access tokens without a separate .dpop(…​) builder call: there is no dedicated DPoP DSL method on OAuth2ResourceServerConfigurer to write. What the reference documentation shows is the wire format your resource server must expect and can rely on Spring Security to check:

with token_type: "DPoP" in the original token response and a confirmation claim inside the access token JWT:

The DPoP request header carries the proof JWT (typ: "dpop+jwt"); Spring Security checks that its embedded public key hashes (SHA-256) to the same jkt value bound in the access token, and that the proof’s htm/htu match the actual request and its jti has not been replayed.

Every client-side type above has a direct reactive counterpart:

The device-code, token-exchange and jwt-bearer providers above have no separate reactive class named in the reference documentation beyond the same .provider(…​) composition pattern on the reactive builder; the gaps noted for device code and mTLS apply identically on the reactive stack.