Map Entra ID groups to business functions

An organisation that has already invested in an identity provider has, almost by definition, already decided who belongs to which team, department, and cost centre. That structure lives in directory groups (eng-platform, data-science-emea, finance-analytics, and the rest), maintained continuously by the identity team as people join, move, and leave. This guide describes how Microsoft Entra ID (formerly Azure Active Directory) groups are surfaced to Agent Router Enterprise (the platform) and mapped to platform roles and business functions, so that a developer's membership in an Entra ID group is what decides their role, the rate limits they are subject to, and the budget their consumption draws down. When the directory changes, the platform changes with it on the next sign-in, without an operator touching the Admin Dashboard. This guide builds directly on the single sign-on (SSO) role-mapping material and assumes that material has been read first.

---

Persona: Platform operator working in the Admin Dashboard, in close coordination with the identity team that owns the Microsoft Entra ID tenant.

Estimated time: 30--60 minutes, most of which is spent coordinating the group-claim configuration with the identity team rather than working in the Admin Dashboard.

When this guide applies

This guide is the right starting point in any of these situations:

Situation	What it covers
Access decisions should follow existing Entra ID groups rather than manual role edits	Emitting group claims and mapping them to roles
Rate limits and budgets should be scoped to teams or departments	Driving group-scoped limits from directory membership
Manual role assignment has become unmanageable as the user base has grown	Replacing per-user edits with claim-driven mapping
A reorganisation has changed team membership in the directory	How membership changes propagate on the next sign-in

This guide is a continuation of the SSO setup. The protocol must already be configured and enabled before group claims can be read; see Configure single sign-on. The mechanics of translating a claim into an Agent Router role are documented in the SSO role mapping guide; the two should be read together, and this guide assumes familiarity with both.

Outcomes

By the end of this guide:

• Microsoft Entra ID has been configured to emit a group claim in the SSO assertion or token.
• The group claim is read by the platform and its values are confirmed.
• Each relevant Entra ID group is mapped to a platform role, a business function, or both.
• Group membership is used to scope rate limits and budgets, so that consumption is governed at the team or department level rather than per user.
• The behaviour on each sign-in, and on a change to a user's group membership, is understood.

Prerequisites

• Administrator access to the Admin Dashboard, typically the super_admin role.
• SSO already configured and enabled against the Microsoft Entra ID tenant. See Configure single sign-on.
• Familiarity with claim-driven role assignment as described in the SSO role mapping guide.
• Cooperation from the identity team that owns the Entra ID tenant. The group-claim configuration is performed on the Entra ID side, and the set of groups and their identifiers comes from that team.
• A decision, made jointly with the identity team, about which directory groups correspond to the business functions the platform needs to recognise. Mapping every group in a large tenant is rarely useful; mapping the handful that correspond to real access and budgeting boundaries is.

Step 1: decide which groups represent business functions

Before any configuration is touched, the set of groups that matter has to be agreed. A large Entra ID tenant contains hundreds of groups, most of which have nothing to do with platform access. The groups worth mapping are the ones that correspond to a real boundary: a team that should hold a particular role, a department whose spend is tracked separately, or a cost centre that owns a budget.

A working approach:

1. List the business functions the platform needs to distinguish: for example, platform engineering, data science, and a finance analytics team.
2. For each, identify the existing Entra ID group that already represents it. The identity team owns this mapping and can confirm which group is authoritative when more than one looks plausible.
3. Record the group identifier that will appear in the claim. Depending on how the claim is configured, this may be the group's display name or its object ID (a GUID). The object ID is stable across renames and is the safer choice where the platform can match on it.
4. Note, for each group, the intended platform role and the business function it represents. This table becomes the mapping configured in later steps.

Keeping the mapped set small and deliberate matters here. Every mapped group is a rule that has to be maintained; unmapped groups have no effect on the platform.

Step 2: configure Microsoft Entra ID to emit a group claim

Entra ID does not include group information in the SSO assertion or token by default. The identity team configures the application registration, the one created when SSO was set up, to add a group claim. This is performed entirely on the Entra ID side; the platform only consumes the result.

The configuration on the Entra ID application registration determines:

1. That a groups claim is emitted at all.
2. Which groups are included: typically all groups assigned to the application, or all security groups, depending on tenant policy. Restricting the claim to groups assigned to the application keeps the claim small and avoids the token-size limits that large tenants run into when every group is emitted.
3. What value identifies each group in the claim: the group object ID (a GUID) or, where the directory is configured to emit them, the group display names. The object ID is recommended because it does not change when a group is renamed.

For a token that emits group object IDs, the relevant portion of the decoded claim set looks roughly like this:

{
  "groups": [
    "8f4e1c20-1d3a-4b9e-9b2a-3c7d5e6f1a90",
    "b1c2d3e4-5f60-4a1b-8c9d-0e1f2a3b4c5d"
  ]
}

For a deployment configured to emit display names instead, the same claim carries readable values:

{
  "groups": [
    "eng-platform",
    "finance-analytics"
  ]
}

The exact claim name and shape depend on how the identity team configures the application registration and on whether SAML or OIDC is in use. The name of the claim is one of the values that has to be confirmed jointly; the platform needs to know which claim to read, and that is settled in the next step. Large tenants should also confirm the identity team's handling of the group overage case: when a user belongs to more groups than the token can carry, Entra ID emits a reference to be resolved against the directory rather than the group list itself, and the deployment has to account for that behaviour.

Step 3: confirm the platform is reading the group claim

With Entra ID emitting the claim, the platform has to be pointed at it. The SSO role-mapping configuration in the Admin Dashboard is where the claim is named and its values are inspected; the full mechanics are in the SSO role mapping guide, and only the group-specific concerns are repeated here.

1. Sign in to the Admin Dashboard.
2. Open the SSO role-mapping configuration.
3. Identify the claim that carries the group values: the same claim name agreed with the identity team in the previous step.
4. Sign in once as a test user who belongs to one of the mapped groups, and confirm that the expected group values appear in the assertion or token the platform receives. The testing surface described in Configure single sign-on exercises this path without disrupting other users.

Confirming the claim values before mapping them avoids the most common failure mode: a mapping rule written against a display name when the token actually carries object IDs, or against a claim name that the token does not contain. The values seen here are the values the mapping rules must match exactly.

Step 4: map each group to a role and a business function

With the group values confirmed, each mapped group is associated with a platform role, a business function, or both. The role governs what members of the group can do; the business function is the label that subsequent rate-limit and budget scoping is built on.

For each group identified in Step 1:

1. Add a mapping rule that matches the group's claim value: its object ID or display name, matching exactly what Step 3 confirmed.
2. Assign the platform role that members of the group should hold. The role model is the same one used throughout the Admin Dashboard: for example, user for developers who consume the platform, or one of the administrative roles for an operations team. The full role list is in Onboard developers and issue keys.
3. Record the business function the group represents, so that rate limits and budgets can later be scoped to it.

Where a user belongs to more than one mapped group, the precedence rules in the SSO role mapping guide decide which role wins. This case is worth designing for deliberately: a developer who is also a member of an administrative group should resolve to the role the deployment actually intends, not to whichever rule happens to be evaluated first.

The result of this step is that a developer's role is no longer set by hand. It is computed from their directory membership on every sign-in, and the directory becomes the source of truth.

Step 5: scope rate limits and budgets to the mapped groups

Once group membership drives role assignment, the same membership can govern consumption. The point of mapping groups to business functions is that limits and budgets are then maintained against the organisation's structure rather than against an ever-changing list of individual users.

• Rate limits. A rate limit scoped to a business function applies to every member of the corresponding group collectively, rather than to each developer in isolation. A data-science team with a shared throughput ceiling is governed as one unit; adding a developer to the directory group brings them under the existing ceiling automatically, with no separate limit to create.
• Budgets. A budget scoped to a group draws down against the combined spend of its members, which is what makes department- or cost-centre-level budgeting tractable. The budget is attached to the business function once; membership changes in the directory move spend in and out of it without further configuration. The mechanics of defining and attaching budgets, including group-scoped budgets, are in Working with budgets.

The advantage of scoping at the group level is the same advantage that motivates the whole guide: there is one rule per business function, not one per person. A reorganisation that moves a team between departments is handled by the identity team in the directory, and the platform's limits and budgets follow.

Step 6: understand how the mapping is applied on each sign-in

The mapping is not a one-time import. It is re-evaluated every time a user authenticates, which is what keeps the platform aligned with the directory.

On each sign-in:

1. The user authenticates at Microsoft Entra ID.
2. Entra ID returns the assertion or token, including the group claim configured in Step 2.
3. The platform reads the group claim and evaluates it against the mapping rules from Step 4.
4. The user's role is set to the result, overwriting whatever role was previously recorded for them.
5. The business-function association is refreshed, so the rate limits and budgets the user is subject to reflect their current group membership.

Because the role is recomputed on every login, a manual role edit in the Admin Dashboard does not survive the user's next sign-in for any user covered by the mapping. This is the same precedence rule documented in Onboard developers and issue keys and the SSO role mapping guide: for mapped users, the directory wins. Manual edits remain appropriate only for users no mapping rule covers.

When a user's group membership changes (they join a team, move departments, or leave), the change takes effect on their next sign-in, not instantly. Adding a user to a mapped group grants the associated role and brings them under the group's rate limits and budgets the next time they authenticate. Removing them has the mirror effect: the role falls back to whatever the remaining rules resolve to, or to the default role if no mapped group applies. A membership change made in the directory while a user holds an active session does not interrupt that session; it is applied the next time the session is re-established. Deployments that need a removal to take effect immediately, an offboarding, say, should treat the directory change as necessary but not sufficient, and follow the credential-revocation steps in Onboard developers and issue keys.

What to do next

• Working with budgets. Attach group-scoped spending limits to the business functions mapped in this guide. See Working with budgets.
• Onboard developers and issue keys. The role model, the precedence rules, and the credential-revocation steps that complement directory-driven role assignment. See Onboard developers and issue keys.
• SSO role mapping. The underlying claim-to-role mechanism that this guide builds on, including the multi-group precedence rules. See the SSO role mapping guide.

---

Where to go next

Onboard developers and issue keys

The role model, precedence rules, and credential revocation that complement directory-driven roles.

Configure single sign-on

The SSO setup that must be in place before group claims can be read.