You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/modules/ROOT/pages/servlet/oauth2/resource-server/jwt.adoc
+21-4Lines changed: 21 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,17 +40,34 @@ And that's it!
40
40
41
41
When this property and these dependencies are used, Resource Server will automatically configure itself to validate JWT-encoded Bearer Tokens.
42
42
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:
44
44
45
45
1. Query the Provider Configuration or Authorization Server Metadata endpoint for the `jwks_url` property
46
46
2. Query the `jwks_url` endpoint for supported algorithms
47
47
3. Configure the validation strategy to query `jwks_url` for valid public keys of the algorithms found
48
48
4. Configure the validation strategy to validate each JWTs `iss` claim against `https://idp.example.com`.
49
49
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.
51
53
52
54
[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
+
====
54
71
55
72
=== Runtime Expectations
56
73
@@ -66,7 +83,7 @@ So long as this scheme is indicated, Resource Server will attempt to process the
66
83
67
84
Given a well-formed JWT, Resource Server will:
68
85
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
70
87
2. Validate the JWT's `exp` and `nbf` timestamps and the JWT's `iss` claim, and
71
88
3. Map each scope to an authority with the prefix `SCOPE_`.
0 commit comments