Skip to content

Commit b8735ab

Browse files
Hann244jzheaux
authored andcommitted
Clarify Resource Server startup expectations
Clarify that Spring Boot defers OIDC discovery by default. Closes gh-16708 Signed-off-by: [CLOUD4] 한현 <gusgus1467@naver.com>
1 parent 68a02ff commit b8735ab

1 file changed

Lines changed: 21 additions & 4 deletions

File tree

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

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

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,17 +40,34 @@ 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 startup process:
43+
It achieves this through a deterministic discovery process when the `JwtDecoder` is initialized from the issuer location:
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-
A consequence of this process is that the authorization server must be up and receiving requests in order for Resource Server to successfully start up.
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.
5153

5254
[NOTE]
53-
If the authorization server is down when Resource Server queries it (given appropriate timeouts), then startup will fail.
55+
====
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.
70+
====
5471

5572
=== Runtime Expectations
5673

@@ -66,7 +83,7 @@ So long as this scheme is indicated, Resource Server will attempt to process the
6683

6784
Given a well-formed JWT, Resource Server will:
6885

69-
1. Validate its signature against a public key obtained from the `jwks_url` endpoint during startup and matched against the JWT
86+
1. Validate its signature against a public key obtained from the `jwks_url` endpoint during startup or on first request, depending on configuration, and matched against the JWT
7087
2. Validate the JWT's `exp` and `nbf` timestamps and the JWT's `iss` claim, and
7188
3. Map each scope to an authority with the prefix `SCOPE_`.
7289

0 commit comments

Comments
 (0)