Update user-provisioning-with-scim-on-ghes.md (#54807)

Co-authored-by: Isaac Brown <[email protected]>
Co-authored-by: Justin Alex <[email protected]>
Co-authored-by: Joe Clark <[email protected]>

Author: 4 people

content/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes.md

@@ -67,13 +67,25 @@ During the {% data variables.release-phases.private_preview %}, your account tea
 
 When SCIM is enabled, you will no longer be able to delete, suspend, or promote SCIM-provisioned users directly on {% data variables.product.prodname_ghe_server %}. You must manage these processes from your IdP.
 
-## What will happen to existing users on my instance?
+To view suspended members, navigate to the "Suspended Members" tab of your enterprise settings.  This page will be present when SCIM is enabled on {% data variables.product.prodname_ghe_server %}.
 
-If you currently use SAML SSO, and you are enabling SCIM, you should be aware of what happens to existing users during SCIM provisioning.
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.people-tab %}
+1. Click **Suspended Members**.
 
-* When SCIM is enabled, users with SAML-linked identities will **not be able to sign in** until their identities have been provisioned by SCIM.{% ifversion scim-for-ghes-ga %} You will no longer be able to update the SAML `NameID` of existing users in the site admin dashboard.{% endif %}
-* When your instance receives a SCIM request, SCIM identities are matched to existing users by **comparing the `userName` SCIM field with the {% data variables.product.prodname_dotcom %} username**. If a user with a matching username doesn't exist, {% data variables.product.prodname_dotcom %} creates a new user.
-* If {% data variables.product.prodname_dotcom %} successfully identifies a user from the IdP, but account details such as email address, first name, or last name don't match, the instance **overwrites the details** with values from the IdP. Any email addresses other than the primary email provisioned by SCIM will also be deleted from the user account.
+## What happens when I enable SCIM?
+
+If you currently use SAML SSO, and you are enabling SCIM, you should be aware of what happens to existing user accounts on {% data variables.product.prodname_ghe_server %} once SCIM is enabled.
+
+* Existing users with SAML mappings will **not be able to sign in** until their identities have been provisioned by SCIM.
+{%- ifversion scim-for-ghes-ga %}
+* {% data variables.product.prodname_ghe_server %} will no longer store SAML mappings for users. Instead, SCIM identities will be stored for users when a user is provisioned.
+* You will no longer see the "SAML authentication" section on the `https://HOSTNAME/users/USER/security` site admin page for users. It will not be possible to view or update SAML NameID mappings that were previously visible in this section, since these stored SAML mappings are no longer evaluated during SAML authentication when SCIM is enabled.
+{%- endif %}
+* When your instance receives a SCIM request, SCIM identities are matched to existing users by **comparing the SCIM `userName` attribute value with the {% data variables.product.prodname_ghe_server %} username**. This means that an existing {% data variables.product.prodname_ghe_server %} user account, regardless of whether it was originally created as a local user account or via SAML JIT-provisioning, can be converted into a SCIM-linked user account if these two values match.
+  * If a user account with a matching username does exist, {% data variables.product.prodname_ghe_server %} links the SCIM identity to this user account.
+  * If a user account with a matching username doesn't exist, {% data variables.product.prodname_ghe_server %} creates a new user account and links it to this SCIM identity.
+* If {% data variables.product.prodname_dotcom %} successfully matches a user who is authenticating via SAML with an existing user account, but account details such as email address, first name, or last name don't match, the instance **overwrites the details** with values from the IdP. Any email addresses other than the primary email provisioned by SCIM will also be deleted from the user account.
 
 ## What happens during SAML authentication?
 
@@ -89,19 +101,26 @@ After an IdP administrator grants a person access to {% data variables.location.
 
 ## What happens if I disable SCIM?
 
-SCIM will be disabled on your instance if any of the following things happens.
+SCIM will be disabled on {% data variables.product.prodname_ghe_server %} if any of the following things happens.
 
 * The **Enable SCIM configuration** checkbox is unselected on the "Authentication security" page in the enterprise settings.
 * The **SAML** radio button is unselected in the "Authentication" section of the Management Console.
 * The SAML **Issuer** or **Single sign-on URL** field is updated in the "Authentication" section of the Management Console.
 
-If SCIM is disabled on the instance:
+When SCIM is disabled on {% data variables.product.prodname_ghe_server %}:
 
+* All linked SCIM identities and SCIM-provisioned groups will be deleted from the instance.
 * Requests to the SCIM API endpoints on your instance will no longer succeed.
-* SCIM-provisioned users will remain unchanged and will not be suspended.
+* All SCIM external identities on {% data variables.product.prodname_ghe_server %} will be deleted.
+* All user accounts will remain with the same usernames, and they will not be suspended when SCIM is disabled.
+* All of the external groups that were previously provisioned by SCIM will be deleted.
+* All user accounts, including SCIM-provisioned user accounts, will remain on the instance and will not be suspended.
 * Site administrators will be able to manage the lifecycle of SCIM-provisioned users, such as suspension and deletion, from the site admin dashboard.
 * Users will still be able to sign on via SAML, if enabled.
-* Users will be unlinked from their external identity record, and the record will be deleted.
+* The "Suspended Members" page in your enterprise settings will no longer be present. Suspended members can still be seen in the [Site Admin dashboard](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/suspending-and-unsuspending-users#viewing-suspended-users-in-the-site-admin-dashboard)
+{%- ifversion scim-for-ghes-ga %}
+* You will be able to see the "SAML authentication" section on the `https://HOSTNAME/users/USER/security` site admin page for users. If any SAML mappings were previously created for users on the {% data variables.product.prodname_ghe_server %} before SCIM was enabled, it will be possible to once again view and update them in this section.
+{%- endif %}
 
 {% endif %}