---
title: Sync groups from Entra ID
slug: opti-id/docs/sync-groups-from-entra-id
docTags: 
createdAt: 2026-07-30T20:38:24.317Z
---

In Opti ID, user access to any entitled product is done using groups. For more information on groups in Opti ID, see [Manage groups](../../opti-id/manage-the-admin-center/manage-groups.mdx).

To ease the process of assigning users to groups, Opti ID lets you automatically add users to existing groups within Opti ID when they sign in. To enable this, you must configure the single sign-on (SSO) provider to send a groups claim with the assertion during user login.

## Prerequisites

- Configure the SAML or OIDC SSO connection in your identity provider (IdP).
  - [Configure SAML SSO with Entra ID](docId\:XhMGgM6XcnSe9jx5cNiZc)
  - [Configure OIDC SSO with Entra ID](docId\:ARv4NskeO_S86B0flcRAl)
- Create groups in your IdP with names that mirror the Opti ID group names you want to sync.

## Considerations

:::hint{type="warning"}
**Important**

This group sync does not handle deprovisioning. If you want your group sync to handle deprovisioning in addition to securely automating user and group provisioning, you should [configure SCIM](../../opti-id/scim-provisioning/overview-of-scim-provisioning-for-opti-id.mdx) instead.
:::

- The groups claim must be a string array. The string values must be the names of the groups as represented in Opti ID.
- The groups specified in the groups claim must already exist in the Opti ID organization that the SSO provider exists in.
- When users are created using just-in-time (JIT) provisioning, they are added to the **Everyone** group. If the SSO provider provided any groups claims for the logged-in user, and groups with the same name exist in Opti ID, then users are added to user groups in Opti ID when they sign in.
- The user creation process for JIT provisioning happens regardless of the groups claim, so even if the groups claim is missing or has groups not found in Opti ID, the user is still created and added to the **Everyone** group.
- When you add a user in the upstream SSO provider, if Opti ID receives any groups as claims at the time of login and these groups exist in Opti ID with the same name, Opti ID adds the user (if not already present) along with the groups.
- When you update a user in the upstream SSO provider (for example, add groups to the user), and Opti ID receives these groups as claims at the time of login, Opti ID adds the user to those groups, provided groups with the same name exist in Opti ID.
- The sync from your SSO provider to Opti ID only adds groups (or users to groups). If you remove a group (or a user from a group) in your SSO provider, you must manually remove that group (or user from that group) in Opti ID.
- If you change the name of a group in Opti ID, you must make the same changes in your SSO provider. Similarly, if you change the name of the group in your SSO provider, you must make the same changes in Opti ID. Otherwise, any group membership changes you make in the SSO provider will not be reflected in Opti ID.

## Set up group sync in Entra ID

You should review some initial considerations for using Entra ID. The feature availability is based on the current Entra ID SKU noted below. For Application groups functionality, the Entra ID instance must be a premium SKU. If you do not have access to the premium SKU, you can use alternative methods to provide group information in the claims while logging into Opti ID by assigning individual users to the application.

1. In Entra ID, go to the enterprise application you set up for SSO.
2. Click **Single sign-on** > **Edit** in the **Attributes & Claims** section.

   ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/S4He_jy2dylst2IYLhZuu_zd-33442105891853.png)
3. Click **Add a group claim**.

   ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/Re1WIvFDJx3XYMyG-4gk5_zd-18625738764301.png)
4. On the **Group Claims** page, select the desired groups to be returned in the claim, such as **Groups assigned to the application**.
5. Expand the **Source attribute** drop-down list and select the attribute that will have the group name in it.

   :::hint{type="info"}
   **Note**

   The **Source attribute** value must match the group name in Opti ID for the mapping to work.

   - **Microsoft Entra ID-based customers** – Select **Cloud-only group display names**.
   - **On-premises customers who sync to Azure AD** – Select **sAMAccountName**, having that attribute configured correctly in Active Directory.
   :::
6. (Optional) Set the **Filter groups** section in **Advanced options**, based on your organization's requirements, to send only the groups you want to sync with Opti ID.
7. Customize the name of the group claim with **Groups** as the **Name** and no **Namespace**. The other checkboxes can remain cleared.

   ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/QBBvfD8FlS9cPNuacZzQd-20260720-154755.png)

The SSO provider sends the group IDs in an array, which Opti ID receives and adds the users to the appropriate groups when they sign in.

## Assign users to groups in Entra ID

1. In the **Azure portal**, go to **Microsoft Entra ID > Groups**.
2. Select the group you want to manage.
3. Select either **Members** or **Owners**.
4. Click **Add** (members or owners).
5. Search for and select the users you want to add (you can select multiple users at one time).
6. Click **Select**.
7. The **Group Overview** page updates to show the number of members or owners you added to the group.

## Set up groups claim in SAML or OIDC app

### SAML app

1. In Entra ID, go to the enterprise application you set up for SSO.
2. Go to **Single sign-on > Attributes & Claims > Edit**.

   ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/yL7A1ZTnIPjHOthalAj66_zd-33442105896845.png)
3. Click **Add a group claim**.
4. On the **Group Claims** page, select the desired groups you want to return in the claim (like **Groups assigned to the application**).
5. Select the attribute that will have the group name in it for the **Source attribute** drop-down list. The **Source attribute** value must match the group name in Opti ID for the mapping to work.
   - If you are Entra ID-based, **Cloud-only group display names** usually works.
   - If you are on-prem, **sAMAccountName** usually works as long as you configure that attribute correctly in your active directory.
6. (Optional) Set the **Filter groups** section in **Advanced options** to send only the groups you want to sync with Opti ID, based on your organization's requirements.
7. Customize the name of the group claim with **Groups** as the **Name** and no **Namespace**. You can leave the other checkboxes unselected.

### OIDC app

1. In Entra ID, go to the application registration you set up for SSO.
2. Under **Manage**, click **Token configuration**.
3. Click **Add groups claim**.
4. Select the group types to return (**Security groups**, **Directory roles**, **all groups**, or **Groups assigned to the application**).
5. Click **Save**.

Complete the following steps to configure groups optional claims through the application manifest:

1. Select the application for which you want to configure optional claims.
2. Under **Manage**, click **Manifest**.
3. Using the manifest editor, for ID token type, modify the groups claim to use the `optionalClaims` section in the manifest as follows:

```javascript
"optionalClaims": {
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "cloud_displayname"
            ]
        }
    ]
} 
```

:::Paragraph{listStyleType="disc" indent="3"}
If you are Entra ID-based, adding `cloud_displayname` in `additionalProperties` usually works.
:::

:::Paragraph{listStyleType="disc" indent="3"}
If you are on-prem, adding `sam_account_name` in `additionalProperties` usually works.
:::

4. (Optional) Go to **Single sign-on** > **Attributes & Claims > Edit** to set the **Filter groups**. Add group filter criteria based on your organization's requirements to send only the groups you want to sync with Opti ID.

The SSO provider sends the group names in an array, which Opti ID receives and adds the users to the appropriate groups when they sign in.

## Create groups in Opti ID Admin Center

1. Go to **Group Access > Groups** in the Opti ID Admin Center.
2. Click **Add Group** to create a group with the same name as the one you created in your SSO provider. This syncs the group from your SSO provider to the user the next time they log in using Opti ID.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/XLA-IEk2Njzr95C0ncyjT_group-access.png)

This group name must exactly match the group name you send from your SSO provider. Your SSO provider configures this value, so you may need to edit the group name later to match the name your SSO provider sends. For example, in some situations, the best value to send is the IdP's Group ID. In this case, you should make the group name in Opti ID the GUID of the IdP's Group ID.

Opti ID has **Everyone** and **Admin Center Administrators** groups available by default. All users remain in **Everyone**, regardless of what groups the SSO provider sends. If you create an **Admin Center Administrators** group in your SSO provider, you can sync those users to the corresponding group in Opti ID.

### Configure roles and groups

Configure roles and groups in the Opti ID **Admin Center**. See the following topics.

- [Roles](../../opti-id/manage-the-admin-center/roles-and-permissions.mdx)
- [Groups](../../opti-id/manage-the-admin-center/manage-groups.mdx)

## Events when groups sync to Opti ID

**Initial login**

When a user logs in for the first time to Opti ID, group claims in the token, if any, are matched with groups in Opti ID (by group name for your organization). These groups are then assigned to the user at the time of their first successful login.

:::hint{type="success"}
**Note**

You must have domain-based routing set up for successful group assignment at the time of initial login.
:::

If you have [domain-based routing set on your IdP](../../opti-id/configure-sso/configure-organizational-domains.mdx), you can create JIT users in Opti ID. You can also add users to your organization explicitly in the Opti ID Admin Center.

In either case, if any matching groups are found, they are assigned to the user upon successful login.

**Subsequent logins**

In case of subsequent logins by a user through your IdP, any new groups assigned to the user since their previous login get assigned in Opti ID, provided matching groups with same name are found in Opti ID.

:::hint{type="success"}
**Note**

If you removed a user from a group in your SSO provider, subsequent logins by that user do not remove them from that group in Opti ID. You must manually remove the user from the group in Opti ID.
:::

After you complete the steps in this article to sync your SSO groups, you can still explicitly assign the Opti ID groups (corresponding to your SSO groups that are set up in Opti ID) to the users in your organization in the Opti ID Admin Center.