> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Just-in-Time SSO provisioning
> Provision CrewAI Enterprise SaaS users and Team access from identity-provider groups
This guide assumes your CrewAI Enterprise SaaS SSO connection is already active and users can authenticate. It covers the additional configuration required to provision users into the correct CrewAI organization and map identity-provider groups to CrewAI Teams.
If users cannot sign in through your identity provider yet, complete the standard SSO onboarding with your CrewAI account team before using this guide.
## How JIT provisioning works
During a complete SSO sign-in:
1. CrewAI identifies the existing CrewAI organization linked to the WorkOS organization.
2. A first-time user joins that CrewAI organization.
3. CrewAI reads the user's identity-provider groups from the managed `idp_groups` attribute.
4. Group-to-Team mappings add or remove SSO-managed Team access.
Team memberships assigned directly in CrewAI are not removed by SSO reconciliation.
JIT SSO is not Directory Sync or SCIM. Group changes are applied when the user next completes an SSO sign-in. Removing a user's SSO application assignment prevents future SSO sign-ins but does not immediately delete the CrewAI user or their existing access.
## Responsibilities
### CrewAI account team
Before users test JIT provisioning, CrewAI must:
* Link the organizations in both directions: the CrewAI organization stores the WorkOS Organization ID, and the WorkOS organization references the CrewAI Organization ID.
* Confirm that the WorkOS SSO connection is active.
* Confirm that the provider's group claim maps to the managed `idp_groups` attribute.
New Microsoft Entra ID, Okta, Keycloak, and Auth0 SAML connections receive the known `idp_groups` mapping automatically when the connection becomes active. CrewAI confirms or updates the mapping for connections that were already active and handles other provider types manually.
### Identity-provider administrator
The customer administrator must:
* Configure a group claim on the existing CrewAI SSO application.
* Assign the users and groups that may access CrewAI.
* Use stable group values that CrewAI can map to Teams.
The administrator does not need to create WorkOS roles or send the group claim details to CrewAI for Entra ID, Okta, Keycloak, or Auth0 SAML.
### CrewAI organization administrator
The CrewAI administrator maps the emitted group values to Teams in CrewAI Settings or through the public API.
## Prerequisites
* An active CrewAI Enterprise SaaS SSO connection
* An existing CrewAI organization with available seats
* Administrator access to the identity provider
* CrewAI organization administrator access
* The identity-provider groups and CrewAI Teams to connect
* A test user who can complete a new SSO sign-in
## Configure the group claim
Configure only the group claim on the existing SSO application. The remaining SSO connection settings should already be complete.
1. Go to **Microsoft Entra ID** → **Enterprise applications** → **All applications** and select the CrewAI SAML application.
2. Open **Single sign-on** → **SAML**.
3. In **Attributes & Claims**, select **Edit**.
4. Select **Add a group claim**. If a group claim already exists, select it to edit it.
5. Select **Groups assigned to the application**. If that option is unavailable, select **Security groups**.
6. Set **Source attribute** to **Group ID**, keep the default claim name, and leave **Emit groups as role claims** unchecked.
7. Open **Users and groups** and assign the users and groups that should access CrewAI.
8. From **Microsoft Entra ID** → **Groups**, record the **Object ID** of each group you want to map to a CrewAI Team.
Entra emits the group claim as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`. CrewAI Team mappings use the immutable group Object IDs contained in that claim.
**Groups assigned to the application** requires Microsoft Entra ID P1 or P2 and includes direct memberships only. Entra omits the group list when a SAML assertion exceeds its 150-group limit, so limit the claim to groups relevant to CrewAI. See the [WorkOS Entra ID SAML guide](https://workos.com/docs/integrations/entra-id-saml).
1. Go to **Applications** → **Applications** and select the CrewAI SAML application.
2. Open **Sign On**, select **Edit**, and locate **Group Attribute Statements**.
3. Add a statement with:
* **Name:** `groups`
* **Filter:** **Matches regex**
* **Value:** `.*`
4. Open **Assignments** and assign the users or groups that should access CrewAI.
5. Record the exact, case-sensitive name of each group you want to map to a CrewAI Team.
You can replace `.*` with a narrower regular expression when users belong to many unrelated groups. You do not need to create CrewAI-specific groups; the filter can select your existing Okta groups.
**Starts with** treats `.*` as literal text. Select **Matches regex** when using a regular expression. See the [WorkOS Okta SAML guide](https://workos.com/docs/integrations/okta-saml).
1. Open the CrewAI SAML client in the Keycloak Admin Console.
2. On **Dedicated scopes**, select **Add mapper** → **By configuration**.
3. Select **Group list**.
4. Set both **Name** and **Group attribute name** to `groups`.
5. Enable **Single Group Attribute** and save the mapper.
6. Record the exact group values emitted for the users you want to map to CrewAI Teams.
See the [WorkOS Keycloak SAML guide](https://workos.com/docs/integrations/keycloak-saml).
1. Go to **Applications** → **Applications** and select the CrewAI application.
2. Create a **Post Login Action** that builds an array from your authoritative access source:
* Auth0 groups available through `api.groups.getUserGroups()`
* Auth0 RBAC roles from `event.authorization.roles`
* A group array maintained in user app metadata
3. Emit that array as a SAML attribute named `groups` with `api.samlResponse.setAttribute("groups", groups)`.
4. Deploy the Action and add it to **Actions** → **Flows** → **Login**.
5. Record the exact group IDs, group names, or role names emitted for CrewAI Team mapping.
Always emit an array, including an empty array when the user has no relevant access values. See the [WorkOS Auth0 SAML guide](https://workos.com/docs/integrations/auth0-saml), the Auth0 [Post Login API](https://auth0.com/docs/actions/reference/post-login/post-login-api-object), and [custom SAML assertion](https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions) references.
Use the appropriate [WorkOS integration guide](https://workos.com/docs/integrations). Configure the existing SSO application to:
1. Emit the user's relevant groups as a multi-valued SAML attribute or OIDC claim.
2. Use stable strings such as immutable group IDs or exact group names.
3. Emit an empty array when the user has no relevant groups.
After configuring the claim, provide its name and sample non-secret values to your CrewAI account team. CrewAI must map providers without a known automatic mapping to `idp_groups`.
## Map groups to CrewAI Teams
A CrewAI organization administrator can configure mappings in **Settings** → **Teams**:
1. Create or select the destination Team.
2. Confirm that **SSO** is enabled under **Membership sources**.
3. Under **SSO group mappings**, select **Add mapping**.
4. Enter the exact value emitted by the identity provider:
* Entra ID: group Object ID
* Okta: exact, case-sensitive group name
* Keycloak, Auth0, or another provider: exact group ID, group name, or role name selected during claim setup
5. Select the destination Team and save the mapping.
One identity-provider group can map to multiple Teams, and multiple groups can map to the same Team.
To automate this step, use a [service account](/api/service-account) with the [Teams API](/api/v1/reference/teams/list-teams) and [Create a group mapping](/api/v1/reference/group-mappings/create-a-group-mapping). The API reference is the source of truth for request and response fields.
## Validate JIT provisioning
1. Wait for your CrewAI account team to confirm the organization link and `idp_groups` mapping.
2. Assign the test user to the CrewAI SSO application and one mapped group.
3. Have the user complete a new SSO sign-in.
4. Confirm that the user joined the existing CrewAI organization and the expected Teams.
5. Remove the user from a mapped group while keeping access to the SSO application.
6. Have the user sign out and complete another SSO sign-in.
7. Confirm that the SSO-managed Team access was removed and directly assigned Team access remained unchanged.
## Troubleshooting
### The user joins a new organization
Stop testing and contact your CrewAI account team. The WorkOS and CrewAI organizations are not linked correctly.
### The user joins the organization but not the expected Team
* Confirm that the SSO membership source is enabled in **Settings** → **Teams**.
* Confirm that the CrewAI mapping exactly matches the emitted value.
* Confirm that the group claim is an array and includes the expected value.
* Complete a new SSO sign-in; refreshing an existing session does not reconcile Team access.
### The provider does not emit a group
* **Entra ID:** Confirm that the group is assigned to the application, the source is **Group ID**, and **Emit groups as role claims** is disabled.
* **Okta:** Confirm that the statement is named `groups` and uses **Matches regex**.
* **Keycloak:** Confirm that the mapper uses `groups` and **Single Group Attribute** is enabled.
* **Auth0:** Confirm that the Post Login Action is deployed, attached to the Login flow, and passes an array to `api.samlResponse.setAttribute`.
* **Other providers:** Confirm the source claim name with your CrewAI account team.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.