Skip to main content

How to Set Keycloak as Identity Provider

Table of Contents

Introduction​

This basic tutorial demonstrates the steps to create a REALM in Keycloak and use it as an identity and access management solution for AI DIAL users.

In AI DIAL, you can assign roles to Models, Applications, Addons, and Assistants to restrict the number of tokens that can be transmitted in a specific time frame. These roles and their limitations can be created in external systems and then assigned in AI DIAL's configuration.

Configuration Guidelines​

Configure Keycloak​

Note: Replace <chat_url> with the actual address of your AI DIAL Chat application.

There are two ways to configure Keycloak: via Admin Console or using a CLI tool.

Configuration in Keycloak Admin Console​

Follow these steps to configure Keycloak in Admin Console:

  1. Create a Client: Create an OpenID Connect client in Keycloak with the following settings:
    • Client type: OpenID Connect
    • Client ID: dial-chat
    • Client authentication: On
    • Root URL: <chat_url>
    • Valid redirect URIs: <chat_url>/*
    • Home URL: <chat_url>
    • Web origins: <chat_url>
  2. Collect configuration parameters: in this step, you will collect parameters that will be required for AI DIAL configuration.
    • In Clients/Client details/Settings, record the Client ID.
    • In Clients/Client details/Credentials, click on view Client secret and record it.
    • In Realm settings/General, record the Realm ID.
  3. Create Users: create necessary Users.
  4. (Optional) Create and Assign Roles: under the Clients/Client details/Roles, create necessary Client roles. After that assign roles to users.

Configuration in Keycloak Config CLI​

For setting up Keycloak, which is included in the AI DIAL Helm chart, you can use Keycloak Config CLI. We suggest using the following configuration, which can be passed to keycloak.keycloakConfigCli.configuration."realm\.yaml" in the DIAL Helm chart.

Note: Replace <fields> before applying this configuration.

realm: "dial"
displayName: "dial"
enabled: true
accessTokenLifespan: 86400
ssoSessionIdleTimeout: 86400
ssoSessionMaxLifespan: 86400
roles:
  client:
    dial-chat:
      - name: admin
        description: "AI DIAL chat admin role"
        composite: false
        clientRole: true
groups:
  - name: DIAL
    subGroups:
      - name: "admin"
        clientRoles:
          dial-chat: ["admin"]
clientScopes:
  - name: dial
    description: "dial scope"
    protocol: openid-connect
    attributes:
      include.in.token.scope: "true"
      display.on.consent.screen: "true"
      consent.screen.text: ""
    protocolMappers:
      - name: "Audience for Dial"
        protocol: openid-connect
        protocolMapper: oidc-audience-mapper
        consentRequired: false
        config:
          included.client.audience: dial-chat
          id.token.claim: false
          access.token.claim: true
clients:
  - clientId: dial-chat
    name: dial-chat
    description: AI DIAL chat client
    rootUrl: https://<chat_url>
    adminUrl: https://<chat_url>
    baseUrl: https://<chat_url>
    surrogateAuthRequired: false
    enabled: true
    clientAuthenticatorType: client-secret
    secret: <keycloak_client_secret>
    redirectUris:
      - https://<chat_url>/*
    webOrigins:
      - https://<chat_url>
    notBefore: 0
    bearerOnly: false
    consentRequired: false
    standardFlowEnabled: true
    implicitFlowEnabled: false
    directAccessGrantsEnabled: true
    serviceAccountsEnabled: false
    publicClient: false
    frontchannelLogout: true
    protocol: openid-connect
    attributes:
      oidc.ciba.grant.enabled: "false"
      client.secret.creation.time: "1691398764"
      backchannel.logout.session.required: "true"
      display.on.consent.screen: "false"
      oauth2.device.authorization.grant.enabled: "false"
      backchannel.logout.revoke.offline.tokens: "false"
    authenticationFlowBindingOverrides: {}
    fullScopeAllowed: true
    nodeReRegistrationTimeout: -1
    defaultClientScopes:
      - web-origins
      - acr
      - profile
      - roles
      - email
      - dial
    optionalClientScopes:
      - address
      - phone
      - offline_access
      - microprofile-jwt

Configure AI DIAL​

By configuring both AI DIAL Chat and AI DIAL Core with the necessary environment variables, you will enable them to work together seamlessly with Identity Provider for authentication and authorization purposes.

To configure AI DIAL Chat and AI DIAL Core to work with Keycloak, follow these steps:

AI DIAL Chat Settings​

Add the following environment variables to AI DIAL Chat configuration. Refer to AI DIAL Chat to learn more.

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

AUTH_KEYCLOAK_HOST example: https://keycloak.example.com/realms/dial

AI DIAL Core Settings​

Add the following parameters to AI DIAL Core static settings. Refer to AI DIAL Core for more details.

aidial.identityProviders.keycloak.jwksUrl: "<keycloak_jwks_uri>"
aidial.identityProviders.keycloak.rolePath: "<keycloak_role_path>"
aidial.identityProviders.keycloak.issuerPattern: <issuerPattern>
aidial.identityProviders.keycloak.loggingKey: "sub" 
aidial.identityProviders.keycloak.loggingSalt: "loggingSalt" # strong generated string

Examples:

  • keycloak_jwks_uri example: https://<keycloak_host>/realms/<keycloak_realm_id>/protocol/openid-connect/certs
  • keycloak_role_path example: resource_access.dial-chat.roles
  • issuerPattern example: '^https:\/\/keycloak\.example\.com.+$'

Assignment of Roles​

Once all the above steps are completed, including the ones marked as Optional, you can assign roles to Models, Applications, Addons, and Assistants.

In AI DIAL Core:

  • Static settings: as value for aidial.identityProviders.keycloak.rolePath provide a role path from Keycloak.
  • Dynamic settings: for userRoles provide a specific role name(s).

In this example, "keycloak-role-name" role from the <keycloak_role_path> is configured for chat-gpt-35-turbo model:

# Dynamic settings of AI DIAL Core
"models": {
    "chat-gpt-35-turbo": {
      "type": "chat",
      "endpoint" : "http://localhost:7001/v1/openai/deployments/gpt-35-turbo/chat/completions",
      "upstreams": [
        {"endpoint": "http://localhost:7001", "key": "modelKey1"}
      ],
      "userRoles": ["keycloak-role-name"]
    }
}