Copy page

Identity providers

Configuring Keycloak

The MCP Gateway can use Keycloak as the identity provider behind its downstream OAuth flow. The mcp-keycloak-oauth-inbound policy is a Keycloak-friendly wrapper around the generic mcp-oauth-inbound policy: provide your Keycloak base URL, a realm name, a client ID, and a client secret, and the policy derives the realm-issuer URL, JWKS URL, and authorize and token URLs from Keycloak's standard OpenID Connect endpoint layout.

This guide walks through the Keycloak admin console setup, then wires the policy into a gateway project. Read the authentication overview first for the two-layer OAuth model.

Set up Keycloak

The MCP Gateway acts as an OAuth 2.1 authorization server in front of Keycloak. Keycloak handles browser login; the gateway issues its own access tokens that bind to MCP routes.

Create a client in the realm

1. In the Keycloak admin console, switch to the realm you want the gateway to use.
2. Open Clients and click Create client.
3. Give the client a Client ID (for example, zuplo-mcp-gateway) and click Next.
4. Enable Client authentication (so the client requires a secret) and leave Standard flow (authorization code) enabled. Disable Service accounts roles and Direct access grants — the gateway only needs the browser code flow.
5. Click Next.
6. Set Valid redirect URIs to https://<gateway-host>/oauth/callback. Add http://localhost:9000/oauth/callback for local development.
7. Set Web origins to https://<gateway-host> (and http://localhost:9000 for local dev).
8. Click Save.

Note the client credentials

Open the client's Credentials tab. Copy the Client secret. The Client ID is the value you set above.

Wire the policy into the gateway

Add the policy to config/policies.json:

Code
{
  "name": "keycloak-managed-oauth",
  "policyType": "mcp-keycloak-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime/mcp-gateway)",
    "export": "McpKeycloakOAuthInboundPolicy",
    "options": {
      "keycloakBaseUrl": "$env(KEYCLOAK_BASE_URL)",
      "realm": "$env(KEYCLOAK_REALM)",
      "clientId": "$env(KEYCLOAK_CLIENT_ID)",
      "clientSecret": "$env(KEYCLOAK_CLIENT_SECRET)"
    }
  }
}

Attach the policy to each MCP route in config/routes.oas.json and register the gateway plugin in modules/zuplo.runtime.ts (see Configuring Auth0 for the route and plugin patterns — they're identical across all wrappers).

What the wrapper derives

Given keycloakBaseUrl: "https://sso.example.com" and realm: "customer-portal":

Generic field	Derived value
oidc.issuer	https://sso.example.com/realms/customer-portal
oidc.jwksUrl	https://sso.example.com/realms/customer-portal/protocol/openid-connect/certs
browserLogin.url	https://sso.example.com/realms/customer-portal/protocol/openid-connect/auth
browserLogin.tokenUrl	https://sso.example.com/realms/customer-portal/protocol/openid-connect/token

Test the configuration

The fastest sanity check is to connect an MCP client:

1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
2. Add a remote MCP server pointing at one of your /mcp/{slug} routes.
3. The client should redirect you to the Keycloak sign-in page. After login, the gateway's consent screen renders. Approve it.
4. The client receives an access token and can call tools/list.

If something fails partway through, walk the flow manually using the manual OAuth testing guide — it exercises every endpoint with curl so you can see the raw responses.

Common issues

• keycloakBaseUrl rejected at boot. The value includes /realms/.... Strip the realm path; pass the realm name on the realm option instead.
• Invalid redirect_uri from Keycloak. The callback URL on the client doesn't match https://<gateway-host>/oauth/callback.
• Invalid client credentials. The client isn't a confidential client (Client authentication off), or the secret value doesn't match. Re-copy the secret from the Credentials tab.

Related

• Authentication overview
• Configuring a generic OIDC provider
• Per-user OAuth to upstream MCP servers