WorkOS SSO

Overview

WorkOS AuthKit provides SSO and directory sync for enterprise organisations. This guide connects CrewAI Platform to your WorkOS application.

Installing for the first time? Use a Deployment Guide for a complete end-to-end walkthrough including infrastructure setup, a full values.yaml, and post-install steps:

Prerequisites

WorkOS account at workos.com
Admin access to the WorkOS Dashboard

Step 1: Create a WorkOS Application

In the WorkOS Dashboard, navigate to Applications
Click Create Application
Enter a name (e.g., CrewAI Platform)
Note the Client ID shown on the application’s main page

Step 2: Configure Redirect URI

In your WorkOS Application settings, add a redirect URI:

https://<APPLICATION_HOST>/auth/workos/callback

Replace <APPLICATION_HOST> with your platform’s hostname (the value you set in envVars.APPLICATION_HOST).

Step 3: Note Your AuthKit Domain

In the WorkOS Dashboard, navigate to Developer → Domains
Note your AuthKit domain (e.g., your-org.authkit.app or a custom domain if configured)

Step 4: Obtain Your API Key

In the WorkOS Dashboard, go to the main API Keys page
Copy your API key — it starts with sk_live_ (production) or sk_test_ (test environment)

Step 5: Configure Your Identity Provider

Create an SSO Connection for the WorkOS organization by following the appropriate WorkOS guide:

Use the ACS URL and SP Entity ID generated for that WorkOS Connection.

Step 6: Configure Group Claims for Team Mapping

CrewAI can map raw identity-provider group values directly to Teams. You do not need to create WorkOS roles or assign every IdP group to a WorkOS role.

Microsoft Entra ID
Okta
Auth0

Go to Entra ID → Enterprise applications and select the SAML application connected to WorkOS.
Open Single sign-on → SAML → Attributes & Claims.
Add or edit the group claim.
Select Groups assigned to the application, or Security groups when that option is unavailable.
Set Source attribute to Group ID, keep the default claim name, and leave Emit groups as role claims unchecked.
Assign every relevant group under Users and groups.

WorkOS receives the SAML attribute http://schemas.microsoft.com/ws/2008/06/identity/claims/groups.

Open the SAML application connected to WorkOS.
Under Sign On, edit the SAML configuration.
Add a Group Attribute Statement:
- Name: groups
- Filter: Matches regex
- Value: .*
Assign every user or group that may sign in.

Starts with treats .* literally. Select Matches regex. If assertions become too large, replace .* with a filter for existing groups relevant to CrewAI.

Open the application configured as the WorkOS SAML identity provider.
Enable the SAML2 Web App add-on with the WorkOS ACS URL and SP Entity ID.
Create a Post Login Action that emits the complete values in a SAML attribute named groups.
Always emit an array, including an empty array when the user has no values.

If Auth0 Core RBAC roles are the source of Team-mapping values:

exports.onExecutePostLogin = async (event, api) => {
  api.samlResponse.setAttribute(
    "groups",
    event.authorization?.roles ?? []
  );
};

In the WorkOS Dashboard:

Create an SSO custom attribute named idp_groups under Identity Provider Attributes.
Enable custom SSO attribute mapping for the WorkOS organization.
Map idp_groups to the source attribute:
- Entra ID: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
- Okta: groups
- Auth0: groups
Sign in again and confirm the WorkOS organization membership contains custom_attributes.idp_groups as an array.

CrewAI’s WorkOS provider always reads idp_groups; SSO_GROUP_MEMBERSHIP_CLAIM_NAME does not change this contract. If Directory Sync and SSO are linked to the same organization membership, Directory User custom attributes take precedence over SSO Profile custom attributes. See WorkOS IdP Attributes for custom-attribute mapping details.

Step 7: Configure Helm Values

Both WORKOS_API_KEY and WORKOS_COOKIE_PASSWORD must be placed under envVars:, not secrets:. The chart template has known gaps: secrets.WORKOS_API_KEY is defined in the values schema but never rendered into the pod environment, and secrets.WORKOS_COOKIE_PASSWORD is not in the secrets schema at all. Values placed under secrets: are silently absent from pods, causing WorkOS authentication to fail with no clear error message.After install, verify both keys are present:

kubectl exec -it deploy/crewai-web -- env | grep -E 'WORKOS_API_KEY|WORKOS_COOKIE_PASSWORD'

Generate a cookie password (must be 32 characters or fewer):

openssl rand -base64 32 | cut -c -32

The openssl rand -base64 32 command produces a 44-character base64 string; the | cut -c -32 suffix truncates it to the required maximum. Omitting the cut step produces a value that WorkOS silently rejects at authentication time. Add to your my-values.yaml:

envVars:
  AUTH_PROVIDER: "workos"
  WORKOS_CLIENT_ID: "client_..."       # From WorkOS Application main page
  WORKOS_AUTHKIT_DOMAIN: "your-org.authkit.app"  # From Developer > Domains
  WORKOS_COOKIE_PASSWORD: "your-32-char-random-string"  # Max 32 characters
  WORKOS_API_KEY: "sk_live_..."        # From WorkOS API Keys page

WORKOS_COOKIE_PASSWORD is stored as an environment variable (not a Kubernetes Secret) by the chart schema. To avoid committing it to version control, supply it via --set or a separate gitignored values file:

helm upgrade crewai-platform ... --set envVars.WORKOS_COOKIE_PASSWORD="$COOKIE_PWD"

oauth.enabled controls the Built-in Integrations service (Google Workspace, Microsoft 365, HubSpot, etc.) — it is NOT required for WorkOS authentication. WorkOS SSO works without oauth.enabled: true.

Map WorkOS Groups to CrewAI Teams

Follow SSO Team Mapping, using the exact values stored in custom_attributes.idp_groups as each CrewAI mapping’s group_name.

Combining With Other Features

Wharf (trace collection): No additional values needed — Wharf is enabled by default. Ensure the wharf database is pre-created before install. See Wharf reference.
Studio V2: Configured entirely post-install via the web UI and kubectl exec commands. No Helm values exist for it. See Enable Studio V2.
Built-in Integrations (Google Workspace, Microsoft 365, etc.): Requires oauth.enabled: true and the relevant OAuth credentials. See Built-In Integrations.
ArgoCD / GitOps: Auto-generated secrets must be set explicitly. See the ArgoCD guide.

After running helm install or helm upgrade, navigate to your platform hostname. You should be redirected to the WorkOS AuthKit login page. If authentication fails, check the web pod logs:

kubectl logs -l app=crewai-web --tail=50 | grep -i workos

Core Configuration

Authentication

Built-In Integrations

Advanced

Overview

Prerequisites

Step 1: Create a WorkOS Application

Step 2: Configure Redirect URI

Step 3: Note Your AuthKit Domain

Step 4: Obtain Your API Key

Step 5: Configure Your Identity Provider

Step 6: Configure Group Claims for Team Mapping

Step 7: Configure Helm Values

Map WorkOS Groups to CrewAI Teams

Combining With Other Features

​Overview

​Prerequisites

​Step 1: Create a WorkOS Application

​Step 2: Configure Redirect URI

​Step 3: Note Your AuthKit Domain

​Step 4: Obtain Your API Key

​Step 5: Configure Your Identity Provider

​Step 6: Configure Group Claims for Team Mapping

​Step 7: Configure Helm Values

​Map WorkOS Groups to CrewAI Teams

​Combining With Other Features

​Verify Login

Overview

Prerequisites

Step 1: Create a WorkOS Application

Step 2: Configure Redirect URI

Step 3: Note Your AuthKit Domain

Step 4: Obtain Your API Key

Step 5: Configure Your Identity Provider

Step 6: Configure Group Claims for Team Mapping

Step 7: Configure Helm Values

Map WorkOS Groups to CrewAI Teams

Combining With Other Features

Verify Login