Skip to content
Back to search

keycloak-mcp-security-demo

A Keycloak MCP security demo using SPIFFE/SPIRE for workload authentication, Cedar for per-tool authorization, and OAuth token exchange for delegated Admin API calls.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gaelnite--keycloak-mcp-security-demo/badge.svg)](/listings/gaelnite--keycloak-mcp-security-demo)

HTML

<a href="/listings/gaelnite--keycloak-mcp-security-demo"><img src="/api/listings/gaelnite--keycloak-mcp-security-demo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From the repository root, use Docker Compose v2 and a free loopback port.

KC_MCP_DEMO_PORT=49448 docker compose -p keycloak-mcp-delegated \
  -f deploy/docker/compose.yaml \
  -f deploy/docker/compose.interactive.yaml \
  -f deploy/docker/compose.delegated.yaml \
  up --build -d --wait

The installer generates fixture credentials. Export the demo CA, sign in as helpdesk, and select `keycloak.users.read` to try an allowed read at `https://localhost:49448/mcp`. Realm administrators can also select client reads and the fixture locale write. With no selected scopes, desktop discovery is empty. [Run the delegated demo](docs/MCP-DELEGATION.md) · [Desktop sign-in and scopes](docs/MCP-INTERACTIVE.md)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 95 lines
  1. # Keycloak MCP security reference (experimental)
  2. [![CI](https://github.com/gaelnite/keycloak-mcp-security-demo/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gaelnite/keycloak-mcp-security-demo/actions/workflows/ci.yml)
  3. ## Purpose
  4. This demo shows how a Keycloak administrator can use a desktop assistant like
  5. Codex to carry out specific tasks in Keycloak. The administrator signs in and
  6. chooses what to allow, then can ask the assistant to look up a user or a
  7. registered application.
  8. The desktop client gets an OAuth access token for the MCP server with scopes
  9. the administrator selects from their available permissions. For each tool
  10. call, the server checks the token and uses Cedar to decide whether the call
  11. is allowed. It then authenticates to Keycloak with its own SPIFFE identity,
  12. issued by SPIRE, and exchanges the user's token for a separate, short-lived
  13. token with limited permissions for the Keycloak Admin REST API. A private
  14. gateway restricts which API requests can reach Keycloak. The demo's only
  15. write, changing the language preference of a disabled test account, also
  16. requires a separate, single-use approval.
  17. [![Delegated user lookup in seven steps. Keycloak issues the user-read grant, MCP checks it with Cedar, SPIRE identifies MCP, and Keycloak exchanges the token. The private gateway forwards the read to the Admin REST API, and MCP returns the permitted user fields.](docs/assets/delegated-user-lookup.svg)](docs/MCP-DELEGATION.md)
  18. [Interactive guide](https://github.com/gaelnite/keycloak-mcp-security-demo/blob/main/docs/mcp-auth-evolution.html) · Open the HTML locally to trace an allowed read, an approved write, and a missing-scope denial.
  19. ## Architecture
  20. 1. **Desktop grant.** A pre-registered Codex client signs in with authorization
  21. code and S256 PKCE. OAuth protected-resource metadata identifies the issuer.
  22. The authorization request identifies the intended MCP resource. Keycloak
  23. issues scopes from the intersection of the user's entitlement and selection.
  24. [MCP OAuth](docs/MCP-OAUTH.md) · [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html#section-5.1) · [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html#section-2)
  25. 2. **Tool decision.** MCP verifies the current access token and checks the issued
  26. scope and user entitlement. Cedar evaluates the verified principal, tool,
  27. and realm. The write also requires a fresh operator-signed approval.
  28. Cedar lets the MCP server answer a question before it requests an Admin token:
  29. may this user invoke this tool in this realm under the grant they selected?
  30. [Why Cedar for tool authorization?](docs/decisions/0001-cedar-policy.md) ·
  31. [Cedar authorization](docs/AUTHZ.md) · [Threat model and tests](docs/THREAT-MODEL.md)
  32. 3. **Workload and exchange.** SPIRE supplies a JWT-SVID for the selected
  33. capability's exchange client. Keycloak exchanges the human grant for a
  34. distinct, short-lived Admin token. MCP validates the subject, requester,
  35. audience, scopes, lifetime, and role ceiling before dispatch.
  36. [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html#section-2.1) · [Keycloak 26.8.2 evidence](docs/evidence/keycloak-26.8.2.md)
  37. 4. **Admin operation.** A private gateway constrains the method, path, and query.
  38. Keycloak enforces backend permissions. MCP projects read results and
  39. constructs the only allowed write, a locale change for a disabled fixture
  40. account. [Delegated credential and route boundaries](docs/MCP-DELEGATION.md#credential-and-route-boundaries)
  41. The architecture decisions explain why the demo uses Cedar, SPIRE, one requester
  42. per capability, single-use approvals, and a private Admin gateway.
  43. [Architecture decisions](docs/decisions/README.md) · [Verification coverage](docs/evidence/acceptance.md)
  44. ## Limits and roadmap
  45. The demo uses a single trusted Docker host, a synthetic realm, and Keycloak
  46. 26.8.2 with its preview SPIFFE provider. The exercised MCP protocol revision
  47. is `2025-11-25`. Deployment recovery, automatic trust rollover, central audit
  48. retention, and multi-host operation remain open.
  49. [Security model](docs/SECURITY.md) · [Operational roadmap](docs/SECURITY.md#operational-roadmap)
  50. ## Quickstart
  51. From the repository root, use Docker Compose v2 and a free loopback port.
  52. ```sh
  53. KC_MCP_DEMO_PORT=49448 docker compose -p keycloak-mcp-delegated \
  54. -f deploy/docker/compose.yaml \
  55. -f deploy/docker/compose.interactive.yaml \
  56. -f deploy/docker/compose.delegated.yaml \
  57. up --build -d --wait
  58. ```
  59. The installer generates fixture credentials. Export the demo CA, sign in as
  60. helpdesk, and select `keycloak.users.read` to try an allowed read at
  61. `https://localhost:49448/mcp`. Realm administrators can also select client
  62. reads and the fixture locale write. With no selected scopes, desktop discovery
  63. is empty. [Run the delegated demo](docs/MCP-DELEGATION.md) · [Desktop sign-in and scopes](docs/MCP-INTERACTIVE.md)
  64. ## Runbooks and reference
  65. | Task | Guide |
  66. | --- | --- |
  67. | Verify workload authentication with an inventory read | [Headless profile](docs/DOCKER.md) |
  68. | Try user grants with Admin dispatch disabled | [Interactive profile](docs/MCP-INTERACTIVE.md) |
  69. | Start, stop, back up, or inspect the fixture | [Operations](docs/OPERATIONS.md) |
  70. | Work on the server or run verification | [Server reference](docs/MCP-SERVER.md) · [Contributing](CONTRIBUTING.md) |
  71. | Review the protocol findings and implementation | [Evidence index](docs/evidence/README.md) |
  72. | Review the historical Podman and dynamic CIMD research | [Protected archive](https://github.com/gaelnite/keycloak-mcp-security-demo/tree/archive/legacy-podman-26.8.1) |
  73. | Report a vulnerability privately | [Security policy](SECURITY.md) |
  74. ## Credits and license
  75. The Cedar integration draws on the PEP/PDP pattern in
  76. [openclaw-cedar-policy-demo](https://github.com/windley/openclaw-cedar-policy-demo).
  77. [Third-party notices](NOTICE) · [Apache 2.0 license](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.