---
title: "Microsoft Entra ID Group Name Sync"
slug: "microsoft-entra-id-group-name-sync"
updated: 2026-08-14T20:16:48Z
published: 2026-08-14T20:16:48Z
canonical: "kb.expedient.com/microsoft-entra-id-group-name-sync"
---

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

## Microsoft Entra ID Group Name Sync

By default, group memberships arrive from Entra ID as GUIDs — long strings of characters that mean nothing to whoever is assigning permissions in AI CTRL. This guide configures Entra to send readable group **names** instead.

It's for the team that manages your Entra tenant, and it assumes single sign-on is already working. If you haven't set that up yet, start with [Microsoft Entra ID Configuration for SSO](https://kb.expedient.com/docs/microsoft-entra-id-configuration-for-sso).

> **One setting decides whether this works.** The `cloud_displayname` property only functions when `groupMembershipClaims` is set to exactly **`ApplicationGroup`**. Any other value — including `SecurityGroup` or `All` — breaks the configuration and reverts group names to GUIDs.

## Before you start: how group sync behaves

Two behaviors surprise people. Both are worth knowing before you turn this on.

**Entra ID is the absolute source of truth, on every login.** When OAuth group management is enabled, a user's AI CTRL group memberships are synchronized with their OAuth claims each time they sign in. They're added to groups matching their claims — and **removed from any group not present in those claims**, including groups assigned manually inside AI CTRL. Manual group assignments won't survive the user's next login.

**Administrators bypass group sync entirely.** Accounts designated as administrators in AI CTRL don't have their group memberships updated by Entra claims at all. Any group assignment or removal for an admin account has to be done manually in the AI CTRL interface.

## Step 1 · Add the groups claim

This creates the claim structure. The next step narrows what it contains.

1. Go to the **Microsoft Entra admin center → App registrations**
2. Select your AI CTRL application
3. Open **Token configuration**, 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**

> **You'll change this scope in Step 2.** Selecting *Security groups* here sets `groupMembershipClaims` to `SecurityGroup`, which is not the value this configuration needs. The manifest edit in Step 2 overrides it. Don't stop after this step.

### If your groups sync from on-premises Active Directory

Security groups synced from an on-premises AD won't work with `cloud_displayname` — those groups still come through as GUIDs. Use the on-premises name attribute instead:

1. Go to **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**

## Step 2 · Edit the application manifest

Two changes here. Both are required.

Go to **Manifest** within the App registration.

**First**, find the `optionalClaims` section and add `cloud_displayname` to the `additionalProperties` array for both token types:

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

**Second**, find `groupMembershipClaims` and set it to exactly:

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

Click **Save**.

## Step 3 · Assign groups to the enterprise application

Because the manifest now uses `ApplicationGroup`, **only groups explicitly assigned to the application appear in tokens**. Groups a user belongs to but which aren't assigned here won't sync.

1. Go to **Microsoft Entra admin center → Enterprise applications**
2. Select your AI CTRL application
3. Go to **Users and groups → Add user/group**
4. Select the security groups you want synchronized
5. Click **Assign**

## Step 4 · Confirm API permissions

1. In the App registration, go to **API permissions → Add a permission**
2. Select **Microsoft Graph → Delegated permissions**
3. From the OpenID section, add `openid`, `email`, and `profile`
4. Click **Grant admin consent**

## Step 5 · Tell Expedient

Expedient applies the backend configuration that enables group sync. Nothing happens until that's done.

| Your situation | What to send |
| --- | --- |
| Setting up SSO for the first time | Application (client) ID, Directory (tenant) ID, and Client Secret value — in your original delivery ticket |
| Enabling group sync on existing SSO | An update to your existing support ticket confirming the Entra changes are complete. **Say whether you're using Hybrid AD.** |

## Testing

Once Expedient confirms the backend configuration is in place:

1. **Sign in with a standard user account.** Don't test with an admin account — admin logic bypasses group sync entirely, so an admin login proves nothing.
2. **Check the Admin Panel** and confirm readable group names appear.
3. **Assign permissions** to those groups under the Admin Panel's Users tab.

## If group names still show as GUIDs

- **Check `groupMembershipClaims` is exactly `ApplicationGroup`** — not `SecurityGroup`, not `All`. This is the most common cause.
- **Check the groups are assigned** to the enterprise application in Step 3. Unassigned groups don't appear at all.
- **Check whether the groups come from on-premises AD.** If so, switch the ID token's group identifier format to sAMAccountName.
- **Check you're not testing as an admin.**

## Related articles

- [Microsoft Entra ID Configuration for SSO](https://kb.expedient.com/docs/microsoft-entra-id-configuration-for-sso)
- [Okta OIDC Configuration for SSO](https://kb.expedient.com/docs/okta-oidc-configuration-for-sso)
- [Duo OIDC Configuration for SSO](https://kb.expedient.com/docs/duo-oidc-configuration-for-sso)