Add OAuth2 resource server project: JWT validation, JWKS and key rotation

Companion code for the follow-up article. The repository now holds two Maven
projects sharing one docs/ tree:

  jwt-authentication/       the hand-written filter application (unchanged, moved)
  oauth2-resource-server/   a resource server, a Keycloak compose, and a stub
                            issuer whose JWK Set can be mutated on command

The stub exists because Keycloak will not rotate a signing key at a chosen
second, report how many times its JWKS endpoint was fetched, or drop a key from
the published set on request - and the caching and rotation measurements need
all three. The Keycloak run confirms the same code path against a real issuer.

Findings captured under docs/output/, all from real runs:

  * The default validator stack does not check aud. A token minted for another
    service in the same realm is accepted.
  * Spring Security builds its JWKSource with refreshAheadCache(false) and
    rateLimited(false), overriding two of Nimbus's protective defaults, and
    enables Nimbus caching only when NO Spring cache was supplied - so
    supplying one removes the five-minute expiry.
  * A key retired from the JWK Set stops being accepted at t+300s with the
    default cache, and never with a Spring cache that has no TTL.
  * 25 tokens carrying an unknown kid produce 25 JWKS fetches at the issuer,
    through permitAll() endpoints included.
  * A hyphenated client id in an authorities-claim-expression parses as
    subtraction; the SpelEvaluationException is swallowed and logged at TRACE.
  * A clientScopes key in a Keycloak realm import replaces the built-in scopes
    rather than adding to them.

New docs chapters 12-18. README covers both projects. Existing docs and scripts
updated for the new paths; no docs/output/ file from the first article moved, so
links in the published article still resolve.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013f7f2XZXrQ6gW3RtZE187t

oauth2-resource-server/src/main/resources/application-keycloak.yaml

@@ -0,0 +1,11 @@
+# Points the resource server at the Keycloak in docker/compose.yaml.
+# Identical shape to application-stub.yaml - one property.
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: http://localhost:8080/realms/demo
+
+demo:
+  jwk-set-uri: http://localhost:8080/realms/demo/protocol/openid-connect/certs

oauth2-resource-server/src/main/resources/application-props.yaml

@@ -0,0 +1,8 @@
+# Audience validation with no Java at all. Boot turns this into a JwtClaimValidator on
+# `aud` and appends it to the default validator stack.
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          audiences: reports-api

oauth2-resource-server/src/main/resources/application-propsroles-broken.yaml

@@ -0,0 +1,15 @@
+# The same configuration with the hyphenated client id unquoted. This is what most people
+# write first, and it fails silently: no error, no WARN, just an authority that never
+# appears and a 403 nobody can explain.
+#
+# The `trace` profile makes the swallowed message visible.
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          principal-claim-name: preferred_username
+          authority-prefix: "ROLE_"
+          authorities-claim-expressions:
+            - "[realm_access][roles]"
+            - "[resource_access][reports-api][roles]"

oauth2-resource-server/src/main/resources/application-propsroles.yaml

@@ -0,0 +1,28 @@
+# Keycloak's nested roles, mapped with configuration only.
+#
+# `authorities-claim-expressions` is a Spring Boot 4 property. Each entry is a SpEL
+# expression evaluated against the claim map, so a nested claim needs no Java.
+#
+# NOTE THE QUOTES around 'reports-api'. Inside a SpEL indexer the contents are an
+# expression, not a literal key, so [resource_access][reports-api][roles] parses as
+# `reports` MINUS `api` and blows up with EL1008E. ExpressionJwtGrantedAuthoritiesConverter
+# catches ExpressionException, substitutes an empty authority list, and logs the reason at
+# TRACE only - so the failure surfaces as a 403 with nothing in the log to explain it.
+# See application-propsroles-broken.yaml for the other spelling, and docs/14.
+#
+# Two more consequences of taking this route:
+#   * `authority-prefix` is ONE value applied to every expression. A mixed mapping -
+#     SCOPE_ for scopes, ROLE_ for roles - cannot be expressed here.
+#   * naming expressions REPLACES the default JwtGrantedAuthoritiesConverter, so the
+#     SCOPE_* authorities it produced from the `scope` claim disappear unless you add
+#     `[scope]` as an expression too - and then it gets the ROLE_ prefix as well.
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          principal-claim-name: preferred_username
+          authority-prefix: "ROLE_"
+          authorities-claim-expressions:
+            - "[realm_access][roles]"
+            - "[resource_access]['reports-api'][roles]"

oauth2-resource-server/src/main/resources/application-stub.yaml

@@ -0,0 +1,14 @@
+# Points the resource server at the in-repo stub issuer on :9000.
+# Discovery is used, exactly as with Keycloak: Spring reads
+# /.well-known/openid-configuration, takes jwks_uri from it, and validates `iss`
+# against this value.
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: http://localhost:9000
+
+# The hardened profile builds the JWKSource itself and therefore cannot discover this.
+demo:
+  jwk-set-uri: http://localhost:9000/jwks.json

oauth2-resource-server/src/main/resources/application-stubissuer.yaml

@@ -0,0 +1,5 @@
+# The stub authorization server itself. Nothing here is a resource server.
+server:
+  port: 9000
+stub:
+  issuer: http://localhost:9000

oauth2-resource-server/src/main/resources/application-trace.yaml

@@ -0,0 +1,6 @@
+# Everything the resource server does to a token, logged. The line worth waiting for is
+# the one from BearerTokenAuthenticationFilter naming the validator that refused.
+logging:
+  level:
+    org.springframework.security: TRACE
+    org.springframework.web.client: DEBUG

oauth2-resource-server/src/main/resources/application-tracespel.yaml

@@ -0,0 +1,4 @@
+# Just enough logging to see a claim expression fail, and nothing else.
+logging:
+  level:
+    org.springframework.security.oauth2.server.resource.authentication.ExpressionJwtGrantedAuthoritiesConverter: TRACE

oauth2-resource-server/src/main/resources/application.yaml

@@ -0,0 +1,16 @@
+# Shared defaults. The issuer is deliberately NOT set here - it arrives with the
+# `stub` or `keycloak` profile, so that the same application code demonstrably runs
+# against a toy issuer and against a real one with no source difference at all.
+spring:
+  application:
+    name: oauth2-resource-server-demo
+
+server:
+  port: 8081
+
+demo:
+  audience: reports-api
+
+logging:
+  level:
+    org.springframework.security.oauth2: INFO