diff --git a/docs/en/enterprise/features/sso.mdx b/docs/en/enterprise/features/sso.mdx index 3384d3d79..b9aea50dd 100644 --- a/docs/en/enterprise/features/sso.mdx +++ b/docs/en/enterprise/features/sso.mdx @@ -10,13 +10,13 @@ CrewAI Platform supports enterprise Single Sign-On (SSO) across both **SaaS (AMP ### Supported Providers -| Provider | SaaS | Factory | Protocol | CLI Support | -|---|---|---|---|---| -| **WorkOS** | ✅ (default) | ✅ | OAuth 2.0 / OIDC | ✅ | -| **Microsoft Entra ID** (Azure AD) | ✅ (enterprise) | ✅ | OAuth 2.0 / SAML 2.0 | ✅ | -| **Okta** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ | -| **Auth0** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ | -| **Keycloak** | — | ✅ | OAuth 2.0 / OIDC | ✅ | +| Provider | SaaS | Factory | Protocol | +|---|---|---|---| +| **WorkOS** | ✅ (default) | ✅ | OAuth 2.0 / OIDC | +| **Microsoft Entra ID** (Azure AD) | ✅ (enterprise) | ✅ | OAuth 2.0 / SAML 2.0 | +| **Okta** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | +| **Auth0** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | +| **Keycloak** | — | ✅ | OAuth 2.0 / OIDC | ### Key Capabilities @@ -52,270 +52,21 @@ Enterprise SaaS customers can configure SSO with their own identity provider (En --- -## Factory SSO Setup +## Factory SSO -Factory (self-hosted) deployments require you to configure SSO by setting environment variables in your Helm `values.yaml` and registering an application in your identity provider. +Factory (self-hosted) deployments support SSO with the following identity providers: -### Microsoft Entra ID (Azure AD) +- **Microsoft Entra ID** (Azure AD) +- **Okta** +- **Keycloak** +- **Auth0** +- **WorkOS** - - - 1. Go to [portal.azure.com](https://portal.azure.com) → **Microsoft Entra ID** → **App registrations** → **New registration** - 2. Configure: - - **Name:** `CrewAI` (or your preferred name) - - **Supported account types:** Accounts in this organizational directory only - - **Redirect URI:** Select **Web**, enter `https:///auth/entra_id/callback` - 3. Click **Register** - +Each provider requires registering an application in your IdP and configuring the corresponding environment variables in your Helm `values.yaml`. - - From the app overview page, copy: - - **Application (client) ID** → `ENTRA_ID_CLIENT_ID` - - **Directory (tenant) ID** → `ENTRA_ID_TENANT_ID` - - - - 1. Navigate to **Certificates & Secrets** → **New client secret** - 2. Add a description and select expiration period - 3. Copy the secret value immediately (it won't be shown again) → `ENTRA_ID_CLIENT_SECRET` - - - - 1. Go to **Enterprise applications** → select your app - 2. Under **Security** → **Permissions**, click **Grant admin consent** - 3. Ensure **Microsoft Graph → User.Read** is granted - - - - Under **App registrations** → your app → **App roles**, create: - - | Display Name | Value | Allowed Member Types | - |---|---|---| - | Member | `member` | Users/Groups | - | Factory Admin | `factory-admin` | Users/Groups | - - - The `member` role grants login access. The `factory-admin` role grants admin panel access. Roles are included in the JWT automatically. - - - - - 1. Under **Properties**, set **Assignment required?** to **Yes** - 2. Under **Users and groups**, assign users/groups with the appropriate role - - - - ```yaml - envVars: - AUTH_PROVIDER: "entra_id" - - secrets: - ENTRA_ID_CLIENT_ID: "" - ENTRA_ID_CLIENT_SECRET: "" - ENTRA_ID_TENANT_ID: "" - ``` - - - - To allow `crewai login` via Device Authorization Grant: - - 1. Under **Authentication** → **Advanced settings**, enable **Allow public client flows** - 2. Under **Expose an API**, add an Application ID URI (e.g., `api://crewai-cli`) - 3. Add a scope (e.g., `read`) with **Admins and users** consent - 4. Under **Manifest**, set `accessTokenAcceptedVersion` to `2` - 5. Add environment variables: - - ```yaml - secrets: - ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID: "" - ENTRA_ID_CUSTOM_OPENID_SCOPE: "" - ``` - - - ---- - -### Okta - - - - 1. Open Okta Admin Console → **Applications** → **Create App Integration** - 2. Select **OIDC - OpenID Connect** → **Web Application** → **Next** - 3. Configure: - - **App integration name:** `CrewAI SSO` - - **Sign-in redirect URI:** `https:///auth/okta/callback` - - **Sign-out redirect URI:** `https://` - - **Assignments:** Choose who can access (everyone or specific groups) - 4. Click **Save** - - - - From the app details page: - - **Client ID** → `OKTA_CLIENT_ID` - - **Client Secret** → `OKTA_CLIENT_SECRET` - - **Okta URL** (top-right corner, under your username) → `OKTA_SITE` - - - - 1. Navigate to **Security** → **API** - 2. Select your authorization server (default: `default`) - 3. Under **Access Policies**, add a policy and rule: - - In the rule, under **Scopes requested**, select **The following scopes** → **OIDC default scopes** - 4. Note the **Name** and **Audience** of the authorization server - - - The authorization server name and audience must match `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` exactly. Mismatches cause `401 Unauthorized` or `Invalid token: Signature verification failed` errors. - - - - - ```yaml - envVars: - AUTH_PROVIDER: "okta" - - secrets: - OKTA_CLIENT_ID: "" - OKTA_CLIENT_SECRET: "" - OKTA_SITE: "https://your-domain.okta.com" - OKTA_AUTHORIZATION_SERVER: "default" - OKTA_AUDIENCE: "api://default" - ``` - - - - 1. Create a **new** app integration: **OIDC** → **Native Application** - 2. Enable **Device Authorization** and **Refresh Token** grant types - 3. Allow everyone in your organization to access - 4. Add environment variable: - - ```yaml - secrets: - OKTA_DEVICE_AUTHORIZATION_CLIENT_ID: "" - ``` - - - Device Authorization requires a **Native Application** — it cannot use the Web Application created for browser-based SSO. - - - - ---- - -### Keycloak - - - - 1. Open Keycloak Admin Console → navigate to your realm - 2. **Clients** → **Create client**: - - **Client type:** OpenID Connect - - **Client ID:** `crewai-factory` (suggested) - 3. Capability config: - - **Client authentication:** On - - **Standard flow:** Checked - 4. Login settings: - - **Root URL:** `https://` - - **Valid redirect URIs:** `https:///auth/keycloak/callback` - - **Valid post logout redirect URIs:** `https://` - 5. Click **Save** - - - - - **Client ID** → `KEYCLOAK_CLIENT_ID` - - Under **Credentials** tab: **Client secret** → `KEYCLOAK_CLIENT_SECRET` - - **Realm name** → `KEYCLOAK_REALM` - - **Keycloak server URL** → `KEYCLOAK_SITE` - - - - ```yaml - envVars: - AUTH_PROVIDER: "keycloak" - - secrets: - KEYCLOAK_CLIENT_ID: "" - KEYCLOAK_CLIENT_SECRET: "" - KEYCLOAK_SITE: "https://keycloak.yourdomain.com" - KEYCLOAK_REALM: "" - KEYCLOAK_AUDIENCE: "account" - # Only set if using a custom base path (pre-v17 migrations): - # KEYCLOAK_BASE_URL: "/auth" - ``` - - - Keycloak includes `account` as the default audience in access tokens. For most installations, `KEYCLOAK_AUDIENCE=account` works without additional configuration. See [Keycloak audience documentation](https://www.keycloak.org/docs/latest/authorization_services/index.html) if you need a custom audience. - - - - - 1. Create a **second** client: - - **Client type:** OpenID Connect - - **Client ID:** `crewai-factory-cli` (suggested) - - **Client authentication:** Off (Device Authorization requires a public client) - - **Authentication flow:** Check **only** OAuth 2.0 Device Authorization Grant - 2. Add environment variable: - - ```yaml - secrets: - KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID: "" - ``` - - - ---- - -### WorkOS - - - - 1. Create an application in the [WorkOS Dashboard](https://dashboard.workos.com) - 2. Configure the redirect URI: `https:///auth/workos/callback` - 3. Note the **Client ID** and **AuthKit domain** - 4. Set up organizations in the WorkOS dashboard - - - - ```yaml - envVars: - AUTH_PROVIDER: "workos" - - secrets: - WORKOS_CLIENT_ID: "" - WORKOS_AUTHKIT_DOMAIN: "" - ``` - - - ---- - -### Auth0 - - - - 1. In the [Auth0 Dashboard](https://manage.auth0.com), create a new **Regular Web Application** - 2. Configure: - - **Allowed Callback URLs:** `https:///auth/auth0/callback` - - **Allowed Logout URLs:** `https://` - 3. Note the **Domain**, **Client ID**, and **Client Secret** - - - - ```yaml - envVars: - AUTH_PROVIDER: "auth0" - - secrets: - AUTH0_CLIENT_ID: "" - AUTH0_CLIENT_SECRET: "" - AUTH0_DOMAIN: "" - ``` - - - - 1. Create a **Native** application in Auth0 for Device Authorization - 2. Enable the **Device Authorization** grant type under application settings - 3. Configure the CLI with the appropriate audience and client ID - - + + Detailed setup guides for each provider — including step-by-step IdP registration, environment variable reference, and CLI enablement — are available in your **Factory admin documentation** (shipped with your Factory installation). + --- @@ -388,161 +139,54 @@ crewai config list ## Role-Based Access Control (RBAC) -CrewAI Platform provides granular RBAC that integrates with your SSO provider. - -### Permission Model - -| Permission | Description | -|---|---| -| **Read** | View resources (dashboards, automations, logs) | -| **Write** | Create and modify resources | -| **Manage** | Full control including deletion and configuration | - -### Resources - -Permissions can be scoped to individual resources: - -- **Usage Dashboard** — Platform usage metrics and analytics -- **Automations Dashboard** — Crew and flow management -- **Environment Variables** — Secret and configuration management -- **Individual Automations** — Per-automation access control - -### Roles +CrewAI Platform provides granular RBAC that integrates with your SSO provider. Permissions can be scoped to individual resources including dashboards, automations, and environment variables. - **Predefined roles** come out of the box with standard permission sets -- **Custom roles** can be created with any combination of permissions +- **Custom roles** can be created with any combination of Read, Write, and Manage permissions - **Per-resource assignment** — limit specific automations to individual users or roles -### Factory Admin Access - -For Factory deployments using Entra ID, admin access is controlled via App Roles: - -- Assign the `factory-admin` role to users who need admin panel access -- Assign the `member` role for standard platform access -- Roles are communicated via JWT claims — no additional configuration needed after IdP setup +For detailed RBAC configuration, see the [RBAC documentation](/enterprise/features/rbac). --- ## Troubleshooting -### Invalid Redirect URI - -**Symptom:** Authentication fails with a redirect URI mismatch error. - -**Fix:** Ensure the redirect URI in your IdP exactly matches the expected callback URL: - -| Provider | Callback URL | -|---|---| -| Entra ID | `https:///auth/entra_id/callback` | -| Okta | `https:///auth/okta/callback` | -| Keycloak | `https:///auth/keycloak/callback` | -| WorkOS | `https:///auth/workos/callback` | -| Auth0 | `https:///auth/auth0/callback` | - ### CLI Login Fails (Device Authorization) **Symptom:** `crewai login` returns an error or times out. **Fix:** - Verify that Device Authorization Grant is enabled in your IdP -- For Okta: ensure you have a **Native Application** (not Web) with Device Authorization grant -- For Entra ID: ensure **Allow public client flows** is enabled -- For Keycloak: ensure the CLI client has **Client authentication: Off** and only Device Authorization Grant enabled -- Check that `*_DEVICE_AUTHORIZATION_CLIENT_ID` environment variable is set on the server +- Check that your CLI is configured correctly: `crewai config list` +- Ensure your CrewAI CLI version meets the minimum requirements for your provider ### Token Validation Errors **Symptom:** `Invalid token: Signature verification failed` or `401 Unauthorized` after login. **Fix:** -- **Okta:** Verify `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` match the authorization server's Name and Audience exactly -- **Entra ID:** Ensure `accessTokenAcceptedVersion` is set to `2` in the app manifest -- **Keycloak:** Verify `KEYCLOAK_AUDIENCE` matches the audience in your access tokens (default: `account`) - -### Admin Consent Not Granted (Entra ID) - -**Symptom:** Users can't log in, see "needs admin approval" message. - -**Fix:** Go to **Enterprise applications** → your app → **Permissions** → **Grant admin consent**. Ensure `User.Read` is granted for Microsoft Graph. +- Verify that your OAuth2 audience and authorization server settings match your IdP configuration exactly +- For SaaS: contact your CrewAI account team if errors persist after verifying CLI settings ### 403 Forbidden After Login **Symptom:** User authenticates successfully but gets 403 errors. **Fix:** -- Check that the user is assigned to the application in your IdP -- For Entra ID with **Assignment required = Yes**: ensure the user has a role assignment (Member or Factory Admin) -- For Okta: verify the user or their group is assigned under the app's **Assignments** tab +- Check that the user is assigned to the CrewAI application in your IdP +- Verify the user has the appropriate role assignment in your IdP -### CLI Can't Reach Factory Instance +### CLI Can't Reach CrewAI Instance **Symptom:** `crewai enterprise configure` fails to connect. **Fix:** -- Verify the Factory URL is reachable from your machine +- Verify the instance URL is reachable from your machine - Check that `enterprise_base_url` is set correctly: `crewai config list` - Ensure TLS certificates are valid and trusted --- -## Environment Variables Reference - -### Common - -| Variable | Description | -|---|---| -| `AUTH_PROVIDER` | Authentication provider: `entra_id`, `okta`, `workos`, `auth0`, `keycloak`, `local` | - -### Microsoft Entra ID - -| Variable | Required | Description | -|---|---|---| -| `ENTRA_ID_CLIENT_ID` | ✅ | Application (client) ID from Azure | -| `ENTRA_ID_CLIENT_SECRET` | ✅ | Client secret from Azure | -| `ENTRA_ID_TENANT_ID` | ✅ | Directory (tenant) ID from Azure | -| `ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Client ID for Device Authorization Grant | -| `ENTRA_ID_CUSTOM_OPENID_SCOPE` | CLI only | Custom scope from "Expose an API" (e.g., `api://crewai-cli/read`) | - -### Okta - -| Variable | Required | Description | -|---|---|---| -| `OKTA_CLIENT_ID` | ✅ | Okta application client ID | -| `OKTA_CLIENT_SECRET` | ✅ | Okta client secret | -| `OKTA_SITE` | ✅ | Okta organization URL (e.g., `https://your-domain.okta.com`) | -| `OKTA_AUTHORIZATION_SERVER` | ✅ | Authorization server name (e.g., `default`) | -| `OKTA_AUDIENCE` | ✅ | Authorization server audience (e.g., `api://default`) | -| `OKTA_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Native app client ID for Device Authorization | - -### WorkOS - -| Variable | Required | Description | -|---|---|---| -| `WORKOS_CLIENT_ID` | ✅ | WorkOS application client ID | -| `WORKOS_AUTHKIT_DOMAIN` | ✅ | AuthKit domain (e.g., `your-domain.authkit.com`) | - -### Auth0 - -| Variable | Required | Description | -|---|---|---| -| `AUTH0_CLIENT_ID` | ✅ | Auth0 application client ID | -| `AUTH0_CLIENT_SECRET` | ✅ | Auth0 client secret | -| `AUTH0_DOMAIN` | ✅ | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) | - -### Keycloak - -| Variable | Required | Description | -|---|---|---| -| `KEYCLOAK_CLIENT_ID` | ✅ | Keycloak client ID | -| `KEYCLOAK_CLIENT_SECRET` | ✅ | Keycloak client secret | -| `KEYCLOAK_SITE` | ✅ | Keycloak server URL | -| `KEYCLOAK_REALM` | ✅ | Keycloak realm name | -| `KEYCLOAK_AUDIENCE` | ✅ | Token audience (default: `account`) | -| `KEYCLOAK_BASE_URL` | Optional | Base URL path (e.g., `/auth` for pre-v17 migrations) | -| `KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Public client ID for Device Authorization | - ---- - ## Next Steps - [Installation Guide](/installation) — Get started with CrewAI