Group Mapping for Automated Team Management in Docker

--- description: Group mapping for administrators keywords: Group Mapping, SCIM, Docker Hub, Docker Admin, admin, security title: Group mapping aliases: - /admin/company/settings/group-mapping/ - /admin/organization/security-settings/group-mapping/ - /docker-hub/group-mapping/ - /security/for-admins/group-mapping/ weight: 40 --- {{< summary-bar feature_name="SSO" >}} Group mapping lets you sync user groups from your identity provider (IdP) with teams in your Docker organization. This automates team membership management, keeping your Docker teams up to date based on changes in your IdP. You can use group mapping once you have configured [single sign-on (SSO)](../single-sign-on/_index.md). > [!TIP] > > Group mapping is ideal for adding users to multiple organizations or multiple teams within one organization. If you don't need to set up multi-organization or multi-team assignment, you can use SCIM [user-level attributes](scim.md#set-up-role-mapping). ## How group mapping works With group mapping enabled, when a user authenticates through SSO, your IdP shares key attributes with Docker, such as the user's email address, name, and groups. Docker uses these attributes to create or update the user's profile, as well as to manage their team and organization assignments. With group mapping, users’ team memberships in Docker automatically reflect changes made in your IdP groups. It's important to note that Docker uses the user's email address as a unique identifier. Each Docker account must always have a unique email address. ## Use group mapping To assign users to Docker teams through your IdP, you must create groups in your IdP following the naming pattern: `organization:team`. For example, if your organization is called "moby" and you want to manage the "developers" team, the group name in your IdP should be `moby:developers`. In this example, any user added to this group in your IdP is automatically assigned to the "developers" team in Docker. You can also use this format to assign users to multiple organizations. For example, to add a user to the "backend" team in the "moby" organization and the "desktop" team in the "whale" organization, the group names would be `moby:backend` and `whale:desktop`. > [!TIP] > > Match the group names in your IdP with your Docker teams. When groups are synced, Docker creates a team if it doesn’t already exist. The following lists the supported group mapping attributes: | Attribute | Description | |:--------- | :---------- | | id | Unique ID of the group in UUID format. This attribute is read-only. | | displayName | Name of the group following the group mapping format: `organization:team`. | | members | A list of users that are members of this group. | | members(x).value | Unique ID of the user that is a member of this group. Members are referenced by ID. | The general steps to use group mapping are: 1. In your IdP, create groups with the `organization:team` format. 2. Add users to the group. 3. Add the Docker application that you created in your IdP to the group. 4. Add attributes in the IdP. 5. Push groups to Docker. The exact configuration may vary depending on your IdP. You can use [group mapping with SSO](#use-group-mapping-with-sso), or with SSO and [SCIM enabled](#use-group-mapping-with-scim). ### Use group mapping with SSO The following steps describe how to set up and use group mapping with SSO connections that use the SAML authentication method. Note that group mapping with SSO isn't supported with the Azure AD (OIDC) authentication method. Additionally, SCIM isn't required for these configurations. {{< tabs >}} {{< tab name="Okta" >}} The user interface for your IdP may differ slightly from the following steps. You can refer to the [Okta documentation](https://help.okta.com/oie/en-us/content/topics/apps/define-group-attribute-statements.htm) to verify. To set up group mapping: 1. Sign in to Okta and open your application. 2. Navigate to the **SAML Settings** page for your application.

Group mapping allows syncing user groups from an identity provider (IdP) with Docker organization teams, automating team membership management. By creating groups in the IdP with the format `organization:team`, users added to these groups are automatically assigned to the corresponding Docker team. The article outlines how group mapping works and provides steps to use it, particularly with SSO using the SAML authentication method, and provides an example using Okta.