单点登录（SSO）

概览

CrewAI Platform 支持跨 SaaS（AMP） 和 Factory（自托管） 部署的企业单点登录（SSO）。SSO 让你的团队可以使用组织现有的身份提供商进行认证，从而强制执行集中式访问控制、MFA 策略和用户生命周期管理。

支持的 Provider

Provider	SaaS	Factory	Protocol	CLI 支持
WorkOS	✅（默认）	✅	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	✅

主要能力

SAML 2.0 和 OAuth 2.0 / OIDC 协议支持
用于 CLI 认证的 Device Authorization Grant 流程
带自定义角色和按资源权限的 Role-Based Access Control（RBAC）
由你的身份提供商负责的 MFA enforcement
通过 IdP assignment（users/groups）进行 用户 provisioning

SaaS SSO

默认认证

CrewAI 的托管 SaaS 平台（AMP）默认使用 WorkOS 作为认证 provider。当你在 app.crewai.com 注册时，认证会通过 login.crewai.com 处理 - 不需要额外的 SSO 配置。

企业自定义 SSO

Enterprise SaaS customers 可以使用自己的身份提供商（Entra ID、Okta、Auth0）来配置 SSO。请联系你的 CrewAI account team，为你的组织启用自定义 SSO。配置完成后：

你的团队成员通过组织的 IdP 进行认证
访问控制和 MFA 策略由你的 IdP 执行
CrewAI CLI 会通过 crewai enterprise configure 自动检测你的 SSO 配置

CLI 默认值（SaaS）

Setting	默认值
`enterprise_base_url`	`https://app.crewai.com`
`oauth2_provider`	`workos`
`oauth2_domain`	`login.crewai.com`

Factory SSO 设置

Factory（自托管）部署需要你在 Helm 的 values.yaml 中设置环境变量，并在身份提供商中注册一个 application。

Microsoft Entra ID（Azure AD）

注册一个 Application
1. 进入 portal.azure.com → Microsoft Entra ID → App registrations → New registration
2. 配置：
  - Name: CrewAI（或你偏好的名称）
  - Supported account types: Accounts in this organizational directory only
  - Redirect URI: 选择 Web，输入 https://<your-domain>/auth/entra_id/callback
3. 点击 Register
收集凭据

从 app overview 页面复制：
- Application (client) ID → ENTRA_ID_CLIENT_ID
- Directory (tenant) ID → ENTRA_ID_TENANT_ID
创建 Client Secret
1. 进入 Certificates & Secrets → New client secret
2. 添加 description 并选择过期时间
3. 立刻复制 secret value（之后不会再次显示）→ ENTRA_ID_CLIENT_SECRET
授予 Admin Consent
1. 进入 Enterprise applications → 选择你的 app
2. 在 Security → Permissions 下，点击 Grant admin consent
3. 确认 Microsoft Graph → User.Read 已获授权
配置 App Roles（推荐）

在 App registrations → 你的 app → App roles 中创建：

Display Name Value Allowed Member Types
Member member Users/Groups
Factory Admin factory-admin Users/Groups

Note

member role 授予登录权限。factory-admin role 授予管理面板访问权限。roles 会自动包含在 JWT 中。
分配用户
1. 在 Properties 下，将 Assignment required? 设置为 Yes
2. 在 Users and groups 下，为相应用户/组分配 role

Display Name	Value	Allowed Member Types
Member	`member`	Users/Groups
Factory Admin	`factory-admin`	Users/Groups

设置环境变量

envVars:
  AUTH_PROVIDER: "entra_id"

secrets:
  ENTRA_ID_CLIENT_ID: "<Application (client) ID>"
  ENTRA_ID_CLIENT_SECRET: "<Client Secret>"
  ENTRA_ID_TENANT_ID: "<Directory (tenant) ID>"

启用 CLI 支持（可选）

若要允许通过 Device Authorization Grant 使用 crewai login：
1. 在 Authentication → Advanced settings 中，启用 Allow public client flows
2. 在 Expose an API 中，添加 Application ID URI（例如 api://crewai-cli）
3. 添加一个 scope（例如 read），并将 consent 设为 Admins and users
4. 在 Manifest 中，将 accessTokenAcceptedVersion 设为 2
5. 添加环境变量：
```
secrets:
  ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID: "<Application (client) ID>"
  ENTRA_ID_CUSTOM_OPENID_SCOPE: "<scope URI, e.g. api://crewai-cli/read>"
```

Okta

创建 App Integration
1. 打开 Okta Admin Console → Applications → Create App Integration
2. 选择 OIDC - OpenID Connect → Web Application → Next
3. 配置：
  - App integration name: CrewAI SSO
  - Sign-in redirect URI: https://<your-domain>/auth/okta/callback
  - Sign-out redirect URI: https://<your-domain>
  - Assignments: 选择谁可以访问（所有人或特定 groups）
4. 点击 Save
收集凭据

在 app details 页面：
- Client ID → OKTA_CLIENT_ID
- Client Secret → OKTA_CLIENT_SECRET
- Okta URL（右上角用户名下方）→ OKTA_SITE
配置 Authorization Server
1. 导航到 Security → API
2. 选择你的 authorization server（默认：default）
3. 在 Access Policies 下添加 policy 和 rule：
  - 在 rule 中的 Scopes requested 下，选择 The following scopes → OIDC default scopes
4. 记下 authorization server 的 Name 和 Audience
Warning

authorization server 的 name 和 audience 必须与 OKTA_AUTHORIZATION_SERVER 和 OKTA_AUDIENCE 完全一致。不匹配会导致 401 Unauthorized 或 Invalid token: Signature verification failed 错误。

设置环境变量

envVars:
  AUTH_PROVIDER: "okta"

secrets:
  OKTA_CLIENT_ID: "<Okta app client ID>"
  OKTA_CLIENT_SECRET: "<Okta client secret>"
  OKTA_SITE: "https://your-domain.okta.com"
  OKTA_AUTHORIZATION_SERVER: "default"
  OKTA_AUDIENCE: "api://default"

启用 CLI 支持（可选）
1. 创建一个新的 app integration：OIDC → Native Application
2. 启用 Device Authorization 和 Refresh Token grant types
3. 允许组织中的所有人访问
4. 添加环境变量：
```
secrets:
  OKTA_DEVICE_AUTHORIZATION_CLIENT_ID: "<Native app client ID>"
```
Note

Device Authorization 需要 Native Application - 它不能使用为浏览器 SSO 创建的 Web Application。

Keycloak

创建 Client
1. 打开 Keycloak Admin Console → 进入你的 realm
2. Clients → Create client：
  - Client type: OpenID Connect
  - Client ID: crewai-factory（建议）
3. Capability config：
  - Client authentication: On
  - Standard flow: Checked
4. Login settings：
  - Root URL: https://<your-domain>
  - Valid redirect URIs: https://<your-domain>/auth/keycloak/callback
  - Valid post logout redirect URIs: https://<your-domain>
5. 点击 Save
收集凭据
- Client ID → KEYCLOAK_CLIENT_ID
- 在 Credentials 标签页中：Client secret → KEYCLOAK_CLIENT_SECRET
- Realm name → KEYCLOAK_REALM
- Keycloak server URL → KEYCLOAK_SITE

设置环境变量

envVars:
  AUTH_PROVIDER: "keycloak"

secrets:
  KEYCLOAK_CLIENT_ID: "<client ID>"
  KEYCLOAK_CLIENT_SECRET: "<client secret>"
  KEYCLOAK_SITE: "https://keycloak.yourdomain.com"
  KEYCLOAK_REALM: "<realm name>"
  KEYCLOAK_AUDIENCE: "account"
  # Only set if using a custom base path (pre-v17 migrations):
  # KEYCLOAK_BASE_URL: "/auth"

启用 CLI 支持（可选）
1. 再创建一个第二个 client：
  - Client type: OpenID Connect
  - Client ID: crewai-factory-cli（建议）
  - Client authentication: Off（Device Authorization 需要 public client）
  - Authentication flow: 只勾选 OAuth 2.0 Device Authorization Grant
2. 添加环境变量：
```
secrets:
  KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID: "<CLI client ID>"
```

WorkOS

在 WorkOS Dashboard 中配置
1. 在 WorkOS Dashboard 中创建一个 application
2. 配置 redirect URI：https://<your-domain>/auth/workos/callback
3. 记下 Client ID 和 AuthKit domain
4. 在 WorkOS dashboard 中设置 organizations

设置环境变量

envVars:
  AUTH_PROVIDER: "workos"

secrets:
  WORKOS_CLIENT_ID: "<WorkOS client ID>"
  WORKOS_AUTHKIT_DOMAIN: "<your-authkit-domain.authkit.com>"

Auth0

创建 Application
1. 在 Auth0 Dashboard 中创建一个新的 Regular Web Application
2. 配置：
  - Allowed Callback URLs: https://<your-domain>/auth/auth0/callback
  - Allowed Logout URLs: https://<your-domain>
3. 记下 Domain、Client ID 和 Client Secret

设置环境变量

envVars:
  AUTH_PROVIDER: "auth0"

secrets:
  AUTH0_CLIENT_ID: "<Auth0 client ID>"
  AUTH0_CLIENT_SECRET: "<Auth0 client secret>"
  AUTH0_DOMAIN: "<your-tenant.auth0.com>"

启用 CLI 支持（可选）
1. 在 Auth0 中为 Device Authorization 创建一个 Native application
2. 在 application settings 中启用 Device Authorization grant type
3. 使用合适的 audience 和 client ID 配置 CLI

CLI 认证

CrewAI CLI 支持通过 Device Authorization Grant 流程进行 SSO 认证。这让开发者可以在终端中认证，而无需暴露凭据。

快速设置

对于 Factory installations，CLI 可以自动配置所有 OAuth2 设置：

crewai enterprise configure https://your-factory-url.app

此命令会从你的 Factory instance 中拉取 SSO 配置，并自动设置所有必需的 CLI 参数。

然后进行认证：

crewai login

手动 CLI 配置

如果你需要手动配置 CLI，可以使用 crewai config set：

# Set the provider
crewai config set oauth2_provider okta

# Set provider-specific values
crewai config set oauth2_domain your-domain.okta.com
crewai config set oauth2_client_id your-client-id
crewai config set oauth2_audience api://default

# Set the enterprise base URL
crewai config set enterprise_base_url https://your-factory-url.app

CLI 配置参考

Setting	说明	示例
`enterprise_base_url`	你的 CrewAI instance URL	`https://crewai.yourcompany.com`
`oauth2_provider`	provider 名称	`workos`, `okta`, `auth0`, `entra_id`, `keycloak`
`oauth2_domain`	provider domain	`your-domain.okta.com`
`oauth2_client_id`	OAuth2 client ID	`0oaqnwji7pGW7VT6T697`
`oauth2_audience`	API audience 标识符	`api://default`

查看当前配置：

crewai config list

Device Authorization 如何工作

运行 crewai login - CLI 向你的 IdP 请求 device code
终端中会显示 verification URL 和 code
浏览器会打开 verification URL
输入 code 并使用你的 IdP 凭据进行认证
CLI 接收 access token 并将其保存在本地

Role-Based Access Control（RBAC）

CrewAI Platform 提供细粒度 RBAC，并与 SSO provider 集成。

权限模型

Permission	说明
Read	查看资源（dashboards、automations、logs）
Write	创建和修改资源
Manage	完整控制，包括删除和配置

资源

权限可以作用于单个资源：

Usage Dashboard - Platform 使用指标和分析
Automations Dashboard - Crew 和 flow 管理
Environment Variables - Secret 和配置管理
Individual Automations - 按自动化访问控制

Roles

预定义 roles 开箱即用，带有标准权限集
自定义 roles 可以用任意权限组合创建
按资源分配 - 将特定 automations 限制给单个用户或 roles

Factory Admin Access

对于使用 Entra ID 的 Factory deployments，admin 访问由 App Roles 控制：

将 factory-admin role 分配给需要访问管理面板的用户
将 member role 分配给标准平台访问用户
roles 会通过 JWT claims 传达 - IdP 设置完成后不需要额外配置

故障排查

无效的 Redirect URI

症状： 认证因 redirect URI mismatch 而失败。

修复： 确保 IdP 中的 redirect URI 与期望的 callback URL 完全一致：

Provider	Callback URL
Entra ID	`https://<domain>/auth/entra_id/callback`
Okta	`https://<domain>/auth/okta/callback`
Keycloak	`https://<domain>/auth/keycloak/callback`
WorkOS	`https://<domain>/auth/workos/callback`
Auth0	`https://<domain>/auth/auth0/callback`

CLI 登录失败（Device Authorization）

症状： crewai login 返回错误或超时。

修复：

验证你的 IdP 已启用 Device Authorization Grant
对于 Okta：确保你使用的是 Native Application（而不是 Web），并且启用了 Device Authorization grant
对于 Entra ID：确保已启用 Allow public client flows
对于 Keycloak：确保 CLI client 的 Client authentication: Off，并且只启用了 Device Authorization Grant
检查服务器上是否设置了 *_DEVICE_AUTHORIZATION_CLIENT_ID environment variable

Token 验证错误

症状： 登录后出现 Invalid token: Signature verification failed 或 401 Unauthorized。

修复：

Okta： 验证 OKTA_AUTHORIZATION_SERVER 和 OKTA_AUDIENCE 是否与 authorization server 的 Name 和 Audience 完全一致
Entra ID： 确保 app manifest 中的 accessTokenAcceptedVersion 设为 2
Keycloak： 验证 KEYCLOAK_AUDIENCE 是否与 access tokens 中的 audience 一致（默认：account）

未授予 Admin Consent（Entra ID）

症状： 用户无法登录，看到 “needs admin approval” 提示。

修复： 进入 Enterprise applications → 你的 app → Permissions → Grant admin consent。确认 Microsoft Graph 的 User.Read 已授予。

登录后 403 Forbidden

症状： 用户成功认证，但收到 403 错误。

修复：

检查用户是否已在你的 IdP 中分配到该 application
对于 Assignment required = Yes 的 Entra ID：确保用户拥有角色分配（Member 或 Factory Admin）
对于 Okta：验证用户或其 group 是否已在 app 的 Assignments 标签页中分配

CLI 无法连接到 Factory instance

症状： crewai enterprise configure 连接失败。

修复：

验证 Factory URL 可从你的机器访问
检查 enterprise_base_url 是否设置正确：crewai config list
确保 TLS certificates 有效且受信任

环境变量参考

通用

Variable	说明
`AUTH_PROVIDER`	认证 provider：`entra_id`, `okta`, `workos`, `auth0`, `keycloak`, `local`

Microsoft Entra ID

Variable	Required	说明
`ENTRA_ID_CLIENT_ID`	✅	来自 Azure 的 Application (client) ID
`ENTRA_ID_CLIENT_SECRET`	✅	来自 Azure 的 Client secret
`ENTRA_ID_TENANT_ID`	✅	来自 Azure 的 Directory (tenant) ID
`ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID`	仅 CLI	Device Authorization Grant 的 Client ID
`ENTRA_ID_CUSTOM_OPENID_SCOPE`	仅 CLI	来自 “Expose an API” 的自定义 scope（例如 `api://crewai-cli/read`）

Okta

Variable	Required	说明
`OKTA_CLIENT_ID`	✅	Okta application client ID
`OKTA_CLIENT_SECRET`	✅	Okta client secret
`OKTA_SITE`	✅	Okta organization URL（例如 `https://your-domain.okta.com`）
`OKTA_AUTHORIZATION_SERVER`	✅	Authorization server name（例如 `default`）
`OKTA_AUDIENCE`	✅	Authorization server audience（例如 `api://default`）
`OKTA_DEVICE_AUTHORIZATION_CLIENT_ID`	仅 CLI	Device Authorization 的 Native app client ID

WorkOS

Variable	Required	说明
`WORKOS_CLIENT_ID`	✅	WorkOS application client ID
`WORKOS_AUTHKIT_DOMAIN`	✅	AuthKit domain（例如 `your-domain.authkit.com`）

Auth0

Variable	Required	说明
`AUTH0_CLIENT_ID`	✅	Auth0 application client ID
`AUTH0_CLIENT_SECRET`	✅	Auth0 client secret
`AUTH0_DOMAIN`	✅	Auth0 tenant domain（例如 `your-tenant.auth0.com`）

Keycloak

Variable	Required	说明
`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（默认：`account`）
`KEYCLOAK_BASE_URL`	可选	Base URL path（例如预 v17 迁移时的 `/auth`）
`KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID`	仅 CLI	用于 Device Authorization 的 public client ID

下一步

Installation Guide - 开始使用 CrewAI
Quickstart - 构建你的第一个 crew
RBAC Setup - 详细的角色与权限管理