Add SCIM role mapping [8/28] (#18032)

* remove limitations and add role mapping to scim docs

* update wording

* link to role mapping from manage users docs

* change list to table and update doc links

* implement feedback

* update hash link

layouts/shortcodes/admin-scim.html

@@ -3,14 +3,17 @@
 {{ $sso_navigation := `Navigate to the SSO settings page for your organization or company.
    - Organization: Select **Organizations**, your organization, **Settings**, and then **Security**.
    - Company: Select **Organizations**, your company, and then **Settings**.` }}
+{{ $group_link := "[Group mapping](/docker-hub/group-mapping)"}}
 
 {{ if eq (.Get "product") "admin" }}
 {{ $product_link = "[Docker Admin](https://admin.docker.com)" }}
 {{ $sso_link = "[configured SSO](/admin/organization/security-settings/sso-configuration/)" }}
 {{ $sso_navigation = "Select your organization in the left navigation drop-down menu, and then select **SSO & SCIM.**" }}
+{{ $group_link = "[Group mapping](/admin/organization/security-settings/group-mapping/)"}}
 {{ if eq (.Get "layer") "company" }}
 {{ $sso_link = "[configured SSO](/admin/company/settings/sso-configuration/)" }}
 {{ $sso_navigation = "Select your company in the left navigation drop-down menu, and then select **SSO & SCIM.**" }}
+{{ $group_link = "[Group mapping](/admin/company/settings/group-mapping)"}}
 {{ end }}
 {{ end }}
 
@@ -58,6 +61,32 @@ Follow the instructions provided by your IdP:
 - [Azure AD](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/user-provisioning)
 - [OneLogin](https://developers.onelogin.com/scim/create-app)
 
+## Set up role mapping
+
+You can assign [roles](/docker-hub/roles-and-permissions/) to members in your organization in the IdP. To set up a role, you can use optional user-level attributes for the person you want to assign a role. In addition to roles, you can set an organization and team to override the default provisioning values set by the SSO connection.
+
+> **Note**
+>
+> These mappings are supported for both SCIM and JIT provisioning. With JIT provisioning, role mapping only applies when a user is initially provisioned to the organization.
+
+The following table lists the supported optional user-level attributes.
+
+| Attribute | Possible values    | Considerations |
+| --------- | ------------------ | -------------- |
+| `dockerRole` | `member`, `editor`, or `owner`. For a list of permissions for each role, see [Roles and permissions](/docker-hub/roles-and-permissions/). | If you don't assign a role in the IdP, the value of the `dockerRole` attribute defaults to `member`. When you set the attribute, this overrides the default value. |
+| `dockerOrg` | `organizationName`. For example, an organization named "moby" would be `moby`. | Setting this attribute overrides the default organization configured by the SSO connection. Also, this won't add the user to the default team. If this attribute isn't set, the user is provisioned to the default organization and the default team. If set and `dockerTeam` is also set, this provisions the user to the team within that org. |
+| `dockerTeam` | `teamName`. For example, a team named "developers" would be `developers`. | Setting this attribute provisions the user to the default org and to the specified team, instead of the SSO connection's default team. This also creates the team if it doesn't exist. You can still use group mapping to provision users to teams in multiple orgs. See {{ $group_link }}. |
+
+After you set the role in the IdP, you need to sync to push the changes to Docker.
+
+The external namespace to use to set up these attributes is `urn:ietf:params:scim:schemas:extension:docker:2.0:User`.
+
+For how to add these attributes, see the documentation for your IdP:
+
+- [Okta](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-custom-user-attributes.htm)
+- [Azure AD](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes#provisioning-a-custom-extension-attribute-to-a-scim-compliant-application)
+- [OneLogin](https://onelogin.service-now.com/support?id=kb_article&sys_id=742a000d4740f1909d8dfd1f536d435f&kb_category=566ffd6887332910695f0f66cebb3556#config-info-custom)
+
 ## Disable SCIM
 
 If SCIM is disabled, any user provisioned through SCIM will remain in the organization. Future changes for your users will not sync from your IdP. User de-provisioning is only possible when manually removing the user from the organization.
@@ -66,7 +95,3 @@ If SCIM is disabled, any user provisioned through SCIM will remain in the organi
 2. {{ $sso_navigation }}
 3. In the SSO connections table, select the **Actions** icon.
 4. Select **Disable SCIM**.
-
-## Limitations
-
-Administrators can assign [roles](/docker-hub/roles-and-permissions/) to organization members. However, SCIM doesn't support role management.

layouts/shortcodes/admin-users.html

@@ -4,6 +4,7 @@
 {{ $remove_button := "**Remove member**" }}
 {{ $product_link := "[Docker Hub](https://hub.docker.com)" }}
 {{ $update_role := "Select the role you want to assign, then select **Save**." }}
+{{ $role_mapping_link := "[SCIM for role mapping](docker-hub/scim.md#set-up-role-mapping)" }}
 
 {{ if eq (.Get "product") "admin" }}
 {{ $invite_button = "**Invite**" }}
@@ -11,10 +12,12 @@
 {{ $member_navigation := "Select your organization in the left navigation drop-down menu, and then select *Members**." }}
 {{ $remove_button = "**Remove member**" }}
 {{ $product_link = "[Docker Admin](https://admin.docker.com)" }}
+{{ $role_mapping_link = "[SCIM for role mapping](admin/organization/security-settings/scim.md#set-up-role-mapping)" }}
 {{ if eq (.Get "layer") "company" }}
 {{ $member_navigation = "Select your company in the left navigation drop-down menu, and then select **Users**." }}
 {{ $remove_button = "**Remove user**" }}
 {{ $update_role = "Select their organization, select the role you want to assign, and then select **Save**." }}
+{{ $role_mapping_link = "[SCIM for role mapping](admin/company/settings/scim.md#set-up-role-mapping)"}}
 {{ end }}
 {{ end }}
 
@@ -132,7 +135,7 @@ To remove a member from an organization:
 
 Organization owners can manage [roles](/docker-hub/roles-and-permissions/)
 within an organization. If an organization is part of a company,
-the company owner can also manage that organization's roles.
+the company owner can also manage that organization's roles. If you have SSO enabled, you can use {{ $role_mapping_link }}.
 
 > **Note**
 >