1# Keycloak Authentication
2 
3Setting up OAuth with Keycloak. Keycloak exposes full OAuth 2.1 + OIDC endpoints on every realm, including native [Dynamic Client Registration](https://www.keycloak.org/securing-apps/client-registration) (RFC 7591). MCP clients discover Keycloak via `.well-known` metadata, register themselves, complete a PKCE flow, and send the access token as a bearer on MCP requests — **the MCP server only verifies the JWT against Keycloak's JWKS**.
4 
5**Learn more:** [Keycloak Documentation](https://www.keycloak.org/documentation) · [Keycloak DCR](https://www.keycloak.org/securing-apps/client-registration) · [Standalone starter template](https://github.com/mcp-use/mcp-oauth-keycloak-template) · [Runnable example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/keycloak)
6 
7---
8 
9## Quick Start
10 
11```typescript
12import { MCPServer, oauthKeycloakProvider, object } from "mcp-use/server";
13 
14const server = new MCPServer({
15  name: "my-server",
16  version: "1.0.0",
17  oauth: oauthKeycloakProvider(),  // reads MCP_USE_OAUTH_KEYCLOAK_SERVER_URL + _REALM
18});
19 
20server.tool(
21  { name: "whoami", description: "Get authenticated user info" },
22  async (_args, ctx) =>
23    object({
24      userId: ctx.auth.user.userId,
25      username: ctx.auth.user.username,
26      email: ctx.auth.user.email,
27      roles: ctx.auth.user.roles,
28      permissions: ctx.auth.permissions,
29      scopes: ctx.auth.scopes,
30    })
31);
32 
33server.listen();
34```
35 
36With a `.env` file:
37 
38```bash
39MCP_USE_OAUTH_KEYCLOAK_SERVER_URL=http://localhost:8080
40MCP_USE_OAUTH_KEYCLOAK_REALM=demo
41```
42 
43---
44 
45## Setup
46 
47This guide assumes you already have a Keycloak instance running with admin access. If not, see [Keycloak's getting started guide](https://www.keycloak.org/guides#getting-started).
48 
49### 1. Enable Dynamic Client Registration
50 
51Keycloak exposes `/{realm}/clients-registrations/openid-connect` on every realm. Anonymous (no-token) registration is gated by **Client Registration Policies**:
52 
531. **Realm settings → Client registration → Anonymous Access Policies**
542. Open the **Trusted Hosts** policy
553. Add the hostnames MCP clients will register from (`localhost`, `127.0.0.1`) to **Trusted Hosts**
564. Make sure **Client URIs Must Match** is enabled so `redirect_uris` in the registration request are validated
57 
58> **Browser MCP clients** (like the Inspector) also need the **Allowed Registration Web Origins** policy (Keycloak 26.6+) listing every origin the client runs from. Without it, DCR requests fail with CORS `403 Invalid origin`.
59 
60For non-localhost redirect URIs, mint an **Initial Access Token** (Realm settings → Client registration → Initial access token) and have clients pass it on the DCR POST.
61 
62### 2. (Optional) Audience enforcement
63 
64Keycloak doesn't set `aud` to the resource server by default. To require it:
65 
661. Add an **Audience** protocol mapper to a client scope in Keycloak.
672. Set `MCP_USE_OAUTH_KEYCLOAK_AUDIENCE` to the matching value.
68 
69Without the mapper, tokens will be rejected if `audience` is configured.
70 
71---
72 
73## Environment Variables
74 
75| Variable | Required | Description |
76|----------|----------|-------------|
77| `MCP_USE_OAUTH_KEYCLOAK_SERVER_URL` | Yes | Base URL of your Keycloak server (no trailing slash, no `/realms` path) |
78| `MCP_USE_OAUTH_KEYCLOAK_REALM` | Yes | Realm name (e.g. `demo`) |
79| `MCP_USE_OAUTH_KEYCLOAK_AUDIENCE` | No | If set, enforced as the access token's `aud` claim. Requires an Audience protocol mapper. |
80 
81---
82 
83## Configuration Options
84 
85Zero-config (reads from env vars):
86 
87```typescript
88oauth: oauthKeycloakProvider()
89```
90 
91Explicit config:
92 
93```typescript
94oauth: oauthKeycloakProvider({
95  serverUrl: "https://keycloak.example.com",
96  realm: "demo",
97  audience: "https://my-mcp-server.example.com/mcp",  // optional
98  verifyJwt: process.env.NODE_ENV === "production",   // default: true
99  scopesSupported: ["openid", "profile", "email"],    // override advertised scopes
100})
101```
102 
103| Option | Type | Default | Description |
104|--------|------|---------|-------------|
105| `serverUrl` | `string` | env var | Base URL of your Keycloak server |
106| `realm` | `string` | env var | Realm name |
107| `audience` | `string?` | env var | Required `aud` claim — needs an Audience mapper in Keycloak |
108| `verifyJwt` | `boolean?` | `true` | Set `false` to skip JWT verification (**development only**) |
109| `scopesSupported` | `string[]?` | `["openid", "profile", "email", "offline_access", "roles"]` | Override advertised scopes |
110 
111---
112 
113## The Flow
114 
115```
116MCP Client ──(1) GET /.well-known/oauth-protected-resource   ─▶ MCP Server
117MCP Client ──(2) GET /.well-known/oauth-authorization-server ─▶ MCP Server ─▶ Keycloak
118MCP Client ──(3) POST /clients-registrations/openid-connect  ─▶ Keycloak      (DCR)
119MCP Client ──(4) GET  /protocol/openid-connect/auth          ─▶ Keycloak      (PKCE)
120MCP Client ──(5) POST /protocol/openid-connect/token         ─▶ Keycloak
121MCP Client ──(6) MCP request + Bearer <token>                ─▶ MCP Server    (verifies JWT via JWKS)
122```
123 
124Step 2 is a passthrough from the MCP server back to Keycloak's metadata — it's what tells the client where to register and where to send the user for login. Everything else goes directly to Keycloak.
125 
126---
127 
128## User Context
129 
130Keycloak puts realm roles in `realm_access.roles` and resource roles in `resource_access.{client}.roles`. The provider normalizes them onto `ctx.auth`:
131 
132| Field | Type | Source |
133|-------|------|--------|
134| `userId` | `string` | `sub` claim |
135| `email` | `string?` | `email` claim |
136| `name` | `string?` | `name` claim |
137| `username` | `string?` | `preferred_username` claim |
138| `roles` | `string[]?` | `realm_access.roles` — **realm roles only** |
139| `permissions` | `string[]?` | `resource_access.{client}.roles` — as `"client:role"` strings |
140| `scopes` | `string[]?` | Parsed from `scope` claim |
141 
142### Role-Based Access Control
143 
144```typescript
145server.tool(
146  { name: "admin-action", description: "Admin-only action" },
147  async (_args, ctx) => {
148    if (!ctx.auth.user.roles?.includes("admin")) {
149      return error("Forbidden: admin role required");
150    }
151 
152    // ... admin logic
153    return text("Done");
154  }
155);
156```
157 
158For per-client roles, check `ctx.auth.permissions` (formatted as `client:role`).
159 
160---
161 
162## Making Keycloak API Calls
163 
164Call Keycloak's userinfo endpoint with the raw access token:
165 
166```typescript
167server.tool(
168  {
169    name: "get-keycloak-userinfo",
170    description: "Fetch the full userinfo document from Keycloak",
171  },
172  async (_args, ctx) => {
173    const serverUrl = process.env.MCP_USE_OAUTH_KEYCLOAK_SERVER_URL!;
174    const realm = process.env.MCP_USE_OAUTH_KEYCLOAK_REALM!;
175 
176    const res = await fetch(
177      `${serverUrl}/realms/${realm}/protocol/openid-connect/userinfo`,
178      { headers: { Authorization: `Bearer ${ctx.auth.accessToken}` } }
179    );
180 
181    return object(await res.json());
182  }
183);
184```
185 
186---
187 
188## Example `.env`
189 
190```bash
191# Required: base URL of your Keycloak server — no trailing slash, no /realms path
192MCP_USE_OAUTH_KEYCLOAK_SERVER_URL=http://localhost:8080
193 
194# Required: realm name
195MCP_USE_OAUTH_KEYCLOAK_REALM=demo
196 
197# Optional: if set, the provider enforces that the token's `aud` claim equals
198# this value. Requires an Audience protocol mapper on the client scope.
199# MCP_USE_OAUTH_KEYCLOAK_AUDIENCE=http://localhost:3000
200```
201 
202---
203 
204## Production Notes
205 
206- **Audience enforcement.** Keycloak doesn't set `aud` to the resource server by default. To require it, add an *Audience* protocol mapper to the client scope and set `MCP_USE_OAUTH_KEYCLOAK_AUDIENCE`.
207- **Anonymous DCR.** Fine for local dev, risky in production. Disable anonymous access and issue Initial Access Tokens that clients pass on the DCR request.
208- **Transport.** Always serve Keycloak and the MCP server over HTTPS outside of local dev.
209- **Scope of realm roles.** `ctx.auth.user.roles` only contains realm roles. Use `ctx.auth.permissions` (formatted as `client:role`) for per-client roles.
210 
211---
212 
213## Next Steps
214 
215- **Auth overview** → [overview.md](overview.md)
216- **Custom providers + OAuth proxy reference** → [custom.md](custom.md)
217- **WorkOS setup** → [workos.md](workos.md)
218- **Build tools** → [../server/tools.md](../server/tools.md)
219