GHES SCIM Documentation Updates (Batch 3/3) (#55228)

Co-authored-by: Sarita Iyer <[email protected]>

Author: taylorreis

assets/images/help/saml/entra-id-saml-scim-mapping-error.png

@@ -45,6 +45,20 @@ If your enterprise uses {% data variables.product.prodname_emus %}, you will not
 {% data reusables.saml.revoke-sso-identity %}
 {% data reusables.saml.confirm-revoke-identity %}
 
+{% elsif scim-for-ghes-public-beta %}
+
+## Viewing a linked identity
+
+You can view the single sign-on identity that a member has linked to their account on GitHub.
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.people-tab %}
+{% data reusables.saml.click-person-revoke-identity %}
+{% data reusables.saml.saml-identity-linked %}
+{% data reusables.saml.view-sso-identity %}
+
+The identity data on this page will include the SCIM data that was sent to {% data variables.product.github %} during user provisioning. This SCIM data is what {% data variables.product.github %} uses when matching a SAML SSO request to the provisioned user. Note that {% data variables.product.github %} does not use SAML mappings when SCIM is enabled. For more information on how {% data variables.product.github %} maps SAML and SCIM data for users, please see [AUTOTITLE](/rest/enterprise-admin/scim?apiVersion=2022-11-28#mapping-of-saml-and-scim-data).
+
 {% endif %}
 
 ## Viewing and revoking an active SAML session

assets/images/help/saml/okta-saml-scim-mapping-error.png

@@ -97,14 +97,19 @@ This will cause a username conflict, and only the first user will be provisioned
 
 Usernames{% ifversion ghec %}, including underscore and short code,{% endif %} must not exceed 39 characters.
 
+{% ifversion ghes %}
+> [!NOTE]
+> If you use SAML with SCIM provisioning, users must be SCIM provisioned before using SAML single sign-on. If a user hasn't been provisioned, they won't be able to complete authentication on your {% data variables.product.prodname_ghe_server %} instance. For more information, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes#how-will-i-manage-user-lifecycles-with-scim).
+{% endif %}
+
 ## About username normalization
 
 Usernames for user accounts on {% data variables.product.prodname_dotcom %} can only contain alphanumeric characters and dashes (`-`).
 
 {% ifversion ghec %}
 When you configure SAML authentication, {% data variables.product.github %} uses the SCIM `userName` attribute value sent from the IdP to determine the username for the corresponding user account on {% data variables.product.prodname_dotcom %}. If this value includes unsupported characters, {% data variables.product.github %} will normalize the username per the following rules.
 {% elsif ghes %}
-When you configure CAS, LDAP, or SAML authentication, {% data variables.product.prodname_ghe_server %} uses an identifier from the user account on your external authentication provider to determine the username for the corresponding user account on your {% data variables.product.prodname_ghe_server %} instance. If the identifier includes unsupported characters, {% data variables.product.github %} will normalize the username per the following rules.
+When you configure CAS, LDAP, or SAML authentication (without SCIM), {% data variables.product.prodname_ghe_server %} uses an identifier from the user account on your external authentication provider to determine the username for the corresponding user account on your {% data variables.product.prodname_ghe_server %} instance. When SAML authentication is configured with SCIM, {% data variables.product.github %} uses the SCIM `userName` attribute value sent from the IdP to determine the username for the corresponding user account. If the identifier includes unsupported characters, {% data variables.product.github %} will normalize the username per the following rules.
 {% endif %}
 
 1. {% data variables.product.github %} will normalize any non-alphanumeric character in your account's username into a dash. For example, a username of `mona.the.octocat` will be normalized to `mona-the-octocat`. Note that normalized usernames also can't start or end with a dash. They also can't contain two consecutive dashes.
@@ -154,7 +159,7 @@ When you configure CAS, LDAP, or SAML authentication, {% data variables.product.
 
 ## Resolving username problems
 
-When a new user is being provisioned, if the username is longer than 39 characters (including underscore and short code), or conflicts with an existing user in the enterprise, the provisioning attempt will fail with a `409` error.
+When a new user is being provisioned, if the username conflicts with an existing user in the enterprise, the provisioning attempt will fail with a `409` error. If the username is longer than 39 characters (including underscore{% ifversion ghec %} and short code{% endif %}), the provisioning attempt will fail with a `400` error. For a full list of possible user provisioning status codes, see [AUTOTITLE](/rest/enterprise-admin/scim?apiVersion=2022-11-28#provision-a-scim-enterprise-user--status-codes).
 
 To resolve this problem, you must make one of the following changes in your IdP so that all normalized usernames will be within the character limit and unique.
 

content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise.md

@@ -267,7 +267,9 @@ After you configure SCIM provisioning for your enterprise, you may need to migra
 
 * If your requests to the REST API are rate-limited, you can learn more in [Understand rate limits on {% data variables.product.prodname_dotcom %}](#understand-rate-limits-on-github).
 
-* If you enable audit log streaming and stream events for API requests, you can review any requests to the REST API endpoints for SCIM provisioning by filtering for events from the `EnterpriseUsersScim` or `EnterpriseGroupsScim` controllers.
+* All SCIM requests that {% data variables.product.company_short %} receives, with the exception of successful HTTP `GET` requests, will generate an [audit log](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#external_identity) event. These logs will contain useful information about the request outcome, payload information, and any errors. These logs can be used to determine whether or not {% data variables.product.company_short %} received a SCIM request, and troubleshoot API failures.
+  * To determine if a user has been provisioned, you can use the following audit log query: `action:external_identity.provision  user:USERNAME{% ifversion ghec %}_SHORTCODE{% endif %}`
+  * If you do not find a user using the query above, you can search for `action:external_identity.scim_api_failure` events on the date that you expected to have received the request.
 
 * If a SCIM request fails and you're unable to determine the cause, check the status of your identity management system to ensure that services were available.{% ifversion ghec %} Additionally, check {% data variables.product.company_short %}'s status page. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-github-support#about-github-status).{% endif %}
 

content/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication.md

@@ -41,33 +41,66 @@ If you're experiencing problems while switching between different authentication
 * [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-from-saml-to-oidc)
 * [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant)
 
+{% endif %}
+
 ## Accessing your enterprise when SSO is not available
 
-When a configuration error or an issue with your identity provider IdP prevents you from using SSO, you can use a recovery code to access your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable).
+When a configuration error or an issue with your identity provider IdP prevents you from using SSO, you can use a {% ifversion ghec %}recovery code to access your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable).{% else %}site admin with access to the Management Console to update your settings, or disable SAML temporarily. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console).{% endif %}
 
 ## SCIM provisioning errors
 
+{% ifversion ghec %}
 {% data reusables.scim.emu-scim-rate-limit-details %}
+{% endif %}
 
 Microsoft Entra ID (previously known as Azure AD) will retry SCIM provisioning attempts automatically during the next Entra ID sync cycle. The default SCIM provisioning interval for Entra ID is 40 minutes. For more information about this retry behavior, see the [Microsoft documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/how-provisioning-works#errors-and-retries) or contact Microsoft support if you need additional assistance.
 
 Okta will retry failed SCIM provisioning attempts with manual Okta admin intervention. For more information about how an Okta admin can retry a failed task for a specific application, see the [Okta documentation](https://support.okta.com/help/s/article/How-to-retry-failed-tasks-for-a-specific-application?language=en_US) or contact Okta support.
-{% endif %}
 
-In an {% data variables.enterprise.prodname_emu_enterprise %} where SCIM is generally functioning properly, individual user SCIM provisioning attempts sometimes fail. Users will be unable to sign in until their account is provisioned to {% data variables.product.github %}. These individual SCIM user provisioning failures result in an HTTP 400 status code and are typically caused by issues with username normalization or username conflicts, where another user with the same normalized username already exists in the enterprise. See [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication).
+In{% ifversion ghec %} an {% data variables.enterprise.prodname_emu_enterprise %}{% else %} your instance{% endif %} where SCIM is generally functioning properly, individual user SCIM provisioning attempts sometimes fail. Users will be unable to sign in until their account is provisioned to {% data variables.product.github %}. These individual SCIM user provisioning failures result in an HTTP 400 range status code and are typically caused by issues with username normalization or username conflicts, where another user with the same normalized username already exists in the enterprise. See [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication).
 
 ## SAML authentication errors
 
 If users are experiencing errors when attempting to authenticate with SAML, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication).
 
+{% ifversion scim-for-ghes-ga %}
+
+## SAML and SCIM data mapping errors
+
+If you use SAML with SCIM on your {% data variables.product.prodname_ghe_server %} instance, and a user's SAML data does not match to an existing SCIM provisioned identity, {% data variables.product.github %} will return an error.
+
+For Entra ID, the error will look like:
+
+![Screenshot of an Entra ID SAML and SCIM data mapping error.](/assets/images/help/saml/entra-id-saml-scim-mapping-error.png)
+
+For all other identity providers, the error will look like:
+
+![Screenshot of an Okta SAML and SCIM data mapping error.](/assets/images/help/saml/okta-saml-scim-mapping-error.png)
+
+When this error occurs, please follow the steps below:
+
+1. Ensure that a SCIM identity has been provisioned for the user by searching through the users on your instance. For more information on how to find SCIM provisioned users on your instance, please see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#filtering-by-account-type-saml-and-scim).
+    * If the user has not been provisioned yet, it is either because the identity provider has not yet sent a provisioning request, or the provisioning request failed. Enterprise administrators can use their [audit log](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#external_identity) events to determine which of these two scenarios they are impacted by. For more information, please see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api#troubleshooting-scim-provisioning).
+1. If the user has been successfully provisioned on your instance, you will need to ensure that the value for the SAML attribute listed in the error message matches the value of the listed SCIM attribute. To find the value for the SCIM attribute, please see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise?search-overlay-input=saml+identity&search-overlay-ask-ai=true#viewing-a-linked-identity).
+    * For example, to troubleshoot the screenshot above, we would look at the user's SCIM "External ID" value. Using that value, we would ensure that the user has the correct value set with the Identity Provider.
+
+For more information on how {% data variables.product.github %} maps SAML and SCIM data for users, please see [AUTOTITLE](/rest/enterprise-admin/scim?apiVersion=2022-11-28#mapping-of-saml-and-scim-data).
+
+{% endif %}
+
 {% ifversion ghec %}
 
 ## Conflicting SAML identity errors
 
 {% data reusables.saml.conflicting-identity %}
 
+{% endif %}
+
 ## Further reading
 
+{% ifversion scim-for-ghes-public-beta %}
+* [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups)
+{% elsif ghec %}
 * [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups)
 * [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization)
 {% endif %}

content/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api.md

@@ -127,14 +127,27 @@ To authenticate API requests, the person who configures SCIM on the IdP must use
 
 ### Mapping of SAML and SCIM data
 
-The {% data variables.product.prodname_ghe_server %} instance links each user who authenticates successfully with SAML SSO to a SCIM identity. To link the identities successfully, the SAML IdP and the SCIM integration must use matching SAML `NameID` and SCIM `userName` values for each user.
+After a {% data variables.product.prodname_ghe_server %} user successfully authenticates using SAML SSO, {% data variables.product.github %} links the user to a SCIM provisioned identity. To link the identities successfully, the SAML identity provider and the SCIM integration must use matching unique identifiers.
 
-{% ifversion ghes %}
+When a mismatch between a user's SAML and SCIM data occurs, {% data variables.product.company_short %} will return an error stating which attributes from SAML and SCIM did not match. For more information on this error, see [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise#saml-and-scim-data-mismatch-errors).
 
-> [!NOTE]
-> If the {% data variables.product.prodname_ghe_server %} instance uses Entra ID as a SAML IdP, {% data variables.product.github %} will also check the SCIM `externalId` claim and SAML `http://schemas.microsoft.com/identity/claims/objectidentifier` claim to match users first, instead of using `NameID` and `userName`.
+{% data variables.product.company_short %} requires the following SAML claim and SCIM attribute to successfully match the user with the identity provisioned by SCIM. Identity providers may differ in the field used to uniquely identify a user.
 
-{% endif %}
+#### Microsoft Entra ID for SAML
+
+To use Entra ID (previously known as Azure AD) for SAML, the following SAML claims and SCIM attribute must match.
+
+| SAML claim | Matching SCIM attribute |
+| :- | :- |
+| `http://schemas.microsoft.com/identity/claims/objectidentifier` | `externalId` |
+
+#### Other IdPs for SAML
+
+To use other IdPs for SAML, {% data variables.product.company_short %} will use the "Username" attribute configured in your SAML "User attributes" to match against the SCIM attribute listed below. If left blank, the "Username" attribute in your SAML "User attributes" will default to the SAML `NameID`. For more information about SAML configurations, see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso).
+
+| SAML claim | Matching SCIM attribute |
+| :- | :- |
+| "Username" attribute configured in your SAML "User attributes", or `NameID` if left blank | `userName` |
 
 ### Supported SCIM user attributes
 

content/admin/managing-iam/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise.md

@@ -1 +1,6 @@
 To access each organization's resources on {% data variables.product.github %}, the member must have an active SAML session in their browser.{% ifversion ghec %} To access each organization's protected resources using the API and Git, the member must use a {% data variables.product.pat_generic %} or SSH key that the member has authorized for use with the organization.{% endif %} Enterprise owners can view and revoke a member's {% ifversion ghec %}linked identity, active sessions, or authorized credentials{% else %}active SAML sessions{% endif %} at any time.
+
+{% ifversion ghes %}
+>[!NOTE]
+> This view is only enabled when SAML with SCIM is enabled.
+{% endif %}