Keycloak Setup
Relevant source files
The following files were used as context for generating this wiki page:
Keycloak provides the OpenID Connect (OIDC) infrastructure for authenticating users within the Infrahub MCP server. This setup enables production-ready authentication, allowing the server to validate Identity Provider (IdP) tokens and enforce scope-based access controls for infrastructure operations.
The setup is primarily driven by a provisioning script that configures a dedicated realm, client scopes, and test users to support end-to-end (e2e) authentication testing. This ensures that AI agents operate under specific user identities, preserving the Infrahub permission model and audit trail.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:52-57, development/keycloak/setup-keycloak.sh:1-5
Provisioning Architecture
The Keycloak configuration is managed as an idempotent process using the setup-keycloak.sh script. It interacts with the Keycloak Admin API to establish a secure environment for MCP operations.
Component Overview
| Component | Description |
|---|---|
| Realm | A dedicated infrahub realm for isolating MCP-related authentication. |
| Client | The infrahub-mcp-client configured for public access and direct access grants. |
| Client Scopes | Specific scopes (infrahub:read, infrahub:write) used to control operation permissions. |
| Protocol Mappers | An audience mapper ensuring tokens include the infrahub-mcp audience claim. |
Sources: development/keycloak/setup-keycloak.sh:35-95
Provisioning Flow
The following diagram illustrates the sequence of operations performed to initialize the Keycloak environment:
Authentication Scopes
Permissions are managed through OIDC client scopes. The server distinguishes between read-only and write operations based on these scopes.
- infrahub:read: Required for querying and listing infrastructure data.
- infrahub:write: Required for creating, modifying, or deleting infrastructure nodes.
The setup-keycloak.sh script assigns infrahub:read as a default client scope, while infrahub:write is treated as an optional scope that must be explicitly requested during the token exchange.
Sources: development/keycloak/setup-keycloak.sh:44-54, development/keycloak/setup-keycloak.sh:131-144
User and Credential Configuration
The setup includes pre-defined users for testing different authorization levels. These users are mapped to specific Infrahub API tokens via environment variables for testing purposes.
Test Users
| Username | Purpose | Scopes Requested |
|---|---|---|
reader-user | Validates read-only access. | openid (includes infrahub:read) |
writer-user | Validates full write access. | openid infrahub:read infrahub:write |
Sources: development/keycloak/setup-keycloak.sh:116-117, development/keycloak/setup-keycloak.sh:163-164
Identity Mapping
Identity is extracted from OIDC JWT claims. In production, this identity is used in branch naming patterns (e.g., mcp/{user}-{date}) to ensure isolated and traceable changes.
Integration with MCP Server
The MCP server configuration must align with the Keycloak setup to enable OIDC authentication. The ServerConfig requires the following environment variables to be set when auth_mode=oidc is used:
# Example OIDC Configuration derived from setup-keycloak.sh
INFRAHUB_MCP_AUTH_MODE=oidc
INFRAHUB_MCP_OIDC_ISSUER_URL=http://localhost:8080/realms/infrahub
INFRAHUB_MCP_OIDC_CLIENT_ID=infrahub-mcp-client
The server validates OIDC configuration as a complete set during startup. If partial configuration is provided, the server fails to start to prevent insecure operation.
Sources: dev/constitution.md:118-125, specs/archive/20260421-144953-production-ready-mcp-server/tasks.md:118-124
Verification Procedures
The setup-keycloak.sh script performs two primary verification checks to ensure the environment is ready:
- OIDC Discovery: Confirms the
/.well-known/openid-configurationendpoint returns an HTTP 200 status. - Token Acquisition: Validates that both
reader-userandwriter-usercan successfully obtain access tokens with their respective scopes.
Sources: development/keycloak/setup-keycloak.sh:147-164
Summary
Keycloak setup is a critical prerequisite for production deployments of the Infrahub MCP server. By provisioning a standardized realm, client, and scope model, it enables secure, multi-user access to infrastructure. The automated provisioning script ensures that developer and test environments are consistent with these production requirements, particularly regarding OIDC identity extraction and scope-based write protection.