Skip to main content

Configure Keycloak

This guide connects DIAL to Keycloak so users authenticate against a Keycloak realm and DIAL authorizes them by client role. Keycloak is open source and self-hosted; it also ships inside the DIAL Helm chart, which makes it the default provider for local and on-premises deployments. For the shared workflow, see the SSO / IdP setup overview.

Prerequisites​

  • A running DIAL deployment and the URL of your DIAL Chat instance, referred to below as <chat_url>.
  • A reachable Keycloak instance with administrator access, or the DIAL Helm chart's bundled Keycloak.

Step 1: Configure the Keycloak realm​

You can configure the realm through the Admin Console or declaratively.

Admin Console:

  1. Create a realm, for example dial.
  2. Create an OpenID Connect client (for example, ai-dial-chat) with client authentication on, the Standard flow and Direct access grants enabled, and valid redirect URIs set to <chat_url>/*.
  3. Gather facts: the Keycloak host (<keycloak_host>), realm name (<keycloak_realm_id>), the jwks_uri from the realm's OpenID endpoint configuration, the Client ID, and the Client secret.
  4. Create users.
  5. (Optional, RBAC) Create client roles and groups, then map roles to groups and add users to those groups.

Declarative (Helm): the bundled Keycloak is provisioned from a realm definition rather than the console. Define the realm in realm-config.json and supply it through the Helm chart. See the realm-config.json reference for the schema and the Docker Compose authentication setup for a working local example.

Step 2: Configure DIAL Chat​

Set these environment variables on DIAL Chat. See DIAL Chat configuration — Keycloak for the full list.

AUTH_KEYCLOAK_HOST: "https://<keycloak_host>/realms/<keycloak_realm_id>"
AUTH_KEYCLOAK_CLIENT_ID: "<keycloak_client_id>"
AUTH_KEYCLOAK_SECRET: "<keycloak_client_secret>"

Step 3: Configure DIAL Core​

Add the provider to the identityProviders section of DIAL Core static settings (settings.json). <keycloak_host_regex> is <keycloak_host> with dots escaped (for example, keycloak\.example\.com). Generate a random loggingSalt, for example with pwgen -s 32 1.

{
  "identityProviders": {
    "keycloak": {
      "jwksUrl": "<keycloak_jwks_uri>",
      "issuerPattern": "^https:\\/\\/<keycloak_host_regex>.*$",
      "loggingKey": "sub",
      "loggingSalt": "<random_salt>",
      "rolePath": "resource_access.<keycloak_client_id>.roles"
    }
  }
}

rolePath reads the client roles Keycloak places under resource_access.<client>.roles. For every setting, see the Identity providers reference.

note

DIAL Core reads static settings at startup. Restart Core after editing settings.json. Each setting can also be supplied as an aidial.identityProviders.keycloak.* environment variable.

Step 4: Assign roles to resources​

In config.json (dynamic settings), add a Keycloak client role name to a deployment's userRoles array.

{
  "models": {
    "chat-gpt-35-turbo": {
      "userRoles": ["keycloak-client-role-name"]
    }
  }
}

Result​

Users log in through Keycloak, and DIAL Core authorizes their requests based on the client roles in their token.

Further reading​