Skip to main content

​
Overview

This guide walks you through configuring Okta as your Single Sign-On (SSO) provider for CrewAI Factory installations.
Installing for the first time? The Deployment Guides provide complete end-to-end walkthroughs with infrastructure setup, full values.yaml examples, and post-install steps. Use the closest guide as a base and replace the auth section with this page’s Helm values.

​
Initial Setup

Open your Okta admin panel. Use the left sidebar to navigate to “Applications” > “Applications”. Then click “Create App Integration”. Okta Create App Integration Choose “OIDC - OpenID Connect” and “Web Application”. Click Next. Okta App Integration Type Give a name for your app (suggested: CrewAI SSO). In the sign-in redirect URI, add the URI of your CrewAI Factory installation and add /auth/okta/callback at the end (e.g. https://myfactoryurl.crewai.com/auth/okta/callback) For the sign-out URI, just add the plain URI of your CrewAI Factory installation (e.g. https://myfactoryurl.crewai.com/auth/okta/callback) Okta App Configuration Under “Assignments”, choose the preferred way to control access to the app - everyone or limit access to selected groups. Click “Save”. Okta Assignments

​
Collecting Credentials

Now with the app created, we can collect the necessary credentials for the CrewAI Factory application environment variables.
  • Under “Client Credentials”, copy the Client ID. This value should be assigned to the OKTA_CLIENT_ID.
  • Under “Client Secrets” copy the existing secret or generate a new one. The secret should be assigned to the OKTA_CLIENT_SECRET environment variable.
  • On the top right corner under your Okta username, you can obtain your unique okta URL. Copy it and assign to the OKTA_SITE environment variable.
Okta Client Credentials

​
Managing Access

Now, under “Assignments” tab, we can manage who has access to this application (if you haven’t enabled “Everyone” when creating the app). If you enabled access only to specific people or groups and didn’t assign them at app creation time, it is a good moment to do so. Just click “Assign”, choose if “People” or “Groups” and follow the prompts on screen. Okta Assignments Management

​
Configure Authorization Server

And lastly, we have to configure our authorization server with a policy that allows using our newly created app to login into CrewAI Factory. On the left sidebar, find “Security”, and then “API”. Okta Security API You should have at least one authorization server, named “default”. We will use this server for demonstrating the configuration, but you can use another server or create a new one if needed. Just remember that the name of the authorization server that you want to use should be the same as the value of the OKTA_AUTHORIZATION_SERVER environment variable. Use the same value value as Audience of the OKTA_AUDIENCE environment variable
NOTE: If you create a custom authorization server instead of using the default, or even if you edit the default one, make sure to update the environment variables OKTA_AUTHORIZATION_SERVER and OKTA_AUDIENCE with the matching values of “Name” and “Audience” displayed in the authorization servers table listing.Failure to do so will likely result in "401 Client Error: Unauthorized for url" or "Invalid token: Signature verification failed" errors when trying to authenticate with the CrewAI CLI tool.
Click on “Edit” icon in the server that you will use as your authorization server. Okta Authorization Server Edit Under the “Access Policies” tab, click “Add Policy”, or, if you have existing Policies, “Add New Access Policy”. Okta Access Policies After adding the policy, click on “Add rule” to add a new rule to the Policy. Okta Add Rule Leave everything as default, except under “Scopes requested” - there, you should click “The following scopes:”, and then under the input area, click “OIDC default scopes”. Click “Create rule” to save. Okta Scope Configuration

​
Configure Group Claims for Team Mapping

To manage CrewAI Team access from Okta groups:
  1. Go to Security → API → Authorization Servers and select the authorization server used by CrewAI.
  2. Open Claims → Add Claim.
  3. Configure:
    • Name: groups
    • Include in token type: ID Token
    • Inclusion: Always
    • Value type: Groups
    • Filter: Matches regex
    • Value: .* to include the user’s existing groups
    • Include in: Any scope, if displayed
  4. Under Applications → your CrewAI application → Assignments, assign every user or group that may sign in.
Application assignment controls who can sign in. The groups claim controls mapped CrewAI Team access. CrewAI reads groups by default, so set SSO_GROUP_MEMBERSHIP_CLAIM_NAME only when the claim uses another name.
Select Matches regex when using .*. Starts with treats it literally and returns no groups. Okta also rejects authorization when more than 100 groups match. If users approach that limit, replace .* with a filter or allowlist for existing relevant groups; you do not need to create or rename groups with a CrewAI-specific prefix.
These steps use a custom authorization server such as default, which requires Okta API Access Management in production. If your subscription supports only the Org Authorization Server, configure the groups claim under the application’s Sign On tab, set OKTA_USE_ORG_AUTH_SERVER: "true", and set OKTA_AUDIENCE to the application’s Client ID.
See Okta’s guides for customizing tokens with a groups claim and assigning applications to groups.

​
Helm Values Configuration

OKTA_SITE, OKTA_CLIENT_ID, OKTA_AUTHORIZATION_SERVER, and OKTA_AUDIENCE are non-sensitive identifiers that must be placed under envVars:. OKTA_CLIENT_SECRET is a credential and must be placed under secrets:. The chart template does not render Okta values from secrets: — any Okta value under secrets: is silently absent from pod environment variables.
Environment variable reference (equivalent values):
oauth.enabled is NOT required for Okta SSO. Enabling it unnecessarily adds a database pre-creation requirement and deploys an additional microservice. oauth.enabled controls the Built-In Integrations service (Gmail, HubSpot, etc.) — it is separate from SSO authentication.

​
Combining With Other Features

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

​
Map Okta Groups to CrewAI Teams

Follow SSO Team Mapping, using the exact Okta group name emitted in the configured claim as the CrewAI mapping’s group_name. Group names must match exactly, including capitalization.

​
Configure the CLI to use Okta as your OAuth2 provider

First of all, let’s make sure you have a dedicated application to perform the Device Authorization Grant Flow. To do that, open your Admin Okta console and click in Create App Integration Select OIDC - OpenID Connect as the Sign-in method, and then Native Application as the Application type.
Device Authorization is only supported for use with a native application.
Okta Native Application Now, click Next and specify the App integration name. You must Select Device Authorization and Refresh Token as the grant types and then select Allow everyone in your organization to access in the Assignments section. After all is selected, click Save. Okta Device Authorization Configuration Now, set the OKTA_DEVICE_AUTHORIZATION_CLIENT_ID environment variable to match the client_id generated for your app.
Now you are ready to configure your enterprise CLI login! Make sure your crewai CLI is version 0.159.0 or higher. To configure the Okta provider just run the following command:
All set! You’re now ready to authenticate using Okta: