Configuring SCIM provisioning for Enterprise Managed Users

In this article

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

To manage users in your enterprise with your identity provider, your enterprise must be enabled for Enterprise Managed Users, which is available with GitHub Enterprise Cloud. For more information, see "About Enterprise Managed Users."

About provisioning for Enterprise Managed Users

To create, manage, and deactivate user accounts for your enterprise members on GitHub.com, your IdP must 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.

After you configure provisioning for Enterprise Managed Users, your IdP uses SCIM to provision user accounts on GitHub.com and add the accounts to your enterprise. If you assign a group to the application, your IdP will provision new managed user accounts for all members of the group.

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, which is in beta and subject to change. For more information, see "About Enterprise Managed Users."

SCIM manages the lifecycle of user accounts in your enterprise. When you update information associated with a user's identity on your IdP, your IdP will update the user's account on GitHub.com. When you unassign the user from the IdP application for Enterprise Managed Users 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 with the short code appended. If you reassign a user to the IdP application for Enterprise Managed Users or reactivate their account on your IdP, the managed user account on GitHub will be reactivated, and the username will be restored.

To configure team and organization membership, repository access, and permissions on GitHub Enterprise Cloud, you can use groups on your IdP. For more information, see "Managing team memberships with identity provider groups."

Prerequisites

  • Before you configure provisioning, you must configure authentication. For more information, see "Configuring authentication for Enterprise Managed Users."

  • Before you configure provisioning, ensure that you understand the integration requirements and level of support for your IdP. For more information, see "About Enterprise Managed Users."

  • After you initially configure authentication and provisioning, GitHub does not recommend migration to a different platform for authentication or provisioning. If you need to migrate an existing enterprise to a different platform for authentication or provisioning, contact your account manager on GitHub's Sales team.

Creating a personal access token

To configure provisioning for your enterprise with managed users, you need a personal access token (classic) with the admin:enterprise scope that belongs to the setup user.

Warning: If the token expires or a provisioned user creates the token, SCIM provisioning may unexpectedly stop working. Make sure that you create the token while signed in as the setup user and that the token expiration is set to "No expiration".

  1. Sign into GitHub.com as the setup user for your new enterprise with the username @SHORT-CODE_admin.

  2. In the upper-right corner of any page, click your profile photo, then click Settings.

    Screenshot of a user's account menu on GitHub. The menu item "Settings" is outlined in dark orange.

  3. In the left sidebar, click Developer settings.

  4. In the left sidebar, click Personal access tokens.

  5. Click Generate new token.

  6. Under Note, give your token a descriptive name.

  7. Select the Expiration dropdown menu, then click No expiration.

  8. Select the admin:enterprise scope. Screenshot of a list of scopes with checkboxes. The "admin:enterprise" scope, accompanied by the text "Full control of enterprises," is selected and highlighted with an orange outline.

  9. Click Generate token.

  10. To copy the token to your clipboard, click .

    Screenshot of the "Personal access tokens" page. Next to a blurred-out token, an icon of two overlapping squares is outlined in orange.

  11. To save the token for use later, store the new token securely in a password manager.

Configuring provisioning for Enterprise Managed Users

After creating your personal access token and storing it securely, you can configure provisioning on your IdP. The instructions you should follow differ depending on whether you use a partner IdP for provisioning.

Configuring provisioning if you use a partner IdP

To use a partner IdP's application both authentication and provisioning, review the parner's instructions for configuring provisioning in the links in the following table.

IdPSSO methodMore information
Azure ADOIDCTutorial: Configure GitHub Enterprise Managed User (OIDC) for automatic user provisioning in the Azure AD documentation
Azure ADSAMLTutorial: Configure GitHub Enterprise Managed User for automatic user provisioning in the Azure AD documentation
OktaSAML"Configuring SCIM provisioning with Okta"
PingFederateSAMLConfigure PingFederate for provisioning and SSO and Managing channels in the PingFederate documentation

Alternatively, if you configured authentication on a partner IdP, but you would like to provision users from a different IdP, you can have your IdP make calls to GitHub's REST API for SCIM.

Configuring provisioning if don't use a partner IdP

If you don't use a partner IdP, you can integrate with GitHub's REST API for SCIM. The API is in beta and subject to change. For more information, see "Provisioning users with SCIM using the REST API."

Assigning users and groups

After you have configured SAML SSO and provisioning, you will be able to provision new users on GitHub.com by assigning users or groups to the GitHub Enterprise Managed User application.

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

Azure AD does not support provisioning nested groups. For more information, see How Application Provisioning works in Azure Active Directory in Microsoft Docs.