feat(compose): provision Keycloak with the realm the http profile needs

[adityamparikh]

Problem

The http profile authenticates against Keycloak, but nothing started one. A developer had to run the container by hand and then script a realm, a client and an audience mapper before the server would boot. The mapper is easy to miss and fails quietly: Keycloak does not honour the RFC 8707 resource= parameter, so without it a token is issued normally and validateAudienceClaim(true) answers 401.

Change

compose.yaml gains a keycloak service that imports keycloak/solr-mcp-realm.json at startup, so the realm, both clients and the mapper exist before the server asks for a token:

Client / user	Purpose
solr-mcp-service	Confidential, service accounts enabled: machine-to-machine callers
solr-mcp-client	Public, redirect URIs for MCP Inspector
testuser / testpassword	The password-grant examples in keycloak.md

Both clients carry the audience mapper for http://localhost:8080/mcp. The credentials are development credentials, committed on purpose; a real deployment provisions its own.

The service sits behind the http compose profile, which application-http.properties activates through spring.docker.compose.profiles.active, so a plain docker compose up -d for STDIO users does not pull Keycloak or wait on its healthcheck. Start it by hand with docker compose --profile http up -d.

The healthcheck is load-bearing. The server resolves the issuer while building its JWT decoder and fails to boot if the realm is not answering, so Spring Boot's compose support must wait for the container to be healthy. Keycloak's image ships neither curl nor wget, so the probe uses bash's /dev/tcp against the management port.

docs/security/keycloak.md Quick Start points at the imported realm and tells compose users to reuse solr-mcp-service instead of creating a client by hand.

Verification

Check	Result
Container health	healthy via the declared healthcheck
realms/solr-mcp/.well-known/openid-configuration	200
client_credentials on solr-mcp-service	aud: ["http://localhost:8080/mcp", "account"]
Password grant on solr-mcp-client as testuser	aud: "http://localhost:8080/mcp"
./gradlew build on Java 25	403 tests, 0 failures, 7 skipped

Not covered: an end-to-end call against a running MCP server.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CiUHyyXLTo9ATdgg8eRFZJ

[adityamparikh]

Rebased onto main @ b4ffe18. One conflict in docs/security/keycloak.md (#190 rewrote the Quick Start intro): resolved by keeping both — this PR's compose callout first, then main's runnable-block intro. Added one sentence to the callout: the manual walkthrough and the compose service both bind port 8180, so anyone following the manual path should start the server with SPRING_DOCKER_COMPOSE_ENABLED=false. Prerequisites now list Keycloak among the compose-started containers. ./gradlew build in a clean worktree: 403 tests, 0 failures.