Skip to main content

Configuring user provisioning with SCIM for your enterprise

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

Qui peut utiliser cette fonctionnalité ?

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

Remarque : SCIM pour GitHub Enterprise Server est en version bêta privée et est susceptible de changer. Pour accéder à la bêta, contactez votre responsable de compte dans l’L’équipe commerciale GitHub. Merci de nous faire part de vos commentaires dans la discussion GitHub Community.

Avertissement : La bêta est exclusivement destinée aux tests et aux commentaires. Aucun support n’est disponible. GitHub recommande d’effectuer les tests avec une instance de préproduction. Pour plus d’informations, consultez « Setting up a staging instance ».

About user provisioning for GitHub Enterprise Server

If you use SAML single sign-on (SSO) for votre instance GitHub Enterprise Server, 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 votre instance GitHub Enterprise Server 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 votre instance GitHub Enterprise Server 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 "Points de terminaison d’API REST pour SCIM."

About identities and claims

After an IdP administrator grants a person access to votre instance GitHub Enterprise Server, 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 existing 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 username claim for each user account provisioned by SCIM on the instance.

During SAML authentication, some environments may use a value other than NameID as the unique identifying claim. If your environment does not use NameID to 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."

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

Supported identity providers

During the private beta, your account team will provide documentation for the configuration of SCIM for GitHub Enterprise Server on a supported IdP.

Prerequisites

  • Vous devez configurer l’authentification SSO SAML pour votre instance GitHub Enterprise Server. Pour plus d’informations, consultez « Configuring SAML single sign-on for your enterprise ».

  • You must allow built-in authentication for users who don't have an account on your IdP. For more information, see "Allowing built-in authentication for users outside your provider."

  • Your IdP must support making SCIM calls to a Service Provider (SP).

  • 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 built-in 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. The built-in user account will continue to perform provisioning actions. After you grant a user access to your instance from your IdP, the IdP will communicate with the instance using SCIM to unsuspend the user's account.

  1. Create a built-in 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 "Inviter des personnes à gérer votre entreprise."

  3. Sign into your instance as the new enterprise owner.

  4. Create a personal access token (classic) with admin:enterprise scope. Do not specify an expiration date for the personal access token (classic). For more information, see "Gestion de vos jetons d'accès personnels."

    Warning: Ensure that you don't specify an expiration date for the personal access token (classic). If you specify an expiration date, SCIM will no longer function after the expiration date passes.

    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. Connexion SSH à votre instance GitHub Enterprise Server. Si votre instance comprend plusieurs nœuds, par exemple si la haute disponibilité ou la géoréplication sont configurées, connectez-vous via SSH au nœud principal. Si vous utilisez un cluster, vous pouvez vous connecter via SSH à n’importe quel nœud. Remplacez HOSTNAME par le nom d’hôte de votre instance, le nom d’hôte ou l’adresse IP d’un nœud. Pour plus d’informations, consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

    Shell
    ssh -p 122 admin@HOSTNAME
    
  6. To enable SCIM, run the commands provided to you by your account manager on L’équipe commerciale GitHub.

  7. Attendez la fin de l’exécution de la configuration.

  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. To request documentation for a supported IdP, contact your account manager on L’équipe commerciale GitHub. If your IdP is unsupported, you must create the application and configure SCIM manually.