Keycloak and Dome

1. 01

   Register your realm as a verification provider

   The issuer is the realm URL. Keycloak releases before 17 serve it under /auth/realms instead.

   $ dome verification-providers create \
     --name corporate-keycloak \
     --method oidc \
     --oidc-url https://<host>/realms/<realm> \
     --oidc-expected-audience <client-id>

2. 02

   Map groups and roles into the token

   Add a group membership mapper named groups to the client, on the access token. Realm roles sit under realm_access, which Dome doesn't read, so add a realm role mapper with the claim name roles if rules need them.

3. 03

   Pass the user's token with each call

   The agent keeps its own Dome key and adds the person's Keycloak token as a header.

   from openai import OpenAI
    
   client = OpenAI(
       base_url=f"{GATEWAY_URL}/v1",
       api_key=DOME_AGENT_KEY,
       default_headers={"X-Dome-Act-As": user_keycloak_token},
   )

Commands and rules tested against a Dome workspace on October 1, 2026. For anything about Keycloak itself, see Keycloak's documentation.

forbid (principal, action == Dome::Action::"mcp:call", resource is Dome::MCPTool)
when {
  resource.connection_name == "github" &&
  resource.tool_name == "merge_pull_request"
}
unless {
  principal has act_as &&
  principal.act_as.groups.contains("/engineering/platform")
};