# Map identity provider groups to IAM groups

Keep people's IAM groups in step with their groups at your identity provider, updated at every single sign-on.

Replace _engineering_ with a group name as your identity provider sends it, and _developers_ with
an IAM group of your organization.

## Prerequisites

- Permission for `iam:UpdateSsoConnection`. In the console also `iam:ListSsoConnections` to open
  the **Single sign-on** page, `iam:GetSsoConnection` to load the current mappings (without it the
  list shows empty and **Save groups** refuses to save) and `iam:ListGroups` to pick IAM
  groups.
- The IAM group exists and is not managed by SCIM (see [Create a group](create-a-group.md)).
- Your identity provider sends the person's groups in the ID token (OIDC) or as an attribute
  (SAML), as a list of strings or one string.

## Map the groups

**Console**
1. Open **IAM**, then choose **Single sign-on**.
2. On the connection's card, under **Groups**, check **Groups claim / attribute**. It is `groups`
   unless you change it.
3. Choose **Add mapping**.
4. For **IdP group**, enter engineering; for **IAM group**, choose developers.
5. Choose **Save groups**. The console says `Saved. It applies from each person’s next sign-in.`

**CLI**
```sh
dcloud iam sso-connections update connection-id --groups-claim groups
dcloud iam sso-connections set-group-mappings connection-id \
  --mappings '[{"idpGroup":"engineering","iamGroupId":"5c2e8a41-7b3d-4f6e-9a1c-2d4b6e8f0a13"}]'
```

**API**
```http
PUT /iam/api/sso-connections/connection-id/group-mappings
{ "mappings": [ { "idpGroup": "engineering", "iamGroupId": "5c2e8a41-7b3d-4f6e-9a1c-2d4b6e8f0a13" } ] }
```

The list replaces every mapping of the connection; an empty list removes them all. Change the claim
with `PATCH /iam/api/sso-connections/{id}` and `groupsClaim`.

**Terraform**
```hcl
resource "dcloud_iam_sso_connection" "okta" {
  # …
  groups_claim = "groups"
  group_mappings = jsonencode([
    { idpGroup = "engineering", iamGroupId = dcloud_iam_group.developers.id },
  ])
}
```

## Result

At every sign-in through the connection, the person's membership in each mapped IAM group is set to
what the identity provider says:

- they are added to the groups their identity provider groups map to;
- they are removed from mapped groups that this connection added them to and they no longer
  qualify for.

Memberships an administrator added by hand, and groups nobody mapped, are never changed. A leading
`/` (Keycloak's group paths) is ignored on both sides. If the identity provider sends no groups
claim at all, nothing changes; an empty list is applied. Each change is in the audit log as
`auth:SsoGroupSync`, with the groups added and removed.

## If it is refused

- 400 `Not a group of this organization, or one SCIM manages: …`
- At most 200 mappings per connection.

## Related

- [Single sign-on](single-sign-on.md) · [Provision users with SCIM](provision-users-with-scim.md)
- `iam.sso-connections.set-group-mappings` · `dcloud iam sso-connections set-group-mappings` · `dcloud_iam_sso_connection`
