Skip to main content

​
Overview

CrewAI Factory can reconcile Team membership from groups supplied by your identity provider. The identity provider remains the source of truth for group membership, while CrewAI group mappings define which Teams those external groups grant. The sign-in flow is:
  1. The identity provider sends a complete group list.
  2. CrewAI reads the configured group claim.
  3. Each claim value is matched against CrewAI group mappings.
  4. CrewAI adds or removes JIT-managed Team memberships to match the latest list.
Direct Team assignments are not changed by SSO reconciliation.

​
Configure the Group Claim

CrewAI reads the groups claim by default for direct OIDC providers. Follow the provider-specific instructions to emit a complete array: If your provider uses another claim name, set:
WorkOS uses the organization membership custom attribute idp_groups instead of SSO_GROUP_MEMBERSHIP_CLAIM_NAME. See WorkOS SSO.

​
Create CrewAI Group Mappings

1

Create an API service account

Create a CrewAI service account and access token by following the Service Accounts API guide.
2

Get the Team ID

Use the official API reference to list existing Teams or create a Team. Copy the Team’s data.id.
3

Create the mapping

Follow Create a group mapping, using the exact external identifier as group_name and the CrewAI Team ID as team_id.Identifier formats depend on the provider:
4

Validate reconciliation

Sign in with a user who belongs to a mapped group and confirm that the corresponding Team appears. Then remove that user from the external group, sign in again, and confirm that CrewAI removes only the JIT-managed Team membership.
One external group can map to multiple Teams, and multiple external groups can map to the same Team.
Mapping values must match the emitted claim values exactly, including capitalization. Entra mappings use group object IDs rather than display names.

​
Complete, Empty, and Missing Claims

CrewAI distinguishes between an empty group list and an unavailable group list:
  • A valid empty array, such as "groups": [], is a complete snapshot and removes existing JIT-managed Team memberships.
  • A missing or malformed claim is not a complete snapshot. CrewAI preserves existing JIT-managed Team memberships because it cannot safely determine what should be removed.
Always configure the identity provider to emit an array, including an empty array when the user has no groups.