diff --git a/docs/modules/ROOT/pages/servlet/oauth2/resource-server/jwt.adoc b/docs/modules/ROOT/pages/servlet/oauth2/resource-server/jwt.adoc index 3cb841115f..7a614104f0 100644 --- a/docs/modules/ROOT/pages/servlet/oauth2/resource-server/jwt.adoc +++ b/docs/modules/ROOT/pages/servlet/oauth2/resource-server/jwt.adoc @@ -40,33 +40,19 @@ And that's it! When this property and these dependencies are used, Resource Server will automatically configure itself to validate JWT-encoded Bearer Tokens. -It achieves this through a deterministic discovery process when the `JwtDecoder` is initialized from the issuer location: +It achieves this through a deterministic discovery process it launches at the first request containing a JWT: 1. Query the Provider Configuration or Authorization Server Metadata endpoint for the `jwks_url` property 2. Query the `jwks_url` endpoint for supported algorithms 3. Configure the validation strategy to query `jwks_url` for valid public keys of the algorithms found 4. Configure the validation strategy to validate each JWTs `iss` claim against `https://idp.example.com`. -In Spring Security, constructing a decoder via `JwtDecoders.fromIssuerLocation` or `NimbusJwtDecoder.withIssuerLocation(...).build()` performs this discovery immediately. -However, in Spring Boot 2.6+, the auto-configured decoder is lazy and defers discovery until the first request that contains a JWT. -This means that, by default, Resource Server startup is not coupled to the authorization server's availability. +One benefit of deferring this process is that Resource Server startup is not coupled to the authorization server's availability. [NOTE] ==== -If you want the application to fail startup when the authorization server is not available, -explicitly configure a `JwtDecoder` so that discovery happens at startup: - -.Eager Validation Configuration -[source,java] ----- -@Bean -JwtDecoder jwtDecoder() { - return JwtDecoders.fromIssuerLocation(issuerUri); -} ----- - -Otherwise, if discovery is deferred (the default in Spring Boot 2.6+), -the first request bearing a JWT will fail if the authorization server is unavailable. +This deferral is managed by javadoc:org.springframework.security.oauth2.jwt.SupplierJwtDecoder[`SupplierJwtDecoder`]. +Consider wrapping any <> you declare in order to preserve this behavior. ==== === Runtime Expectations @@ -128,7 +114,7 @@ Ultimately, the returned `JwtAuthenticationToken` will be set on the xref:servle [[oauth2resourceserver-jwt-jwkseturi]] == Specifying the Authorization Server JWK Set Uri Directly -If the authorization server doesn't support any configuration endpoints, or if Resource Server must be able to start up independently from the authorization server, then the `jwk-set-uri` can be supplied as well: +If the authorization server doesn't support any configuration endpoints, or if Resource Server must be able to initialize independently from the authorization server, then the `jwk-set-uri` can be supplied as well: [source,yaml] ----