Group mapping

With directory group-to-team provisioning from your IdP, user updates will automatically sync with your Docker organizations and teams. You can use group mapping once you have configured single sign-on (SSO).

[!TIP]

Group mapping is ideal for adding a user 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 user-level attributes.

How group mapping works#

IdPs share with Docker the main attributes of every authorized user through SSO, such as email address, name, surname, and groups. Just-in-Time (JIT) Provisioning uses these attributes to create or update the user’s Docker profile and their associations with organizations and teams on Docker Hub.

Docker uses the email address of the user to identify them on the platform. Every Docker account must have a unique email address at all times.

Use group mapping#

To correctly assign your users to Docker teams, you must create groups in your IdP following the naming pattern organization:team. For example, if you want to manage provisioning for the team "developers", and your organization name is "moby", you must create a group in your IdP with the name moby:developers.

Once you enable group mappings in your connection, users assigned to that group in your IdP will automatically be added to the team "developers" in Docker.

You can use this format to add a user to multiple organizations. For example, if you want to add a user to the "backend" team in the "moby" organization as well as the "desktop" team in the "whale" organization, the format would be: moby:backend and whale:desktop.

Tip

Use the same names for the Docker teams as your group names in the IdP to prevent further configuration. When you sync groups, this creates a group 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:

In your IdP, create groups with the organization:team format.
Add users to the group.
Add the Docker application that you created in your IdP to the group.
Add attributes in the IdP.
Push groups to Docker.

The exact configuration may vary depending on your IdP. You can use group mapping with SSO, or with SSO and SCIM enabled.

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 to verify.

To set up group mapping:

Sign in to the Okta Console to go to your application.
Go to the SAML Settings for your application.
In the Group Attribute Statements (optional) section, configure like the following:
Name: groups
Name format: Unspecified
Filter: Starts with + organization: where organization is the name of your organization The filter option will filter out the groups that aren't affiliated with your Docker organization.
Create your groups by navigating to Directory > Groups.
Add your groups using the format organization:team that matches the names of your organization(s) and team(s) in Docker.
Assign users to the group(s) that you create.

The next time you sync your groups with Docker, your users will map to the Docker groups you defined.

{ { < /tab > } } { { < tab name="Entra ID" > } }

The user interface for your IdP may differ slightly from the following steps. You can refer to the Entra ID documentation to verify.

To set up group mapping:

Sign in to Entra ID and go to your application.
Go to Manage > Single sign-on.
Select Add a group claim.
In Group Claims, select Groups assigned to the application with the source attribute Cloud-only group display names (Preview).
Select Advanced options, then the Filter groups option.
Configure the attribute like the following:
Attribute to match: Display name
Match with: Contains
String: :
Select Save.
Go to Groups > All groups then select New group to create your group(s).
Assign users to the group(s) that you create.

The next time you sync your groups with Docker, your users will map to the Docker groups you defined.

{ { < /tab > } } { { < /tabs > } }

Use group mapping with SCIM#

The following steps describe how to set up and use group mapping with SCIM. Before you begin, make sure you set up SCIM first.

{ { < tabs > } } { { < tab name="Okta" > } }

The user interface for your IdP may differ slightly from the following steps. You can refer to the Okta documentation to verify.

To set up your groups:

Sign in to the Okta Console to go to your application.
Select Applications > Provisioning > Integration.
Select Edit to enable groups on your connection, then select Push groups.
Select Save. Saving this configuration will add the Push Groups tab to your application.
Create your groups by navigating to Directory > Groups.
Add your groups using the format organization:team that matches the names of your organization(s) and team(s) in Docker.
Assign users to the group(s) that you create.
Return to Applications > Provisioning > Integration, then select the Push Groups tab to open the view where you can control and manage how groups are provisioned.
Select Push Groups > Find groups by rule.
Configure the groups by rule like the following:
- Enter a rule name, for example Sync groups with Docker Hub
- Match group by name, for example starts with docker: or contains : for multi-organization
- If you enable Immediately push groups by rule, sync will happen as soon as there's a change to the group or group assignments. Enable this if you don't want to manually push groups.

Find your new rule under By rule in the Pushed Groups column. The groups that match that rule are listed in the groups table on the right-hand side.

To push the groups from this table:

Select Group in Okta.
Select the Push Status drop-down.
Select Push Now.

{ { < /tab > } } { { < tab name="Entra ID" > } }

The user interface for your IdP may differ slightly from the following steps. You can refer to the Entra ID documentation to verify.

Complete the following before configuring group mapping:

Sign in to Entra ID and go to your application.
In your application, go to Provisioning > Mappings.
Select Provision Microsoft Entra ID Groups.
Select Show advanced options, then Edit attribute list.
Update the externalId type to reference, then select the Multi-Value checkbox and choose the referenced object attribute urn:ietf:params:scim:schemas:core:2.0:Group.
Select Save, then Yes to confirm.
Go to Provisioning.
Toggle Provision Status to On, then select Save.

Next, set up group mapping:

Go to the application overview page.
Under Provision user accounts, select Get started.
Select Add user/group.
Create your group(s) using the organization:team format.
Assign the group to the provisioning group.
Select Start provisioning to start the sync.

To verify, go to Monitor > Provisioning logs to see that your groups were provisioned successfully. In your Docker organization, you can check that the groups were correctly provisioned and the members were added to the appropriate teams.

{ { < /tab > } } { { < /tabs > } }

Once complete, a user who signs in to Docker through SSO is automatically added to the organizations and teams mapped in the IdP.

[!TIP]

Enable SCIM to take advantage of automatic user provisioning and de-provisioning. If you don't enable SCIM users are only automatically provisioned. You have to de-provision them manually.

More resources#

The following videos demonstrate how to use group mapping with your IdP with SCIM enabled.