Skip to main content

​
Overview

This guide walks you through configuring Keycloak as your Single Sign-On (SSO) provider for CrewAI Factory installations.

​
Prerequisites

  • A running Keycloak instance (guide based on version 26.4.2)
  • Administrative access to your Keycloak realm
  • Your CrewAI Factory installation URL

​
Initial Setup

Open your Keycloak admin console. Navigate to your realm (or create a new one if needed). Keycloak Admin Console

​
Creating a Client to log in into the web application (AMP)

In the left sidebar, click “Clients”, then click “Create client”. Keycloak Clients List Configure the client with the following settings:
  • Client type: OpenID Connect
  • Client ID: Choose a client ID (suggested: crewai-factory)
  • (Optional): Fill name and description fields.
Click “Next” to continue. Keycloak Client Creation Step 1 On the capability configuration screen:
  • Client authentication: On
  • Authorization: Off (unless you need fine-grained authorization)
  • Authentication flow: Check “Standard flow” (and “Service accounts roles”)
Click “Next” to continue. Keycloak Client Creation Step 2 On the login settings screen:
  • Root URL: Your CrewAI Factory URL (e.g., https://myfactoryurl.crewai.com)
  • Home URL: Usually the same as the root URL.
  • Valid redirect URIs: Add your CrewAI Factory URL with the callback path: https://myfactoryurl.crewai.com/auth/keycloak/callback
  • Valid post logout redirect URIs: Your CrewAI Factory URL (e.g., https://myfactoryurl.crewai.com)
  • Web origins: Your CrewAI Factory URL or + to allow all redirect URIs
Click “Save” to create the client. Keycloak Client Creation Step 3

​
Collecting Credentials

With the client created, collect the necessary credentials for the CrewAI Factory environment variables.

​
Client ID and Secret

In the client details page:
  • Client ID: Copy the Client ID you specified during creation. This value should be assigned to the KEYCLOAK_CLIENT_ID environment variable.
    • In this tutorial, this value is factory_keycloak_sso_tutorial
  • Navigate to the “Credentials” tab and copy the Client secret. This value should be assigned to the KEYCLOAK_CLIENT_SECRET environment variable.
    • In this tutorial, this value is 55oahEeruNQGWxqzleWy02cRfW3wLf2c
Keycloak Credentials Tab

​
Realm, Site URL and Base URL

  • Realm name: Note your realm name. This should be assigned to the KEYCLOAK_REALM environment variable.
    • In this tutorial, this value is crewai
  • Site URL: Your Keycloak server URL (e.g., https://keycloak.yourdomain.com). This should be assigned to the KEYCLOAK_SITE environment variable.
    • In this tutorial, this value is http://localhost:8080
  • Base URL: Your Keycloak default context path (e.g. ‘/auth’ or a blank string). This should be assigned to the KEYCLOAK_BASE_URL environment variable.
    • In this tutorial, this value will be not set, but you can obtain your base URL as follows:
    • It is the value passed with --http-relative-path when you start up your keycloak instance
    • After keycloak 17, this is not set, so if you are using Keycloak 17+ without --http-relative-path, you do not need to set the environment variable
    • If you migrated from 17 to a newer version and you kept the old default /auth for example, you should pass /auth to keep the backwards compatibility.
TODO: Add screenshot showing realm name location Keycloak Realm Name Location

​
Managing Access

​
User Assignment

To control which users can access CrewAI Factory, you can, on step 2 of client creation, activate the “authorization” option. This will unlock a new “Authorization” tab on Client management where you can configure specific access policies for individual users or groups. Keycloak Client Creation with Authorization option turned on Keycloak Client Authorization tab
The exact access control configuration depends on your organization’s requirements and existing Keycloak setup.

​
Environment Variables

With the credentials collected, configure the following environment variables when deploying your CrewAI Factory installation: 
AUTH_PROVIDER=keycloak
KEYCLOAK_CLIENT_ID="your-client-id"
KEYCLOAK_CLIENT_SECRET="your-client-secret"
KEYCLOAK_SITE="https://keycloak.yourdomain.com"
KEYCLOAK_BASE_URL="your-base-url"
KEYCLOAK_REALM="your-realm-name"
KEYCLOAK_AUDIENCE="account"

​
Configuring the Audience

By default, Keycloak includes account as the audience (aud claim) in access tokens. This is standard Keycloak behavior, and is supported by CrewAI Factory AMP and CLI. For most installations, you can leave KEYCLOAK_AUDIENCE=account and no additional configuration is required. However, if you already use a custom audience or want to configure one, make sure to update KEYCLOAK_AUDIENCE accordingly. Below you will find a few resources that explain more about the default value of audience and guides on how to customize it.

​
Why is the default audience “account”?

Keycloak automatically adds account to the aud claim because it represents the built-in account management service. This behavior is documented in various community discussions:

​
Using a Custom Audience

If your organization requires a custom audience value, you will need to configure it in Keycloak using client scopes and audience mappers. Update the KEYCLOAK_AUDIENCE environment variable to match your custom audience value.
Configuring a custom audience requires advanced Keycloak configuration. Ensure your custom audience is properly set up before changing the KEYCLOAK_AUDIENCE environment variable, otherwise authentication will fail. Login on CrewAI CLI is particularly sensitive to misconfigured audience values.
For instructions on configuring custom audiences in Keycloak, refer to:

​
Configure the CLI to use Keycloak as your OAuth2 provider

To enable CLI authentication with Keycloak, you need to configure the Device Authorization Grant flow.

​
Enable Device Authorization Flow

Navigate to your Keycloak admin console, and refer to the steps below to create a new client that supports the device authorization flow:

​
Creating a Client for logging in to the CLI

In the left sidebar, click “Clients”, then click “Create client”. Keycloak Clients List Configure the client with the following settings:
  • Client type: OpenID Connect
  • Client ID: Choose a client ID (suggested: crewai-factory-cli)
  • (Optional): Fill name and description fields.
Click “Next” to continue. Keycloak CLI Client Creation Step 1 On the capability configuration screen:
  • Client authentication: Off
    • (Device authorization grant requires the client to be public)
  • Authorization: Off
  • Authentication flow: Check ONLY “OAuth 2.0 Device Authorization Grant”
Click “Next” to continue. Keycloak CLI Client Creation Step 2 On the login settings screen:
  • Root URL: Your CrewAI Factory URL (e.g., https://myfactoryurl.crewai.com)
  • Home URL: Usually the same as the root URL.
Click “Save” to create the client. Keycloak CLI Client Creation Step 3

​
Additional Environment Variables

Add the following environment variable to your CrewAI Factory installation to enable CLI authentication: 
KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID="your-client-id"

​
CLI Configuration

Now you are ready to configure your enterprise CLI login. Make sure your crewai CLI is version 1.9.0 or higher. To configure the Keycloak provider, run the following command: 
crewai enterprise configure https://your-factory-url.app
All set! You’re now ready to authenticate on CLI using Keycloak: 
crewai login

​
Common Issues

  • Invalid redirect URI: Ensure the redirect URI in Keycloak exactly matches your Factory URL with /auth/keycloak/callback
  • Client authentication failed: Verify the client secret is correctly copied and the client authentication is enabled
  • User not authorized: Check that the user has the appropriate roles/group membership to access the application
  • Invalid Audience: Check that the audience being sent by keycloak is the same one set on KEYCLOAK_AUDIENCE environment variable