Skip to content

Commit 48112d3

Browse files
committed
Polish Resource Server startup expectations
Issue gh-16708 Signed-off-by: Josh Cummings <3627351+jzheaux@users.noreply.github.com>
1 parent b8735ab commit 48112d3

1 file changed

Lines changed: 5 additions & 19 deletions

File tree

  • docs/modules/ROOT/pages/servlet/oauth2/resource-server

docs/modules/ROOT/pages/servlet/oauth2/resource-server/jwt.adoc

Lines changed: 5 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -40,33 +40,19 @@ And that's it!
4040

4141
When this property and these dependencies are used, Resource Server will automatically configure itself to validate JWT-encoded Bearer Tokens.
4242

43-
It achieves this through a deterministic discovery process when the `JwtDecoder` is initialized from the issuer location:
43+
It achieves this through a deterministic discovery process it launches at the first request containing a JWT:
4444

4545
1. Query the Provider Configuration or Authorization Server Metadata endpoint for the `jwks_url` property
4646
2. Query the `jwks_url` endpoint for supported algorithms
4747
3. Configure the validation strategy to query `jwks_url` for valid public keys of the algorithms found
4848
4. Configure the validation strategy to validate each JWTs `iss` claim against `https://idp.example.com`.
4949

50-
In Spring Security, constructing a decoder via `JwtDecoders.fromIssuerLocation` or `NimbusJwtDecoder.withIssuerLocation(...).build()` performs this discovery immediately.
51-
However, in Spring Boot 2.6+, the auto-configured decoder is lazy and defers discovery until the first request that contains a JWT.
52-
This means that, by default, Resource Server startup is not coupled to the authorization server's availability.
50+
One benefit of deferring this process is that Resource Server startup is not coupled to the authorization server's availability.
5351

5452
[NOTE]
5553
====
56-
If you want the application to fail startup when the authorization server is not available,
57-
explicitly configure a `JwtDecoder` so that discovery happens at startup:
58-
59-
.Eager Validation Configuration
60-
[source,java]
61-
----
62-
@Bean
63-
JwtDecoder jwtDecoder() {
64-
return JwtDecoders.fromIssuerLocation(issuerUri);
65-
}
66-
----
67-
68-
Otherwise, if discovery is deferred (the default in Spring Boot 2.6+),
69-
the first request bearing a JWT will fail if the authorization server is unavailable.
54+
This deferral is managed by javadoc:org.springframework.security.oauth2.jwt.SupplierJwtDecoder[`SupplierJwtDecoder`].
55+
Consider wrapping any <<oauth2resourceserver-jwt-decoder,`JwtDecoder` `@Bean`>> you declare in order to preserve this behavior.
7056
====
7157

7258
=== Runtime Expectations
@@ -128,7 +114,7 @@ Ultimately, the returned `JwtAuthenticationToken` will be set on the xref:servle
128114
[[oauth2resourceserver-jwt-jwkseturi]]
129115
== Specifying the Authorization Server JWK Set Uri Directly
130116

131-
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:
117+
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:
132118

133119
[source,yaml]
134120
----

0 commit comments

Comments
 (0)