Skip to main content

Groups from Microsoft Entra ID

Users who sign in through Microsoft Entra ID bring their Entra groups with them. BasePeak.AI can turn those into groups, roles and agent access, so you do not maintain the same structure twice. For example, a user in the Entra group "Department 10" joins the BasePeak.AI group "Department 10" automatically, gets its roles and sees the agents shared with it.

How it works​

  1. At sign-in, Entra ID sends the user's groups in the token's groups claim. An active session renews the token about once an hour and gets the current groups with it.
  2. BasePeak.AI stores these values on the user. You can see them on the user detail page under Advanced Details → OAuth Claim Groups.
  3. Auto-assignment rules on a BasePeak.AI group decide which values lead into that group (see Groups).
  4. A group can hold roles and be given access to agents. Its members get both.

When a user leaves a group in Entra, BasePeak.AI removes the automatic membership once the token carries the change (see Notes). Members added by hand are not affected.

1. Set up the groups claim in Entra​

Entra only sends groups once the app registration asks for them:

  1. In the Entra admin center, open the app registration BasePeak.AI uses for sign-in.
  2. Choose Token configuration → Add groups claim.
  3. Pick the group types, usually Security groups, or Groups assigned to the application (see Many groups).
  4. Choose how groups appear in the ID token:
    • Group ID (default): Entra sends the groups' object IDs, e.g. 6f1c2c3e-…. This always works.
    • sAMAccountName: only for groups synchronized from an on-premises Active Directory.
    • Cloud-only group display names: for groups that exist only in Entra, when you chose Groups assigned to the application.

There is nothing else to set in BasePeak.AI for Entra ID. Auth Providers → … → Group sync shows the same note.

Group IDs are not a problem

You never have to type an ID. Once users have signed in, the rule dialog offers the values it has seen, with the number of users per value. To match an ID to a group name, look the group up under Groups in the Entra admin center.

2. Sign in once​

Sign in with a test user who is a member of the Entra groups you want to use. Then check that OAuth Claim Groups appear on their user detail page under Advanced Details. If the list is empty, Entra is not sending a groups claim yet. Go back to step 1.

3. Create the group and an auto-assignment rule​

  1. Under Groups, create a group, e.g. dept-10 with display name "Department 10".
  2. In the group, click Add Rule.
  3. Under Auth Provider, select your Entra instance.
  4. Under Seen at login, click the Entra group's value. It appears as a selected value below Values. A rule matches if any of its values matches.
  5. Click Create.

The rule applies within about a minute, at each signed-in user's next action, without signing in again.

4. Attach roles and agent access to the group​

  • Roles: on the group detail page, under Assigned Roles, click Assign Role. All members get the role's permissions.
  • Agents: in the agent editor, under Access Control, add the group via Publish (see Agents).

The role's detail page under Roles shows who holds the role through which group.

Many groups per user​

An Entra ID token has room for at most 200 groups. For a user in more groups, Entra leaves out the groups claim and points to Microsoft Graph instead ("group overage"). BasePeak.AI does ask Microsoft Graph for these groups at sign-in, but does not keep them current: after the hourly token renewal they are missing again, and memberships stay as they were at sign-in. Graph also always returns group IDs, including nested groups.

In that case, choose Groups assigned to the application in step 1, and assign only the groups BasePeak.AI needs to the enterprise application. The token then carries only those groups. Assigning groups to an application requires Entra ID P1 or P2.

Notes​

  • When do changes apply? BasePeak.AI reconciles memberships against the groups in the user's token on every action of a signed-in user. New or deleted rules therefore apply within about a minute. A change in Entra applies once the session renews its token, so within about an hour or at the next sign-in.
  • Users without groups: when a user loses all their groups in Entra, Entra stops sending a groups claim, and their existing automatic memberships stay in place, as do the OAuth Claim Groups shown and the counts under Seen at login. Remove them from those groups by hand. Note that a user removed by hand is not added to that group automatically again until you add them by hand once.
  • Rule values are compared case-insensitively.
  • A rule set to All Providers applies to every sign-in, including other providers. That is harmless for Entra group IDs. For names like admins, select the Entra instance instead.