docs(security): document client credentials for machine-to-machine callers

[adityamparikh]

What's missing today

Every token example in docs/security/keycloak.md uses the password grant with testuser. A
service that calls this MCP server on its own behalf — an agent, a scheduled job, another
application — has no user to authenticate as, and no documented path. The confidential client it
needs is already described under Creating Clients; what was missing is the grant that uses it.

The part that actually bites

The audience mapper. The Quick Start attaches it to the public client used by MCP Inspector, so
a service client created by following Creating Clients has none of its own:

token issued normally  →  server answers 401  →  nothing in the token request hinted at a problem

validateAudienceClaim(true) finds no matching aud and rejects it. The new Machine-to-Machine
Tokens section states where the mapper belongs, shows adding it to the service client, and shows
confirming that the claim landed before an application is pointed at it.

Also fixed: the audience check under Troubleshooting

echo $TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq

A JWT payload is base64url without padding, so base64 -d truncates it and jq reports
parse error: Unfinished string at EOF — which reads like a malformed token when the token is
perfectly fine. That is a bad failure mode for a troubleshooting step whose whole job is telling you
whether the token is good. Replaced with a jq-only decode that tolerates the missing padding:

echo "$TOKEN" | jq -R 'split(".")[1] | @base64d | fromjson'

Verification

Every command in the new section was run verbatim against Keycloak 26 and a running Solr MCP server,
and produces the output shown in the doc:

Step	Result
client_credentials grant against the confidential client	token issued
aud check	["http://localhost:8080/mcp", "account"]
/.well-known/oauth-protected-resource	http://localhost:8080/mcp
Old decode idiom	parse error: Unfinished string at EOF
New decode idiom	claim printed

Docs only — no code or test changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_011nUD34DFfoJeyQRTquPy7a