> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO Team Mapping

> Map identity-provider groups to CrewAI Teams during SSO sign-in.

## 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:

* [Microsoft Entra ID](/features/entra-id#configure-group-claims-for-team-mapping)
* [Okta](/features/okta-sso#configure-group-claims-for-team-mapping)
* [Auth0](/features/auth0-sso#configure-group-claims-for-team-mapping)
* [Keycloak](/features/keycloak-sso#configure-group-claims-for-team-mapping)

If your provider uses another claim name, set:

```yaml theme={null}
envVars:
  SSO_GROUP_MEMBERSHIP_CLAIM_NAME: "<claim-name>"
```

<Note>
  WorkOS uses the organization membership custom attribute `idp_groups` instead of `SSO_GROUP_MEMBERSHIP_CLAIM_NAME`. See [WorkOS SSO](/features/workos-sso#configure-group-claims-for-team-mapping).
</Note>

## Create CrewAI Group Mappings

<Steps>
  <Step title="Create an API service account">
    Create a CrewAI service account and access token by following the [Service Accounts API guide](https://docs.crewai.com/api/service-account).
  </Step>

  <Step title="Get the Team ID">
    Use the official API reference to [list existing Teams](https://docs.crewai.com/api/v1/reference/teams/list-teams) or [create a Team](https://docs.crewai.com/api/v1/reference/teams/create-a-team). Copy the Team's `data.id`.
  </Step>

  <Step title="Create the mapping">
    Follow [Create a group mapping](https://docs.crewai.com/api/v1/reference/group-mappings/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:

    | Provider | `group_name` value |
    | - | - |
    | Microsoft Entra ID | Immutable group object ID |
    | Okta | Group name emitted in the claim |
    | Auth0 | Role or group value emitted in the configured claim |
    | Keycloak | Group name or full path emitted in the claim |
    | WorkOS | Value stored in `custom_attributes.idp_groups` |
  </Step>

  <Step title="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.
  </Step>
</Steps>

One external group can map to multiple Teams, and multiple external groups can map to the same Team.

<Warning>
  Mapping values must match the emitted claim values exactly, including capitalization. Entra mappings use group object IDs rather than display names.
</Warning>

## 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.