Skip to main content

Configuring user provisioning with SCIM for your enterprise

You can configure System for Cross-domain Identity Management (SCIM) for your GitHub Enterprise Server instance, which automatically provisions user accounts when you assign the application for your instance to a user on your identity provider (IdP).

Who can use this feature

Site administrators can configure user provisioning for a GitHub Enterprise Server instance.

Note: SCIM for GitHub Enterprise Server is currently in private beta and is subject to change. For access to the beta, contact your account manager on GitHub's Sales team.

Warning: The beta is exclusively for testing and feedback, and no support is available. GitHub recommends testing with a staging instance. For more information, see "Setting up a staging instance."

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.

Configuring provisioning allows your IdP to communicate with your GitHub Enterprise Server instance when you assign or unassign the application for GitHub Enterprise Server to a user on your IdP. When you assign the application, your IdP will prompt your GitHub Enterprise Server instance to create an account and send an onboarding email to the user. When you unassign the application, your IdP will communicate with GitHub Enterprise Server to invalidate any SAML sessions and disable the member's account.

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

The provisioning application on your IdP communicates with GitHub Enterprise Server using the SCIM API. For more information, see "SCIM" in the REST API documentation.

About identities and claims

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.

During authentication, the instance attempts to associate the user with a SAML identity. By default, the instance compares the NameID claim from the IdP to the account's username. GitHub Enterprise Server normalizes the value of NameID for the comparison. For more information about username normalization, see "Username considerations for external authentication."

If there is no matching username on the instance, the instance creates a new account for the user. If there is an account with a matching username on the instance, the user signs into the account. GitHub Enterprise Server compares the claim from the IdP against all accounts on the instance, regardless of whether the accounts use built-in authentication or are already associated with a SAML identity.

When using SAML SSO, a site administrator can configure custom user attributes for the instance. A custom username attribute will allow the instance to use a value from the IdP other than NameID. 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."

If GitHub Enterprise Server successfully identifies a user from the IdP, but account details such as email address, first name, or last name don't match, the instance updates the details with values from the IdP.

Supported identity providers

The following IdPs support user provisioning with SCIM for GitHub Enterprise Server.

Note: SCIM support for the following IdPs is currently in private beta and is subject to change.

IdPSAMLUser provisioningTeam mapping
Azure Active Directory (Azure AD)
Okta

Prerequisites

  • 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 dedicated machine 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. If you grant the user access to your instance from your IdP and the user authenticates successfully, the user's account will be unsuspended.

  1. Create a dedicated machine 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 with admin:enterprise scope. For more information, see "Creating a personal access token."

    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. For more information about SSH access, see "Accessing the administrative shell (SSH)."

    $ 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.

    Configuring your instance

  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. GitHub provides documentation for configuring provisioning for the following IdPs.

    IdPMore information
    Azure ADTo configure Azure AD for GitHub Enterprise Server, see "Configuring authentication and provisioning for your enterprise using Azure AD."
    OktaTo configure Okta for GitHub Enterprise Server, see "Configuring authentication and provisioning for your enterprise using Okta."

    The application on your IdP requires two values to provision or deprovision user accounts on your GitHub Enterprise Server instance.

    ValueOther namesDescriptionExample
    URLTenant URLURL to the SCIM provisioning API for your enterprise on GitHub AEhttp(s)://HOSTNAME/api/v3/scim/v2
    Shared secretPersonal access token, secret tokenToken for application on your IdP to perform provisioning tasks on behalf of an enterprise ownerPersonal access token you created in step 4