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 alsoiam:ListSsoConnectionsto open the Single sign-on page,iam:GetSsoConnectionto load the current mappings (without it the list shows empty and Save groups refuses to save) andiam:ListGroupsto pick IAM groups. - The IAM group exists and is not managed by SCIM (see Create a group).
- 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
- Open IAM, then choose Single sign-on.
- On the connection's card, under Groups, check Groups claim / attribute. It is
groupsunless you change it. - Choose Add mapping.
- For IdP group, enter engineering; for IAM group, choose developers.
- Choose Save groups. The console says
Saved. It applies from each person’s next sign-in.
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"}]'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.
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.