ENGDOCS-1301 (#17125)

* ENGDOCS-1301

* add image

* add screenshot, clarify SCIM, tidy

* reorg toc

* tidy

* reduce image size

* enfore sign in info

_data/toc.yaml

@@ -1885,8 +1885,6 @@ manuals:
     title: Create and manage a team
   - path: /docker-hub/members/
     title: Manage members
-  - path: /docker-hub/configure-sign-in/
-    title: Enforce sign-in
   - sectiontitle: Single Sign-on
     section:
       -  path: /single-sign-on/
@@ -1917,6 +1915,8 @@ manuals:
             title: Recover your Docker Hub account
           - path: /docker-hub/2fa/new-recovery-code/
             title: Generate a new recovery code
+  - path: /docker-hub/configure-sign-in/
+    title: Enforce sign-in for Desktop
   - path: /docker-hub/audit-log/
     title: Audit logs
   - path: /docker-hub/domain-audit/

docker-hub/group-mapping.md

@@ -15,10 +15,38 @@ Once you enable group mappings in your connection, users assigned to that group
 >Use the same names for the Docker teams as your group names in the IdP to prevent further configuration. When you sync groups, a group is created if it doesn’t already exist.
 {: .tip}
 
-To take advantage of group mapping, make sure you have [enabled SCIM](scim.md) and then follow the instructions provided by your IdP:
+## 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. These attributes are used by Just-In-Time (JIT) Provisioning 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.
+
+After every successful SSO sign-in authentication, the JIT provisioner performs the following actions:
+
+1. Checks if there's an existing Docker account with the email address of the user that just authenticated.
+    
+    a) If no account is found with the same email address, it creates a new Docker account using basic user attributes (email, name, and surname). The JIT provisioner generates a new username for this new account by using the email, name, and random numbers to make sure that all account usernames are unique in the platform.
+    
+    b) If an account exists for this email address, it uses this account and updates the full name of the user’s profile if needed.
+2. Checks if the IdP shared group mappings while authenticating the user.
+
+    a) If the IdP provided group mappings for the user, the user gets added to the organizations and teams indicated by the group mappings.
+    
+    b) If the IdP didn't provide group mappings, it checks if the user is already a member of the organization, or if the SSO connection is for multiple organizations (only at company level) and if the user is a member of any of those organizations. If the user is not a member, it adds the user to the default team and organization configured in the SSO connection.
+
+![JIT provisioning](images/jit.PNG)
+
+## Use group mapping
+
+To take advantage of group mapping, follow the instructions provided by your IdP:
 
 - [Okta](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-enable-group-push.htm){: target="_blank" rel="noopener" class="_" }
 - [Azure AD](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes){: target="_blank" rel="noopener" class="_" }
 - [OneLogin](https://developers.onelogin.com/scim/create-app){: target="_blank" rel="noopener" class="_" }
 
-Once complete, a user who signs in to Docker through SSO is automatically added to the organizations and teams mapped in the IdP.
+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](scim.md) 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. 
+{: .tip}

single-sign-on/configure/index.md

@@ -49,6 +49,10 @@ Follow the steps on this page to configure SSO for your organization or company.
    - SAML: **Entity ID**, **ACS URL**
    - Azure AD (OIDC): **Redirect URL**
 
+   ![SAML](../../docker-hub/images/saml-create-connection.png){: width="500px" }
+   
+   ![Azure AD](../../docker-hub/images/azure-create-connection.png){: width="500px" }
+
 4. From your IdP, copy and paste the following values into the Docker **Settings** fields:
 
     - SAML: **SAML Sign-on URL**, **x509 Certificate**
@@ -68,16 +72,21 @@ The SSO connection is now created. You can continue to set up [SSO Group Mapping
 
 ## Optional step three: Test your SSO configuration
 
-After you’ve completed the SSO configuration process in Docker Hub, you can test the configuration when you sign in to Docker Hub using an incognito browser. Log in to Docker Hub using your domain email address. You are then redirected to your IdP's login page to authenticate.
+After you’ve completed the SSO configuration process in Docker Hub, you can test the configuration when you sign in to Docker Hub using an incognito browser. Sign in to Docker Hub using your domain email address. You are then redirected to your IdP's login page to authenticate.
 
 1. Authenticate through email instead of using your Docker ID, and test the login process.
 2. To authenticate through CLI, your users must have a PAT before you enforce SSO for CLI users.
 
-## Optional step four: Enforce SSO log-in in Docker Hub
+## Optional step four: Enforce SSO 
 
 1. In the **Single Sign-On Connections** table, select the **Action** icon and then **Enforce Single Sign-on**.
     When SSO is enforced, your users are unable to modify their email address and password, convert a user account to an organization, or set up 2FA through Docker Hub. You must enable 2FA through your IdP.
 2. Continue with the on-screen instructions and verify that you’ve completed the tasks. 
 3. Select **Turn on enforcement** to complete. 
 
-To enforce SSO log-in for Docker Desktop, see [Enforce sign-in](../../docker-hub/configure-sign-in.md).
+Your users must now sign in to Docker with SSO. 
+
+>**Important**
+>
+>If SSO isn't enforced, users can choose to sign in with either their Docker ID or SSO.
+{: .important}