Keycloak

Integrate agentgateway with Keycloak for identity management

Keycloak is an open-source identity and access management solution. agentgateway can validate JWTs issued by Keycloak.

Why use Keycloak with agentgateway?

Open source - Self-hosted identity management
Standards-based - OAuth2, OIDC, SAML support
Enterprise features - User federation, SSO, MFA
Fine-grained authorization - Role and attribute-based access

Configuration

Configure agentgateway to validate Keycloak JWTs:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: my-server
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]
      policies:
        mcpAuthentication:
          mode: strict
          issuer: https://keycloak.example.com/realms/myrealm
          audiences:
          - agentgateway
          jwks:
            url: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs

Docker Compose example

version: '3'
services:
  agentgateway:
    image: ghcr.io/agentgateway/agentgateway:latest
    ports:
      - "3000:3000"
    volumes:
      - ./config.yaml:/etc/agentgateway/config.yaml
    depends_on:
      - keycloak

  keycloak:
    image: quay.io/keycloak/keycloak:latest
    ports:
      - "8080:8080"
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    command: start-dev

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=keycloak
      - POSTGRES_USER=keycloak
      - POSTGRES_PASSWORD=keycloak

Keycloak setup

Create a realm (e.g., myrealm)
Create a client for agentgateway:
- Client ID: agentgateway
- Client Protocol: openid-connect
- Access Type: confidential or public
Create users and assign roles

Role-based authorization

Combine Keycloak roles with agentgateway authorization:

policies:
  mcpAuthentication:
    mode: strict
    issuer: https://keycloak.example.com/realms/myrealm
    audiences: [agentgateway]
    jwks:
      url: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs
  authorization:
    rules:
    # Check for admin role in token
    - '"admin" in jwt.realm_access.roles'

Learn more

Was this page helpful?