docs(keycloak): make the quick start actually runnable

[adityamparikh]

Problem

docs/security/keycloak.md's Quick Start cannot be completed as written. Following it verbatim gives you a server that exits 1 printing nothing but the Spring banner — and once past that, every tool call is rejected.

Three independent gaps, all reproduced against Keycloak 26.0:

1. Step 2 had no commands

# 2. Configure Keycloak (see detailed steps below)
# - Create realm: solr-mcp
# - Create client: solr-mcp-client

A comment, so it reads as skippable. It is not. HttpSecurityConfiguration wires OAuth2 only when an issuer is set, and McpServerOAuth2Configurer builds its NimbusJwtDecoder eagerly during init() — so an OAUTH2_ISSUER_URI pointing at a realm that does not exist aborts context refresh:

Error creating bean with name 'securityFilterChain':
  Unable to resolve the Configuration with the provided Issuer of
  "http://localhost:8180/realms/solr-mcp"

Note the asymmetry that makes this sharp: an issuer left empty starts fine (the chain still returns 401/403). Only a configured-but-unresolvable issuer kills startup.

2. No audience mapper — so every tool call 401s

HttpSecurityConfiguration sets validateAudienceClaim(true) against the resource indicator from resourcePath("/mcp"). Keycloak does not populate aud on its own; a token from the documented client carries only:

"aud": "account"

Result:

401 WWW-Authenticate: Bearer error="invalid_token",
    error_description="... The aud claim is not valid"

docs/security/http.md already documents that Keycloak needs an Audience protocol mapper — keycloak.md just never applied it. This PR adds it to both the scripted and console paths and cross-links http.md.

3. Test users could not get a token at all

The documented user creation omits first/last name, which Keycloak's default user profile requires:

{"error":"invalid_grant","error_description":"Account is not fully set up"}

Two distinct causes produce this identical message, and the doc only ever covered the first:

Cause	Mechanism
Blank firstName / lastName	declarative user-profile validation
Pending required action, usually UPDATE_PASSWORD	required-action gate

The second is the easier one to hit, because the admin console defaults Temporary to ON when setting a password — and step 6 of Creating Test Users said "disable Temporary" without ever saying what breaks if you don't. Neither cause is resolvable through the password grant, which has no browser leg to render the "complete your profile" or "update your password" page; both accounts sign in fine through a browser flow, so the failure looks like it only affects curl.

What changed

• Step 2 is now runnable kcadm commands — realm, public client, audience mapper, user, password.
• New step 4 proves security is actually on. An anonymous tools/list succeeds by design (/mcp is permitted at the HTTP layer; authorization is per-tool via @PreAuthorize), so only a tools/call distinguishes a secured server from an unsecured one. Both outcomes are shown.
• Console instructions gain the audience mapper, the first/last name fields, and a note that Direct access grants is what makes the existing password-grant curl work.
• Troubleshooting gains the four failure modes actually encountered, each with its real symptom text.
• Account is not fully set up now documents both causes — with one command that reports profile fields and requiredActions together, a table of the four blocking required actions, and console + REST remedies for clearing them. The Temporary trap is called out at the Creating Test Users step and on the REST provisioning example (which correctly keeps "temporary": true — it is the right default for a real user, just not for a scripted one).

Verification

The whole Quick Start was executed verbatim against Keycloak 26.0 from a freshly deleted and recreated realm. Recorded outputs are the real ones:

--- unauthenticated:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Access Denied"}],"isError":true}}
--- authenticated:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"[\"books\",\"films\",\"streaming-shows\"]"}],"isError":false}}

Audience mapper effect confirmed by removing it and re-testing: aud drops to account and the same call returns 401 "The aud claim is not valid".

The required-action cause was reproduced separately against the same Keycloak 26.0 instance: an account with firstName/lastName populated and emailVerified: true still failed the password grant while carrying requiredActions: ["UPDATE_PASSWORD"], and succeeded once that action was cleared — nothing else changed. firstName and lastName were confirmed required: true via GET /admin/realms/solr-mcp/users/profile rather than assumed.

Docs-only — no source or test changes.

Related

Diagnosing this surfaced a separate bug that made the failure invisible: logback.xml shadows logback-spring.xml, so HTTP mode logs nothing and the startup exception above never reaches the console. Fixed in #189. The troubleshooting section here mentions the LOGGING_CONFIG=classpath:logback-spring.xml workaround so this doc stands alone whether or not #189 has merged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bbs8w62uwcx12ZE8E2xg8P