Skip to content

Latest commit

 

History

History
208 lines (135 loc) · 13.9 KB

configuring-scim-provisioning-for-users.md

File metadata and controls

208 lines (135 loc) · 13.9 KB
title shortTitle intro allowTitleToDifferFromFilename permissions product redirect_from versions topics
Configuring SCIM provisioning {% ifversion ghec %}for Enterprise Managed Users{% else %}to manage users{% endif %}
Configure SCIM provisioning
You can manage the lifecycle of your enterprise's user accounts from your identity provider (IdP) using System for Cross-domain Identity Management (SCIM).
true
{% ifversion scim-for-ghes-public-beta %}Site administrators{% endif %}
{% data reusables.gated-features.emus %}
/github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
/admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
/admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users
/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users
/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
/admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
ghec feature
*
scim-for-ghes-public-beta
Accounts
Enterprise

{% data reusables.scim.ghes-beta-note %}

{% data reusables.enterprise_user_management.about-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 {% data variables.product.company_short %}'s REST API for SCIM. For more information, see {% ifversion ghec %}AUTOTITLE.{% else %}AUTOTITLE.{% endif %}

{% ifversion ghes %}

Who needs to follow these instructions?

Even if your instance already uses SAML authentication, or if you were enrolled in the SCIM {% data variables.release-phases.private_preview %} on a previous {% data variables.product.prodname_ghe_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 {% data variables.release-phases.private_preview %}: 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.

{% endif %}

{% ifversion ghec %}

About user lifecycle management with SCIM

{% data reusables.enterprise_user_management.scim-manages-user-lifecycle %}

{% endif %}

Prerequisites

{% ifversion ghec %}

If you're configuring SCIM provisioning for a new enterprise, make sure to complete all previous steps in the initial configuration process. See AUTOTITLE.

{% else %}

  • 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.
  • You must have access to the Management Console on {% data variables.product.prodname_ghe_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 AUTOTITLE.

{% endif %}

{% ifversion ghes %}

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 {% data variables.product.prodname_ghe_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 AUTOTITLE.

  3. Create a built-in user account to perform provisioning actions on your instance. See AUTOTITLE.

    [!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 AUTOTITLE.

2. Create a {% data variables.product.pat_generic %}

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

  2. Create a {% data variables.product.pat_v1 %}. For instructions, see AUTOTITLE.

    • The token must have the {% ifversion scim-enterprise-scope %}scim:enterprise{% else %}admin:enterprise{% endif %} 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 {% data variables.release-phases.private_preview %}, 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 AUTOTITLE.

  3. Select SAML.

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

    • So the built-in setup user can continue to authenticate, ensure you select the following settings:
      • Allow creation of accounts with built-in authentication
      • Disable administrator demotion/promotion
    • If you're using a partner IdP, to find the information you need to configure the settings, follow the "Configure SAML" section of the relevant guide.

  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. {% data reusables.enterprise-accounts.access-enterprise-emu %} {% data reusables.enterprise-accounts.settings-tab %} {% data reusables.enterprise-accounts.security-tab %}
  2. Under "SCIM Configuration", select Enable SCIM configuration.

{% endif %}

{% ifversion ghec %}

Configuring user provisioning for {% data variables.product.prodname_emus %}

{% else %}

5. Configure your identity provider

{% endif %}

After completing the setup on {% data variables.product.prodname_dotcom %}, 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

{% ifversion ghec %}

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

{% rowheaders %}

IdP SSO method Instructions
Microsoft Entra ID (previously known as Azure AD) OIDC Tutorial: Configure GitHub Enterprise Managed User (OIDC) for automatic user provisioning on Microsoft Learn
Entra ID SAML Tutorial: Configure GitHub Enterprise Managed User for automatic user provisioning on Microsoft Learn
Okta SAML AUTOTITLE
PingFederate SAML The "Prerequisites" and "2. Configure SCIM" sections in AUTOTITLE

{% endrowheaders %}

{% else %}

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.

{% endif %}

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 {% data variables.product.company_short %}'s REST API endpoints for SCIM provisioning. See AUTOTITLE.

{% ifversion emu-public-scim-schema %}

{% data reusables.emus.sign-in-as-setup-user %}

Note

{% data reusables.enterprise-accounts.emu-password-reset-session %}

{% data reusables.enterprise-accounts.access-enterprise-emu %} {% data reusables.enterprise-accounts.identity-provider-tab %} {% data reusables.enterprise-accounts.sso-configuration %}

  1. Under "Open SCIM Configuration", select "Enable open SCIM configuration".
  2. Manage the lifecycle of your users by making calls to the REST API endpoints for SCIM provisioning. See AUTOTITLE.

{% endif %}

{% ifversion scim-for-ghes-public-beta %}

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.

{% endif %}

{% ifversion ghec %}Assigning{% else %}7. Assign{% endif %} users and groups

{% data reusables.enterprise-managed.assigning-users %}

{% data reusables.enterprise-managed.assigning-roles %}

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