Configuring user provisioning with SCIM on GitHub Enterprise Server

About user provisioning for GitHub Enterprise Server

If you use SAML single sign-on (SSO) for your GitHub Enterprise Server instance, you can configure SCIM to automatically create or suspend user accounts and grant access to your instance when you assign or unassign the application on your IdP. For more information about SCIM, see System for Cross-domain Identity Management: Protocol (RFC 7644) on the IETF website.

If you do not configure user provisioning with SCIM, your IdP will not communicate with GitHub Enterprise Server automatically when you assign or unassign the application to a user. Without SCIM, GitHub Enterprise Server creates a user account using SAML Just-in-Time (JIT) provisioning the first time someone navigates to GitHub Enterprise Server and signs in by authenticating through your IdP.

To configure provisioning for your enterprise, you must enable provisioning on GitHub Enterprise Server, then install and configure a provisioning application on your IdP.

Supported identity providers

During the private beta, your account team will provide documentation for the configuration of SCIM for GitHub Enterprise Server on a supported IdP.

How will I manage user lifecycles with SCIM?

With SCIM, you manage the lifecycle of user accounts from your IdP:

• When you provision a new user, your IdP will prompt your GitHub Enterprise Server instance to create an account and send an onboarding email to the user. If you assign a group to the application in your IdP, your IdP will provision accounts for all members of the group.
• When you update information associated with a user's identity on your IdP, your IdP will update the user's account on GitHub.
• When you unassign the user from the IdP application or deactivate a user's account on your IdP, your IdP will communicate with GitHub to invalidate any sessions and disable the member's account. The disabled account's information is maintained and their username is changed to a hash of their original username.
• If you reassign a user to the IdP application or reactivate their account on your IdP, the user account will be reactivated, and the username will be restored.

When SCIM is enabled, you will no longer be able to delete, suspend, or promote SCIM-provisioned users directly on GitHub Enterprise Server. You must manage these processes from your IdP.

What will happen to existing users on my instance?

If you currently use SAML SSO, and you are enabling SCIM, you should be aware of what happens to existing users during SCIM provisioning.

• When SCIM is enabled, users with SAML-linked identities will not be able to sign in until their identities have been provisioned by SCIM.
• When your instance receives a SCIM request, SCIM identities are matched to existing users by comparing the userName SCIM field with the GitHub username. If a user with a matching username doesn't exist, GitHub creates a new user.
• If GitHub 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 during SAML authentication?

After an IdP administrator grants a person access to your GitHub Enterprise Server instance, the user can authenticate through the IdP to access GitHub Enterprise Server using SAML SSO.

• When a user authenticates through SAML, to associate a user with a SAML identity, GitHub compares a normalized NameID claim from the IdP (or another value you have configured) to the account's username. For details about normalization, see Username considerations for external authentication.
• If there is no account with a matching username on the instance, the user will fail to sign in.
  • To make this match, GitHub Enterprise Server compares the SAML NameId claim from the IdP to the SCIM userName attribute for each user account provisioned by SCIM on the instance.
  • Additionally, for Entra ID, GitHub Enterprise Server compares the object identifier from the SAML request with an existing SCIM external ID.
• If your environment does not use NameID to uniquely identify users, a site administrator can configure custom user attributes for the instance. GitHub Enterprise Server will respect this mapping when SCIM is configured. For more information about mapping user attributes, see Configuring SAML single sign-on for your enterprise.

Prerequisites

• You must configure SAML SSO for your GitHub Enterprise Server instance. For more information, see Configuring SAML single sign-on for your enterprise.

• You must allow built-in authentication for users who don't have an account on your IdP. For more information, see Allowing built-in authentication for users outside your provider.

• Your IdP must support making SCIM calls to a Service Provider (SP).

• You must have administrative access on your IdP to configure the application for user provisioning for GitHub Enterprise Server.

Enabling user provisioning for your enterprise

To perform provisioning actions on your instance, you will create a built-in user account and promote the account to an enterprise owner.

After you enable SCIM on a GitHub Enterprise Server instance, all user accounts are suspended. The built-in user account will continue to perform provisioning actions. After you grant a user access to your instance from your IdP, the IdP will communicate with the instance using SCIM to unsuspend the user's account.

1. Create a built-in user account to perform provisioning actions on your instance. For more information, see Allowing built-in authentication for users outside your provider.

2. Promote the dedicated user account to an enterprise owner. For more information, see Inviting people to manage your enterprise.

3. Sign into your instance as the new enterprise owner.

4. Create a personal access token (classic) with admin:enterprise scope. Do not specify an expiration date for the personal access token (classic). For more information, see Managing your personal access tokens.

   Warning

   Ensure that you don't specify an expiration date for the personal access token (classic). If you specify an expiration date, SCIM will no longer function after the expiration date passes.

   Note

   You'll need this personal access token to test the SCIM configuration, and to configure the application for SCIM on your IdP. Store the token securely in a password manager until you need the token again later in these instructions.

5. SSH into your GitHub Enterprise Server instance. If your instance comprises multiple nodes, for example if high availability or geo-replication are configured, SSH into the primary node. If you use a cluster, you can SSH into any node. Replace HOSTNAME with the hostname for your instance, or the hostname or IP address of a node. For more information, see "Accessing the administrative shell (SSH)."

   Shell

   ssh -p 122 admin@HOSTNAME
   

6. To enable SCIM, run the commands provided to you by your account manager on GitHub's Sales team.

7. Wait for the configuration run to complete.

8. To validate that SCIM is operational, run the following commands. Replace PAT FROM STEP 3 and YOUR INSTANCE'S HOSTNAME with actual values.

   $ GHES_PAT="PAT FROM STEP 3"
   $ GHES_HOSTNAME="YOUR INSTANCE'S HOSTNAME"
   $ curl --location --request GET 'https://$GHES_HOSTNAME/api/v3/scim/v2/Users' \
       --header 'Content-Type: application/scim' \
       --header 'Authorization: Bearer $GHES_PAT'
   

   The command should return an empty array.

9. Configure user provisioning in the application for GitHub Enterprise Server on your IdP. To request documentation for a supported IdP, contact your account manager on GitHub's Sales team. If your IdP is unsupported, you must create the application and configure SCIM manually.