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

# SCIM Groups

> Push groups from your identity provider into StackOne over SCIM and grant access through them.

SCIM Provisioning can push your identity provider's groups into StackOne as **synced groups**. Your identity provider (IdP) owns each synced group's name and members. You grant access with it in StackOne exactly as you would with a group you created by hand. Add someone to the group in your directory and they gain the projects the group is assigned to. Remove them and that access goes with them.

Synced groups build on [SCIM Provisioning](/identity/scim/overview) and [Groups](/identity/groups/overview), so both need to be in place first.

## How synced groups work

When your IdP pushes a group, StackOne creates a group of the same name on the **Groups** tab of **Organization > Manage Team**, marked with a **Synced** tag. From then on:

* **Your IdP manages the name and the members.** Rename the group there and it is renamed here. Add or remove members there and the membership follows. In StackOne the group is marked **Managed by your identity provider**, and renaming it, deleting it, and editing its members are disabled.
* **You manage its access.** Assign the group to projects and accounts and choose a role, the same way as for any other group. See [Assign Group Access](/identity/groups/assigning-access).
* **Its members are people your directory has provisioned.** A synced group can only contain members that SCIM Provisioning created or linked through the same connection. Someone who is in the directory group but not assigned to the StackOne application isn't a StackOne member, so they don't appear in the group until they are.

<Note>
  A synced group doesn't set anyone's organization role. Every provisioned user joins at the **Viewer** role, or **Admin** when your IdP sends a `roles` value of `admin`. See [organization role from your identity provider](/identity/sso/jit-provisioning#organization-role-from-your-identity-provider).
</Note>

## Prerequisites

* **SCIM Provisioning linked** on your SSO connection, with users provisioning. See [Enable SCIM Provisioning](/identity/scim/overview#enable-scim-provisioning).
* **Groups enabled** for your organization. If you're an **Org Admin** and don't see the **Groups** tab under **Organization > Manage Team**, contact StackOne support to turn it on.
* **Org Admin**, or **Project Admin** on the project, to assign a group to a project.

## Prepare the access before you push

A pushed group takes over an existing StackOne group of the same name when that group has no members. Names match ignoring case and surrounding spaces. This lets you set up the access before anyone arrives:

<Steps>
  <Step title="Create the group in StackOne">
    On the **Groups** tab, click **Create group** and give it the exact name of the directory group, for example `Finance`. Leave it empty.
  </Step>

  <Step title="Assign its access">
    Open the group's **Projects** tab and add the projects it should grant, each with a role. See [Manage Groups](/identity/groups/managing-groups#assign-the-group-to-projects).
  </Step>

  <Step title="Push the group from your IdP">
    When your IdP pushes `Finance`, StackOne turns your empty group into the synced one and keeps its assignments. Its members gain that access as they are pushed.
  </Step>
</Steps>

<Warning>
  A StackOne group that already has members is never taken over. If your IdP pushes a group with the same name, StackOne creates a second group, tagged **Synced**, and leaves yours untouched. To end up with one `Finance` group, remove the members from yours before the push, or push the directory group under a different name.
</Warning>

## Push groups from your identity provider

<CardGroup cols={2}>
  <Card title="Okta" icon="https://stackone-logos.com/api/okta/filled/svg" href="/identity/scim/okta#push-groups">
    Push groups from the app's **Push Groups** tab.
  </Card>

  <Card title="Microsoft Entra" icon="https://stackone-logos.com/api/microsoft-entra/filled/svg" href="/identity/scim/microsoft-entra#provision-groups">
    Provision the groups assigned to the application.
  </Card>
</CardGroup>

## What changes when

| In your identity provider                                                    | In StackOne                                                                                                                 |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| A group is pushed for the first time.                                        | A synced group appears, or an empty group of the same name becomes the synced group and keeps its access.                   |
| A member is added to or removed from the group.                              | The membership updates, and the access the group grants follows.                                                            |
| The group is renamed.                                                        | The group is renamed. Its assignments stay.                                                                                 |
| The group is deleted, or its push is unlinked and the group deleted with it. | The group is deleted in StackOne. Its members lose the access it granted.                                                   |
| A member is deactivated or unassigned from the application.                  | They leave every synced group, along with the rest of their access. If your IdP reactivates them, their memberships return. |

<Note>
  If you stop pushing a group but keep it in StackOne, it stays a synced group and can't be edited until you unlink SCIM Provisioning. Delete it from your IdP's push instead, or unlink SCIM Provisioning to get every synced group back.
</Note>

## When SCIM Provisioning is unlinked or replaced

Unlinking SCIM Provisioning, or deleting the SSO connection it's on, hands every synced group back to you. Each becomes a normal group that keeps its members and its project and account assignments, and you can edit it again. Nobody loses access.

If you link SCIM Provisioning again, on the same connection or a new one, a pushed group with the same name takes that group back as a synced group, members and assignments intact, rather than creating a second copy.

## Limits

* A group push can contain at most **1,000** direct members. StackOne rejects larger pushes, and your IdP reports the error.
* Synced group names must be unique within the SCIM Provisioning connection. A push that reuses the name of another synced group is rejected. A group you created by hand can share the name, which is how the takeover above works.
* Members must already be provisioned. A push that lists someone SCIM Provisioning doesn't know is rejected until that person is assigned to the StackOne application and provisioned.

## Next steps

<CardGroup cols={2}>
  <Card title="Assign Group Access" icon="key" href="/identity/groups/assigning-access">
    Grant a synced group access to a project or account and set its role.
  </Card>

  <Card title="Manage Groups" icon="user-gear" href="/identity/groups/managing-groups">
    Create groups and manage the ones you own by hand.
  </Card>

  <Card title="SCIM Provisioning" icon="arrows-rotate" href="/identity/scim/overview">
    How provisioning works and how it attaches to your SSO connection.
  </Card>
</CardGroup>