Skip to main content
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.

​
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 with the Teams API and 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.