crewAI/docs/en/enterprise/features/sso.mdx

---
title: Single Sign-On (SSO)
icon: "key"
description: Configure enterprise SSO authentication for CrewAI Platform — SaaS and Factory
---

## Overview

CrewAI Platform supports enterprise Single Sign-On (SSO) across both **SaaS (AMP)** and **Factory (self-hosted)** deployments. SSO enables your team to authenticate using your organization's existing identity provider, enforcing centralized access control, MFA policies, and user lifecycle management.

### Supported Providers

| 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

- **SAML 2.0 and OAuth 2.0 / OIDC** protocol support
- **Device Authorization Grant** flow for CLI authentication
- **Role-Based Access Control (RBAC)** with custom roles and per-resource permissions
- **MFA enforcement** delegated to your identity provider
- **User provisioning** through IdP assignment (users/groups)

---

## SaaS SSO

### Default Authentication

CrewAI's managed SaaS platform (AMP) uses **WorkOS** as the default authentication provider. When you sign up at [app.crewai.com](https://app.crewai.com), authentication is handled through `login.crewai.com` — no additional SSO configuration is required.

### Enterprise Custom SSO

Enterprise SaaS customers can configure SSO with their own identity provider (Entra ID, Okta, Auth0). Contact your CrewAI account team to enable custom SSO for your organization. Once configured:

1. Your team members authenticate through your organization's IdP
2. Access control and MFA policies are enforced by your IdP
3. The CrewAI CLI automatically detects your SSO configuration via `crewai enterprise configure`

### CLI Defaults (SaaS)

| Setting | Default Value |
|---|---|
| `enterprise_base_url` | `https://app.crewai.com` |
| `oauth2_provider` | `workos` |
| `oauth2_domain` | `login.crewai.com` |

---

## Factory SSO

Factory (self-hosted) deployments support SSO with the following identity providers:

- **Microsoft Entra ID** (Azure AD)
- **Okta**
- **Keycloak**
- **Auth0**
- **WorkOS**

Each provider requires registering an application in your IdP and configuring the corresponding environment variables in your Helm `values.yaml`.

<Note>
  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).
</Note>

---

## CLI Authentication

The CrewAI CLI supports SSO authentication via the **Device Authorization Grant** flow. This allows developers to authenticate from their terminal without exposing credentials.

### Quick Setup

For Factory installations, the CLI can auto-configure all OAuth2 settings:

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

This command fetches the SSO configuration from your Factory instance and sets all required CLI parameters automatically.

Then authenticate:

```bash
crewai login
```

<Note>
  Requires CrewAI CLI version **1.6.0** or higher for Entra ID, **0.159.0** or higher for Okta, and **1.9.0** or higher for Keycloak.
</Note>

### Manual CLI Configuration

If you need to configure the CLI manually, use `crewai config set`:

```bash
# 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 Configuration Reference

| Setting | Description | Example |
|---|---|---|
| `enterprise_base_url` | Your CrewAI instance URL | `https://crewai.yourcompany.com` |
| `oauth2_provider` | Provider name | `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 identifier | `api://default` |

View current configuration:

```bash
crewai config list
```

### How Device Authorization Works

1. Run `crewai login` — the CLI requests a device code from your IdP
2. A verification URL and code are displayed in your terminal
3. Your browser opens to the verification URL
4. Enter the code and authenticate with your IdP credentials
5. The CLI receives an access token and stores it locally

---

## Role-Based Access Control (RBAC)

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 Read, Write, and Manage permissions
- **Per-resource assignment** — limit specific automations to individual users or roles

For detailed RBAC configuration, see the [RBAC documentation](/enterprise/features/rbac).

---

## Troubleshooting

### 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
- 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:**
- 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 CrewAI application in your IdP
- Verify the user has the appropriate role assignment in your IdP

### CLI Can't Reach CrewAI Instance

**Symptom:** `crewai enterprise configure` fails to connect.

**Fix:**
- 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

---

## Next Steps

- [Installation Guide](/installation) — Get started with CrewAI
- [Quickstart](/quickstart) — Build your first crew
- [RBAC Setup](/enterprise/features/rbac) — Detailed role and permission management