Configuring SSO - mapping roles and groups

Agent Router assigns its own roles automatically from the claims returned by any OIDC identity provider. Once the mapping is in place, a directory change propagates to Agent Router on the next login, with no manual work in the Admin Dashboard.

---

Mapping OIDC roles and groups to Agent Router roles

Most organisations already model who-can-do-what in their identity provider, and duplicating that model inside Agent Router quickly becomes a maintenance burden. This guide describes how Agent Router is configured to assign its own roles automatically, driven by the claims returned by any OpenID Connect compliant (OIDC) identity provider. Once the mapping is in place, an administrator added to a group in the directory shows up as an administrator in Agent Router on their next login, with no manual intervention in the Admin Dashboard.

The same configuration shape works for Microsoft Entra ID, Okta, Auth0, Keycloak, and any other OIDC provider. The pattern is consistent: a claim that carries role or group values is selected, and the values inside that claim are mapped to Agent Router roles.

note

This guide uses Microsoft Entra in its examples, but the overall process is the same for every identity provider. Only the location of settings and the exact claim names tend to differ between vendors.

The Entra examples below use app roles because they produce stable, readable values in the roles claim: values such as tare-billing-admin are easy to recognise during audits and easy to map. If group claims are used instead, the same Agent Router mapping fields apply to the groups claim with no change to the platform side.

For Entra, the recommended setup is app roles assigned to users or groups. Direct group-claim mapping also works when Entra reliably emits the groups claim, but it usually exposes raw group object IDs and can hit group-overage limits, both of which tend to make day-two operations harder than they need to be.

Outcomes

By the end of this guide:

• App roles (or groups) are defined and assigned in the identity provider.
• Agent Router is configured with a role-claim path and a value-to-role mapping.
• Verified users receive the correct Agent Router role on every login, with no per-user action required inside Agent Router itself.

Plan for 15--30 minutes for the configuration itself, plus a few minutes for Entra to propagate the new app role assignments to test users. In larger tenants, propagation may take noticeably longer.

In this guide

• Identity Provider (IdP) configuration - define app roles or groups and confirm they appear in OIDC claims
  • Step 1: Create app roles in your IdP
  • Step 2: Assign roles to users or groups
• Agent Router configuration - map IdP claim values to Agent Router roles
  • Step 3: Configure the SSO provider with role mapping
• Verify - confirm the mapping works end-to-end
  • Step 4: Verify the mapping

Optional:

• Appendix A: Control who can log in with Assignment required
• Appendix B: Role mapping precedence and defaults
• Appendix C: App roles vs group claims

How it works

When a user signs in through the OIDC identity provider, the provider returns a set of claims describing that user (name, email, group memberships, assigned application roles, and so on). Agent Router inspects the configured claim path, looks up each value found there in the configured mapping table, and applies the matching Agent Router role to the user record. This evaluation runs on every login, not just the first, so the directory always remains the source of truth.

[OIDC] token/userinfo: { "roles": ["tare-billing-admin"] }
                                  ↓
roleClaimPath: "roles"
roleMapping: { "tare-billing-admin": "billing_admin" }
                                  ↓
[Agent Router] user.role = "billing_admin"

From Agent Router's perspective, app roles and group claims are interchangeable: both arrive as arrays of string values inside a named claim, and both are consumed through the same two configuration fields.

Field	What it does	Example
roleClaimPath	Dot-notation path to the claim to read	roles, groups, resource_access.tars.roles
roleMapping	Maps each IdP claim value to an Agent Router role	{ "tare-admin": "super_admin" }

A typical app role configuration looks like this:

{
  "roleClaimPath": "roles",
  "roleMapping": {
    "tare-admin": "super_admin",
    "tare-user": "user"
  }
}

A group claim configuration uses the same structure, with group identifiers in place of role strings:

{
  "roleClaimPath": "groups",
  "roleMapping": {
    "00000000-0000-0000-0000-000000000000": "super_admin",
    "11111111-1111-1111-1111-111111111111": "user"
  }
}

note

Entra's /userinfo endpoint sometimes serializes claims such as roles as a JSON-stringified array ('["tare-billing-admin"]') instead of a native array. This is a known quirk of the Microsoft Graph response shape. Agent Router handles both formats transparently: no special configuration is needed, and the same roleClaimPath value works in either case.

Prerequisites

• An OIDC application already configured for Agent Router corporate SSO login. For Entra, this is an App registration created during initial SSO setup.
• Permission to configure claims and assignments in the identity provider. For Entra, the Owner or Application Administrator role in the tenant is required; lesser roles cannot edit app roles or manage user assignments.
• Access to the Agent Router admin dashboard with the super_admin role, which is required to view and edit SSO provider configuration.

Step 1: create app roles in IdP

App roles are the building blocks of the mapping. Each role defined here corresponds to an entry that will eventually appear in the roles claim and, through the mapping, to a specific Agent Router role.

info

App roles are defined on the App registration, not the Enterprise application. The two blades are linked but distinct: App registration owns the application's identity and capabilities, while Enterprise application owns the user-facing assignment surface.

This example is based on Microsoft Entra. Comparable steps exist for every OIDC provider; the navigation differs, but the underlying objects are the same.

1. Go to Azure Portal → App registrations and open the Agent Router app.

2. In the left sidebar, click App roles.

3. Click + Create app role.

4. Fill in the fields:

   Field	Value
   Display name	A human-readable label (for example, Agent Router Billing Admin)
   Allowed member types	Users/Groups
   Value	The string Agent Router will see in the token (for example, tare-billing-admin)
   Description	Brief description for admins
   Do you want to enable this app role?	Checked

5. Click Apply.

6. Repeat for each required role.

The Value field is the one that matters, because it is the exact string that Entra emits in the roles claim and that Agent Router will look up in its mapping. Display names are for humans browsing the Entra UI; values are for machines.

tip

Use a consistent naming prefix such as tare- (for example tare-model-admin, tare-billing-admin) to make role assignments easy to filter and audit in Entra. A prefix also helps avoid collisions when the same tenant hosts multiple applications with their own role schemes.

Available Agent Router roles

The mapping target on the Agent Router side is always one of the roles listed below. The role determines which areas of the Console and Admin Dashboard the user can access, and which actions the API will accept on their behalf.

Agent Router role	Typical use
super_admin	Full platform administration
model_admin	Manage model routes and backends
provider_admin	Manage upstream AI providers
mcp_admin	Manage MCP profiles and routing
user_admin	Manage users and org membership
billing_admin	View and manage billing and usage
user	Default: standard access, no admin permissions

Most deployments only need two or three of these roles. A common starting point is super_admin for the platform owners, one or two functional admin roles (such as model_admin or billing_admin) for delegated operators, and user for everyone else.

Step 2: assign roles to users or groups

Defining app roles is only half the picture; the roles must also be assigned to the principals (users or groups) who should receive them. Role assignments live on the Enterprise application, a separate blade from App registrations that controls who can use the app and what they appear as inside it.

Step 2.1: find the enterprise application

The App registration and the Enterprise application are two views of the same underlying object in Entra. The fastest way to jump from one to the other is through the App registration's overview page.

From inside the App registration:

1. Open the Agent Router app in App registrations → Overview.
2. In the Essentials section, click the Managed application in local directory link. This opens the matching Enterprise application directly, with the correct context preserved.

Step 2.2: assign a role to a user

A single assignment grants exactly one app role to one principal. Multiple assignments can be stacked for the same user when more than one role is required.

1. In the Enterprise application, click Users and groups in the left sidebar.
2. Click + Add user/group.
3. Under Users, click None Selected, search for the user, select them, and click Select.
4. Under Select a role, click None Selected, choose the app role created in Step 1 (for example, Agent Router Billing Admin), and click Select.
5. Click Assign.

The assignment becomes visible to Agent Router on the user's next sign-in. Existing sessions are not affected until the next token refresh or login.

tip

To assign the same role to multiple users at once, use a security group: add the group under Users and groups, assign the role to the group, and manage membership in the group itself. The roles claim is populated with roles assigned to the user directly and roles inherited through group membership, so the two approaches can be mixed without conflict.

note

A user can hold only one app role per assignment row. To grant multiple Agent Router roles to a user, add them more than once with a different role each time, or consider whether a single higher-privilege role (such as super_admin) covers the use case more cleanly. In practice, Agent Router applies the highest-privilege matching role, so stacking lower roles on top of a higher one offers little additional value.

Step 3: configure the SSO provider with role mapping

With the identity provider side in place, the remaining task is to tell Agent Router which claim to read and how to translate the values it finds there. This is done once per SSO provider configuration and applies to every user who signs in through it.

Step 3.1: required fields

Two fields drive the entire mapping. Both are edited together in the Admin Dashboard.

Field	Description
roleClaimPath	The claim path to read from the token or userinfo response. Use roles for Entra app roles, groups for OIDC group claims, or a nested path such as resource_access.tars.roles for providers like Keycloak.
roleMapping	A JSON object mapping IdP claim values to Agent Router role names.

Step 3.2: apply the configuration in Agent Router

1. Open the Agent Router admin dashboard.

2. Go to Settings → SSO.

3. Open the OIDC SSO provider configuration.

4. In the role mapping section, set Role claim path to the claim Agent Router should read. The correct value depends on the identity provider and the claim shape configured for the app:

   Source	Role claim path
   Entra app roles	roles
   Entra group claims	groups
   Okta groups claim	groups
   Keycloak client roles	resource_access.tars.roles

5. Add one mapping row for each IdP value that should grant an Agent Router role. Any value not listed here simply produces no admin role and falls through to the default user role:

   IdP claim value	Agent Router role
   tare-billing-admin	billing_admin
   tare-model-admin	model_admin
   tare-super-admin	super_admin

6. Save the SSO provider configuration.

The new mapping takes effect on the user's next login. There is no need to invalidate sessions or restart Agent Router; the configuration is read fresh on each authentication callback.

note

roleMapping keys must match the exact claim values emitted by the IdP, character for character and case for case. For Entra app roles, the app role Value strings set in Step 1 are what flows through the claim, not the display names shown in the portal. For Entra group claims, the group object IDs are emitted unless a provider-specific claim configuration that emits names has been added separately. Values on the right-hand side must be valid Agent Router role names from the table above; any mapping that points to an unrecognised role name is silently ignored, so misspellings can be a frustrating source of "why is my admin still a regular user?" tickets.

Step 3.3: provider examples

The same two-field pattern covers most realistic deployments. The differences between providers are largely about which claim is the natural fit and what shape its values take.

Provider pattern	Typical roleClaimPath	roleMapping keys
Entra app roles	roles	App role Value strings, such as tare-billing-admin
Entra group claims	groups	Group object IDs, only when Entra emits the groups claim for the user
Okta groups claim	groups	Group names or IDs, depending on the Okta claim configuration
Auth0 namespaced custom claim	https://example.com/roles	Role or group values emitted in the custom claim
Keycloak client roles	resource_access.tars.roles	Client role names

Step 4: verify the mapping

Before announcing the new SSO configuration to the broader user base, the mapping should be exercised end-to-end with at least one test user per Agent Router role. This catches both directory-side misconfiguration (missing assignments, wrong claim names) and mapping-side typos in a low-stakes setting.

Step 4.1: log in as a test user

Sign in via corporate SSO as a user assigned the expected IdP app role or group. After login completes, open Users in the Agent Router admin dashboard and confirm that the user's role matches the mapped Agent Router role.

For example, a user with the tare-billing-admin Entra app role should appear as billing_admin in Agent Router immediately after their first login under the new configuration.

Step 4.2: what to check if the role is wrong

The table below covers the issues that account for most "role not applied" support cases. Each one is straightforward to diagnose once the right place to look is known.

Symptom	Likely cause	Fix
User gets user role despite assignment	Role or group value mismatch between the IdP claim and Agent Router role mapping	Confirm the exact app role value or group object ID in the IdP and make the Agent Router mapping key match it exactly, including case.
roles or groups claim is absent from the token	Claim not configured, app role or group not assigned, or assignment not yet propagated	Confirm the IdP emits the claim for this application and that the user has the expected assignment. For Entra app roles, check Enterprise application → Users and groups. Allow ~1 minute for propagation.
Existing user's role did not change after adding mapping	User has a role from a previous login; the mapping applies on the next login	Have the user log out and log back in; the mapping is evaluated on every login.
Role reverts to user after next login	Mapping is applied on every login and overwrites the stored role	This is expected. Manage role changes via Entra assignments, not manual Agent Router edits.

Appendix a: control who can log in with assignment required

By default, any user in the Entra tenant can sign in to Agent Router via SSO. Users without an app role assignment land in the user role and have access to standard Console features but no administrative surface. For deployments where Agent Router should be visible only to an explicit allow-list, Entra's Assignment required setting locks the application down at the directory level, before any token ever reaches Agent Router.

To restrict access so that only assigned users can log in:

1. Open the Enterprise application for the Agent Router app.
2. Click Properties in the left sidebar.
3. Set Assignment required to Yes.
4. Click Save.

The combinations of Assignment required and role assignment produce the following outcomes:

Assignment required	User has a role assigned	Result
No	No	User can log in; roles claim is empty, falls through to default user role in Agent Router
No	Yes	User can log in; roles claim contains their role, mapped in Agent Router
Yes	No	Login blocked by Entra, user never reaches the Agent Router callback
Yes	Yes	User can log in; roles claim contains their role, mapped in Agent Router

When Assignment required is enabled, at least one app role must be assigned to every user or group that needs access. A user with no role assignment will be blocked at the Entra consent screen even if they have a corporate email in the allowed domain list, because Entra refuses to issue a token in the first place.

warning

Enable Assignment required only after confirming that all current users have an assignment. Flipping this on without checking will lock out existing users immediately, including platform administrators if their accounts are not explicitly assigned a role.

Appendix b: role mapping precedence and defaults

Agent Router does not consider the IdP claim mapping in isolation. Several signals can determine a user's role, and the platform evaluates them in a fixed order on every login. The first rule that produces a match wins, and later rules are not consulted.

Priority	Rule	When it applies
1	Admin email list: user's email is in adminEmails (SSO provider) or CORPORATE_ADMIN_EMAIL (env var)	Always checked first. Use this for emergency super-admin grants.
2	IdP claim mapping: roleClaimPath resolves to a value that matches a key in roleMapping	Applied when the email list does not match. Overwrites the stored role on every login.
3	Retain existing role: user already has a role in Agent Router from a previous login	Used when neither rule above matches.
4	First-user bootstrap: new user, no super_admin exists in Agent Router yet	One-time only; promotes the first user to super_admin for fresh deployments.
5	Default	New user with no matching rule gets user.

The most important consequence of this ordering is that rule 2 runs on every login and overwrites the stored role. Manual edits to a user's role in the Admin Dashboard are therefore not durable for any user whose role is also managed via claim mapping: the next login will revert the change. Once a user is brought under claim-driven management, their role should be changed exclusively through Entra assignments. For environments where some users are claim-managed and others are not, the cleanest approach is to omit the unmanaged users from roleMapping entirely so that rule 3 keeps their manually assigned role in place.

Appendix c: app roles vs group claims

Agent Router treats app roles and group claims identically once they are present in OIDC claims: roleClaimPath selects the claim, and roleMapping translates the values inside it to Agent Router roles. The difference is entirely on the identity provider side: in what the IdP emits, how stable those values are over time, and how easy they are to govern.

Entra app roles assigned to groups

For organisations that already use security groups to manage application access, Entra app roles still work without needing to flatten everything onto individual users. The group itself can be assigned the app role under Enterprise application → Users and groups, and every user who is a member of that group inherits the assignment. Entra populates the roles claim with every app role the user inherits through group memberships, plus any direct assignments, in one combined array.

The Agent Router-side configuration is unchanged:

{
  "roleClaimPath": "roles",
  "roleMapping": {
    "tare-billing-admin": "billing_admin",
    "tare-super-admin": "super_admin"
  }
}

This is usually the cleanest Entra setup for customer environments because app role values are readable, application-specific, and decoupled from the directory's broader group taxonomy. A rename of a security group does not break the mapping, and the value strings that appear in audit logs are immediately recognisable.

Entra group claims

In tenants that already manage application access purely through groups, and prefer not to introduce app roles at all, group claims provide a direct path. Agent Router maps group IDs to roles in exactly the same way, but two Entra-specific behaviours are worth being aware of before committing to this approach.

important

Entra group claims usually emit group object IDs, not display names. Map those IDs unless a provider-specific claim configuration that emits another stable value has been set up. Object IDs are opaque UUIDs, which makes the mapping table harder to read at a glance than the app role equivalent.

caution

If a user is a member of too many groups, Entra may omit the full groups list and emit a group-overage indicator instead of the actual values. Agent Router does not resolve group overage through Microsoft Graph, so users in this state will be treated as if they had no groups assigned for the application. Entra app roles assigned to groups avoid this entirely, because only the roles relevant to the application are ever emitted, and they are the recommended option for the most predictable customer setup.

When Entra is configured to emit a groups claim for the app, the mapping looks like this:

{
  "roleClaimPath": "groups",
  "roleMapping": {
    "00000000-0000-0000-0000-000000000000": "billing_admin",
    "11111111-1111-1111-1111-111111111111": "super_admin"
  }
}

The UUIDs above are placeholders. For Entra group mapping, the group's real Object ID is required, not its display name. The Object ID is found in Microsoft Entra ID → Groups → the group → Overview → Object ID, or with the Azure CLI:

az ad group show --group "<group-display-name>" --query id -o tsv

Group claims are a good fit when the identity provider already governs application access entirely through groups and reliably emits the relevant group values in OIDC claims. For Entra specifically, app roles assigned to groups are usually easier to operate over the long run: they avoid exposing broad directory group IDs directly to the application, sidestep Entra's group-overage behaviour, and produce mapping tables that an auditor can read without cross-referencing a group registry.

---

Where to go next

Configure SSO

The base SSO setup that role mapping builds on: connecting an OIDC identity provider.

Data plane installation

Bring up the data plane on AWS, Azure, or GCP.