---
title: "Mapping groups to roles"
description: "Map identity provider groups to Overlane roles, pick the highest role a group can grant, and see how a person in several groups gets one role."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Mapping groups to roles

A mapping says which role a directory group grants. The mapping set lives with the team, is edited in Enterprise settings (`overlane.app/<workspace>/settings/enterprise/`) or through the API, and is applied at each directory sync.

```json
{
  "cap": "admin",
  "mappings": [
    { "groupName": "Engineering", "role": "member" },
    { "groupName": "Platform", "role": "admin" },
    { "groupName": "Readers", "role": "viewer" }
  ]
}
```

Send it with `PUT /v1/tenants/{tenantId}/enterprise/identity/group-mappings`, or run the same thing from the CLI. The request is accepted from an agent token for the team.

```sh
overlane enterprise sso groups set --map Engineering=member --map Platform=admin --map Readers=viewer --cap admin
overlane enterprise sso show
```

## The rules

- **One role per person.** A person in several mapped groups gets the highest role among them. A person in no mapped group keeps the role they have.
- **A cap on what groups can grant.** `cap` is `admin`, `member` or `viewer`. A mapping above the cap is refused when you save it, with the group named, and is clamped if it ever reaches a sync.
- **No owner from a group.** The owner role is not an option in a mapping, and a sync never changes an existing owner. Changing who owns the team stays a deliberate change that is recorded in the audit log.
- **Group names match without regard to case.** Each group may be listed once.

Roles from groups follow the same rule as every other grant of access: the result is the intersection of what the mapping allows and what the cap allows, never more.

## Checking the result

```sh
overlane enterprise sso sync
```

The report counts the role changes it made. Each sync is in the [audit log](/enterprise/audit-and-siem/) as a directory sync, and saving the mappings is recorded as a group mapping update.

Source: https://docs.overlane.app/enterprise/group-roles/index.mdx