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.

Last updated 18 November 2026View as Markdown

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).
  • 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

  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.

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.
Did this page help you?