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

# Group mappings

> Map your identity provider's groups to Aperium roles so users get the right role automatically when they sign in.

**Group mappings** are the bridge between your identity provider (Okta, Microsoft Entra / Azure AD, Google Workspace, etc.) and Aperium's roles. Each mapping ties one **IdP group name** to one **Aperium role**. When a user signs in, every IdP group on their token that has a mapping grants them the corresponding role for this tenant — no per-user provisioning required.

You'll find this under **Settings › Workspace › Access**, on the **Group mappings** tab.

<Note>
  Group mappings grant **roles**, not membership in [permission groups](/admins/access-control/groups). The two are separate systems. IdP groups are a read-only snapshot Aperium reads from the sign-in token; they are never merged into your native Aperium permission groups. Permission-group membership stays native and is managed by hand.
</Note>

## How a mapping resolves

<Steps>
  <Step title="A user signs in through SSO">
    Their identity token carries the list of IdP groups they belong to.
  </Step>

  <Step title="Aperium matches each group against this tenant's mappings">
    For every IdP group name that has a mapping, the user picks up the mapped role.
  </Step>

  <Step title="Roles combine additively">
    A user can hold several roles from several groups. Access is the union of what those roles grant — there is no deny rule. See [Roles](/admins/access-control/roles) for what each role can do.
  </Step>
</Steps>

This replaced Aperium's earlier hardcoded admin-group setting: instead of a single fixed group name granting admin, each tenant now defines its own mappings.

## Creating a mapping

Click **Add mapping** to open the dialog:

* **IdP group name** — the exact group name as your identity provider spells it (for example `aperium-admins`). Casing matters; it must match the token. If Aperium has recently seen group names on your members' tokens, they're offered as autocomplete suggestions in their exact casing.
* **Aperium role** — the role that group should grant. Choose from the system roles (**Super Admin**, **Tenant Admin**, **Member**).

The mappings table lists each IdP group name alongside the role it grants, with a **Delete** action per row.

<Warning>
  Deleting a mapping takes effect with no confirmation step. Members keep their current session, but the role stops being granted from that group the next time the mapping is evaluated at sign-in.
</Warning>

## Who can manage mappings

The tab is available to admins with the group-mapping capability (**Tenant Admin** and **Super Admin**). A **Tenant Admin** manages mappings for their own tenant only. A **Super Admin** can switch which tenant they're editing using the tenant picker in the tab's toolbar.

<Info>
  Verify before relying on it for a security decision: group mappings are evaluated from the IdP groups present on the sign-in token, so a change in your identity provider only reaches Aperium the next time the user authenticates.
</Info>