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

jwt-authentication/scripts/rs256-demo.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Requires: --spring.profiles.active=rs256
+set -u
+BASE="${1:-http://localhost:8080}"
+show() {
+  local out; out=$(curl -sS -D /tmp/.h -o /tmp/.b -w '%{http_code}' "$@")
+  printf 'HTTP %s\n' "$out"
+  grep -iE '^www-authenticate:' /tmp/.h | sed 's/\r$//'
+  [ -s /tmp/.b ] && { python3 -m json.tool < /tmp/.b 2>/dev/null || cat /tmp/.b; echo; }
+}
+jwt_part(){ echo "$1" | cut -d. -f$(( $2 + 1 )) | tr '_-' '/+' | sed 's/$/==/' | base64 -d 2>/dev/null | python3 -m json.tool 2>/dev/null; }
+hr(){ printf '\n%s\n' "--------------------------------------------------------------------------"; }
+
+echo "=========================================================================="
+echo " jwt-auth-demo - RS256 variant"
+echo " profiles: rs256   (private key signs, public key / JWKS verifies)"
+echo "=========================================================================="
+
+hr; echo "# 1. The public half, published as a JWK Set. No private material here -"
+echo "#    n and e only. Any number of resource servers can poll this."
+echo; show "$BASE/.well-known/jwks.json"
+
+hr; echo "# 2. Login. Same endpoint, same request, different signature algorithm."
+echo; show -X POST "$BASE/api/auth/login" -H 'Content-Type: application/json' \
+     -d '{"username":"root","password":"root-password"}'
+TOK=$(python3 -c "import json;print(json.load(open('/tmp/.b'))['accessToken'])")
+
+hr; echo "# 3. The JOSE header now carries alg=RS256 and the kid that selects the key."
+echo; jwt_part "$TOK" 0
+
+hr; echo "# 4. Token length. RS256 signatures are 256 bytes; HS256 signatures are 32."
+echo
+printf '  RS256 access token: %s characters\n' "${#TOK}"
+printf '  signature segment : %s characters\n' "$(echo "$TOK" | cut -d. -f3 | wc -c)"
+
+hr; echo "# 5. It works exactly the same from the caller's side."
+echo; show "$BASE/api/me" -H "Authorization: Bearer $TOK"
+
+hr; echo "# 6. Tampered payload, original signature -> 401, same as HS256."
+HDR=$(echo "$TOK" | cut -d. -f1); SIG=$(echo "$TOK" | cut -d. -f3)
+FORGED=$(echo "$TOK" | cut -d. -f2 | tr '_-' '/+' | sed 's/$/==/' | base64 -d 2>/dev/null \
+  | sed 's/"sub":"root"/"sub":"mallory"/' | base64 -w0 | tr '/+' '_-' | tr -d '=')
+echo; show "$BASE/api/me" -H "Authorization: Bearer $HDR.$FORGED.$SIG"
+
+hr; echo "# end"