About 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 either install and configure a provisioning application on your IdP, or configure SCIM provisioning manually using GitHub's REST API endpoints for SCIM.

Supported identity providers

GitHub partners with some developers of identity management systems to provide a "paved-path" integration with GitHub Enterprise Server. To simplify your configuration and ensure full support, use a single partner IdP for both authentication and provisioning.

Partner identity providers

The following IdPs are partner IdPs. They offer an application that you can use to configure both SAML authentication and SCIM provisioning.

• Microsoft Entra ID
• Okta
• PingFederate (beta)

When you use a single partner IdP for both authentication and provisioning, GitHub provides support for the application on the partner IdP and the IdP's integration with GitHub. Support for PingFederate is in beta.

Other identity management systems

If you cannot use a single partner IdP for both authentication and provisioning, you can use another identity management system or combination of systems. The system must:

• Adhere to GitHub's integration guidelines
• Provide authentication using SAML, adhering to SAML 2.0 specification
• Provide user lifecycle management using SCIM, adhering to the SCIM 2.0 specification and communicating with GitHub's REST API (see Provisioning users and groups with SCIM using the REST API)

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.

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

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.

What happens if I disable SCIM?

SCIM will be disabled on your instance if any of the following things happens.

• The Enable SCIM configuration checkbox is unselected on the "Authentication security" page in the enterprise settings.
• The SAML radio button is unselected in the "Authentication" section of the Management Console.
• The SAML Issuer or Single sign-on URL field is updated in the "Authentication" section of the Management Console.

If SCIM is disabled on the instance:

• Requests to the SCIM API endpoints on your instance will no longer succeed.
• SCIM-provisioned users will remain unchanged and will not be suspended.
• Site administrators will be able to manage the lifecycle of SCIM-provisioned users, such as suspension and deletion, from the site admin dashboard.
• Users will still be able to sign on via SAML, if enabled.
• Users will be unlinked from their external identity record, and the record will be deleted.

Getting started

To get started with SCIM, you will:

1. Complete initial setup, required regardless of which IdP you will use, in Configuring SCIM provisioning to manage users.
2. Configure settings in your IdP.
   • If you're using a partner IdP for authentication and provisioning, you'll follow a guide for your IdP.
   • Otherwise, you'll set up a SCIM integration with the REST API, as described in Provisioning users and groups with SCIM using the REST API.