---
title: "Microsoft Entra ID Group Name Sync Configuration"
slug: "microsoft-entra-id-group-name-sync-configuration"
updated: 2026-07-20T15:29:56Z
published: 2026-07-20T15:29:56Z
canonical: "kb.expedient.com/microsoft-entra-id-group-name-sync-configuration"
---

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

# Microsoft Entra ID Group Name Sync Configuration

## Solution Overview

This guide provides the necessary steps to configure Entra ID to return group names. The configuration requires modifying token claims, updating the application manifest, assigning groups explicitly, and coordinating with the Expedient AI CTRL Team.

**Critical Requirement:** The `cloud_displayname` property only functions when `groupMembershipClaims` is set exactly to `ApplicationGroup`. Including other values (such as `SecurityGroup` or `All`) will break the configuration and revert the sync back to GUIDs.

## Operational Behaviors and Limitations
### Strict Group Synchronization
When OAuth group management is enabled on the backend, a user's group memberships in Open WebUI are strictly synchronized with the groups received in their OAuth claims upon each login.

- Users will be added to Open WebUI groups that match their OAuth claims.
- Users will be removed from any Open WebUI groups, including those manually assigned within the Open WebUI local database, if those groups are not present in their OAuth claims for that specific login session. Entra ID acts as the absolute source of truth.
### Open WebUI Administrators

**Critical:** Accounts designated as administrators within Open WebUI bypass OAuth group synchronization entirely. Administrator group memberships will *not* update via Entra ID claims. Any group assignments or removals for admin accounts must be executed manually within the Open WebUI interface. 

---

## Configuration Steps

### Step 1: Add Token Claims

Configure the App Registration to include groups in the authentication tokens.

1. Navigate to the **Microsoft Entra admin center** \> **App registrations**.
2. Select the target AI CTRL application.
3. Go to **Token configuration** in the left menu, then click **Add groups claim**.
4. Select **Security groups**.
5. Under **Customize token properties by type**, enable groups for both **ID** and **Access tokens**.
6. Click **Add**.

### Optional: Hybrid AD Groups (On-Premises Active Directory)

If security groups are synced from an on-premises Active Directory to Entra ID, the `cloud_displayname` configuration will fail for those specific groups, resulting in GUIDs.

**Resolution: Use sAMAccountName**

1. Navigate to the App Registration \> **Token configuration**.
2. Edit the existing groups claim.
3. Under the **ID token** section, change the group identifier format to **sAMAccountName**.
4. Click **Save**. This ensures the on-premises AD name attribute is utilized instead of the cloud display name.

### Step 2: Modify Application Manifest

Enable group names by injecting `cloud_displayname` into the manifest.

1. Go to **Manifest** within the App Registration.
2. Locate the `optionalClaims` section and add `cloud_displayname` to the `additionalProperties` array.

```json
"optionalClaims": {
    "idToken": [
        {
            "name": "groups",
            "source": null,
            "essential": false,
            "additionalProperties": ["cloud_displayname"]
        }
    ],
    "accessToken": [
        {
            "name": "groups",
            "source": null,
            "essential": false,
            "additionalProperties": ["cloud_displayname"]
        }
    ]
}
```

1. Locate `groupMembershipClaims` and set it strictly to `ApplicationGroup`:

```json
"groupMembershipClaims": "ApplicationGroup"
```

*Warning: Do not use *`SecurityGroup` or `All`.

1. Click **Save**.

### Step 3: Assign Groups to Enterprise Application

Because the manifest now uses `ApplicationGroup`, only explicitly assigned groups will be returned in the tokens.

1. Navigate to **Microsoft Entra admin center** \> **Enterprise applications**.
2. Select the target AI CTRL application.
3. Go to **Users and groups** \> **Add user/group**.
4. Select the specific security groups required for synchronization.
5. Click **Assign**.

### Step 4: Configure API Permissions

Ensure the App Registration possesses the correct Microsoft Graph permissions.

1. In the App Registration, navigate to **API permissions** \> **Add a permission**.
2. Select **Microsoft Graph** \> **Delegated permissions**.
3. Add the following permissions from the OpenID section: `openid`, `email`, `profile`.
4. Click **Grant admin consent**.

### Step 5: Coordinate with Expedient AI CTRL Team

Expedient handles the backend environment variable configurations required to execute the group sync.

- **For initial SSO configurations:** Provide the Application/Client ID, Directory/Tenant ID, and Client Secret Value to Expedient in the original delivery ticket.
- **For post-SSO group sync enablement:** Update the existing support ticket confirming the Entra App changes are complete. Specify whether Hybrid AD is being used.

Expedient will apply the required backend changes to enable group sync in the interface.

---

## Testing and Verification

Once the Expedient AI CTRL Team confirms backend configuration is complete, validate the setup:

1. **Test Authentication:** Log in using a standard user account. Do not use an admin account to verify group synchronization, as admin logic bypasses this routine entirely.
2. **Verify UI:** Confirm readable group names populate correctly within the application Admin Panel.
3. **Assign Permissions** to Groups in Open WebUI under the Admin Panel User tab.