Configuring SCIM provisioning to manage users

You can manage the lifecycle of your enterprise's user accounts from your identity provider (IdP) using System for Cross-domain Identity Management (SCIM).

Who can use this feature?

Site administrators

In this article

Note

SCIM for GitHub Enterprise Server is currently in beta and subject to change. GitHub recommends testing with a staging instance first. See Setting up a staging instance.

To create, manage, and deactivate user accounts for your enterprise members on GitHub, your IdP can implement SCIM for communication with GitHub. SCIM is an open specification for management of user identities between systems. Different IdPs provide different experiences for the configuration of SCIM provisioning.

If you use a partner IdP, you can simplify the configuration of SCIM provisioning by using the partner IdP's application. If you don't use a partner IdP for provisioning, you can implement SCIM using calls to GitHub's REST API for SCIM. For more information, see About user provisioning with SCIM on GitHub Enterprise Server.

Who needs to follow these instructions?

Even if your instance already uses SAML authentication, or if you were enrolled in the SCIM private beta on a previous GitHub Enterprise Server version, you must ensure you have followed all instructions in this guide to enable SCIM in version 3.14 and later.

This guide applies in any of the following situations.

  • You're setting up SAML and SCIM for the first time: you'll follow these instructions to get started.
  • You already use SAML authentication: you'll need to enable SCIM on your instance, plus either reconfigure SAML with an IdP application that supports automated provisioning or set up a SCIM integration with the REST API.
  • You were enrolled in the SCIM private beta: you'll need to reenable SCIM on your instance and, if you're using a partner IdP, reconfigure your settings on an updated IdP application.

Prerequisites

  • For authentication, your instance must use SAML SSO, or a mix of SAML and built-in authentication.
    • You cannot mix SCIM with other external authentication methods. If you use CAS or LDAP, you will need to migrate to SAML before using SCIM.
    • After you have configured SCIM, you must keep SAML authentication enabled to continue using SCIM.
  • You must have administrative access on your IdP to configure user provisioning for GitHub Enterprise Server.
  • You must have access to the Management Console on GitHub Enterprise Server.
  • If you are configuring SCIM on an instance with existing users, ensure you have understood how SCIM will identify and update these users. See About user provisioning with SCIM on GitHub Enterprise Server.

1. Create a built-in setup user

To ensure you can continue to sign in and configure settings when SCIM is enabled, you'll create an enterprise owner using built-in authentication.

  1. Sign in to GitHub Enterprise Server as a user with access to the Management Console.

  2. If you have already enabled SAML authentication, ensure your settings allow you to create and promote a built-in setup user. Go to the "Authentication" section of the Management Console and enable the following settings:

    • Select Allow creation of accounts with built-in authentication, so you can create the user.
    • Select Disable administrator demotion/promotion, so admin permissions can be granted outside of your SAML provider.

    For help finding these settings, see Configuring SAML single sign-on for your enterprise.

  3. Create a built-in user account to perform provisioning actions on your instance. See Allowing built-in authentication for users outside your provider.

    Note

    Ensure the user's email and username are different from any user you plan on provisioning through SCIM. If your email provider supports it, you can modify an email address by adding +admin, for example johndoe+admin@example.com.

  4. Promote the user to an enterprise owner. See Promoting or demoting a site administrator.

2. Create a personal access token

  1. Sign in to your instance as the built-in setup user you created in the previous section.

  2. Create a personal access token (classic). For instructions, see Managing your personal access tokens.

    • The token must have the admin:enterprise scope.
    • The token must have no expiration. If you specify an expiration date, SCIM will no longer function after the expiration date passes.

  3. Store the token securely in a password manager until you need the token again later in the setup process. You'll need the token to configure SCIM on your IdP.

3. Enable SAML on your instance

Note

Complete this section if either of the following situations applies:

  • If you have not already enabled SAML authentication, you will need to do so before you can enable SCIM.
  • If you already use SAML authentication and want to use a partner IdP for both authentication and provisioning, or if you're upgrading from the SCIM private beta, you must reconfigure SAML using a new application.

  1. Sign in to your instance as a user with access to the Management Console.

  2. Go to the "Authentication" section of the Management Console. For instructions, see Configuring SAML single sign-on for your enterprise.

  3. Select SAML.

  4. Configure the SAML settings according to your requirements and the IdP you're using.

  5. Optionally, complete configuration of the SAML settings within the application in your IdP. Alternatively, you can leave this step until later.

4. Enable SCIM on your instance

  1. Sign in to your instance as the built-in setup user you created earlier.

  2. In the top-right corner of GitHub, click your profile photo, then click Your enterprise.

  3. On the left side of the page, in the enterprise account sidebar, click Settings.

  4. Under Settings, click Authentication security.

  5. Under "SCIM Configuration", select Enable SCIM configuration.

5. Configure your identity provider

After completing the setup on GitHub, you can configure provisioning on your IdP. The instructions you should follow differ depending on whether you use a partner IdP's application for both authentication and provisioning.

Configuring provisioning if you use a partner IdP's application

To use a partner IdP's application for both authentication and provisioning, review the instructions that are linked below. Complete the steps for enabling SCIM, plus any SAML configuration that you haven't already performed.

Configuring provisioning for other identity management systems

If you don't use a partner IdP, or if you only use a partner IdP for authentication, you can manage the lifecycle of user accounts using GitHub's REST API endpoints for SCIM provisioning. See Provisioning users and groups with SCIM using the REST API.

6. Disable optional settings

After you have finished the configuration process, you can disable the following settings in the Management Console:

  • Allow creation of accounts with built-in authentication: Disable this setting if you want all users to be provisioned from your IdP.
  • Disable administrator demotion/promotion: Disable this setting if you want to be able to grant the enterprise owner role via SCIM.

7. Assign users and groups

After you have configured authentication and provisioning, you will be able to provision new users on GitHub by assigning users or groups to the relevant application in your IdP.

When assigning users, you can use the "Roles" attribute in the application on your IdP to set a user's role in your enterprise on GitHub Enterprise Server. For more information about the roles available to assign, see Roles in an enterprise.

Entra ID does not support provisioning nested groups. For more information, see How Application Provisioning works in Microsoft Entra ID on Microsoft Learn.