Approvisionnement des utilisateurs et des groupes avec SCIM à l'aide de l'API REST

Gérez le cycle de vie des comptes d’utilisateurs de votre fournisseur d’identité à l’aide de l’API REST de GitHub pour System for Cross-domain Identity Management (SCIM).

Qui peut utiliser cette fonctionnalité ?

Enterprise Managed Users est disponible pour les nouveaux comptes d'entreprise sur GitHub Enterprise Cloud. Consulter « À propos d’Enterprise Managed Users ».

Dans cet article

Note

GitHub vous recommande de tester l’approvisionnement dans un environnement isolé des données de production sur votre fournisseur d’identité et GitHub.

À propos d'IAM pour Enterprise Managed Users

Si votre entreprise sur GitHub est créée pour Enterprise Managed Users, vous devez configurer un système de gestion de l'identité externe pour fournir et gérer les comptes utilisateurs. Votre système de gestion des identités doit offrir les fonctionnalités suivantes :

  • Authentification unique implémentant l'une des deux normes d'authentification unique (SSO) suivantes :
    • Security Assertion Markup Language (SAML) 2.0
    • OpenID Connect (OIDC), qui est uniquement pris en charge si vous utilisez Microsoft Entra ID (précédemment appelé Azure AD)
  • Gestion du cycle de vie des utilisateurs avec System for Cross-domain Identity Management (SCIM)

Lorsque vous configurez l'authentification et l'approvisionnement pour votre entreprise, vous pouvez utiliser un fournisseur d'identité partenaire ou utiliser une autre combinaison de systèmes de gestion des identités.

Utilisation d'un fournisseur d'identité partenaire

Chaque fournisseur d'identité partenaire fournit une application « paved-path », qui implémente à la fois l'authentification unique et la gestion du cycle de vie des utilisateurs. Pour simplifier la configuration, GitHub vous recommande d’utiliser l’application d’un IdP partenaire pour l’authentification et l’approvisionnement. Pour plus d’informations et une liste des IdP partenaires, consultez « À propos d’Enterprise Managed Users ».

Pour plus d'informations sur la configuration de l'approvisionnement SCIM à l'aide d'un idP partenaire, consultez « Configurer l’approvisionnement SCIM pour les utilisateurs gérés par l’entreprise ».

Utilisation d'autres systèmes de gestion des identités

Si vous ne pouvez pas utiliser un fournisseur d'identité partenaire pour l'authentification et l'approvisionnement en raison de la surcharge de migration, des coûts de licence ou de l'inertie organisationnelle, vous pouvez utiliser un autre système de gestion des identités ou une combinaison de systèmes. Les systèmes doivent assurer l'authentification à l'aide de SAML et la gestion du cycle de vie des utilisateurs à l'aide de SCIM. Ils doivent également suivre les recommandations d'intégration de GitHub.

GitHub n'a pas testé l'intégration avec tous les systèmes de gestion de l'identité. Bien que l’intégration avec Enterprise Managed Users soit possible, l’équipe de support de GitHub peut ne pas être en mesure de vous aider à résoudre les problèmes liés à ces systèmes. Si vous avez besoin d'aide pour un système de gestion des identités qui n'est pas un fournisseur d'identité partenaire ou si vous utilisez un fournisseur d'identité partenaire uniquement pour l'authentification SAML, vous devez consulter la documentation du système, l'équipe de support technique ou d'autres ressources.

Prérequis

Meilleures pratiques pour l'approvisionnement SCIM avec l'API REST de GitHub

Lorsque vous configurez votre système de gestion des identités pour fournir des utilisateurs ou des groupes d'utilisateurs sur GitHub Enterprise Cloud, GitHub recommande vivement de suivre les recommandations suivantes.

Vérifiez que votre système de gestion des identités est la seule source d'opérations d'écriture

Pour vous assurer que votre environnement a une source unique de vérité, vous devez uniquement écrire par programmation dans l'API REST pour l'approvisionnement SCIM à partir de votre système de gestion des identités. GitHub recommande vivement qu'un seul système envoie POST, PUT, PATCH ou DELETE demandes à l'API.

Toutefois, vous pouvez récupérer en toute sécurité des informations à partir des API de GitHub avec GET demandes dans des scripts ou des demandes ad hoc par un propriétaire d'entreprise.

Warning

Si vous utilisez un fournisseur d'identité partenaire pour l'approvisionnement SCIM, l'application sur le fournisseur d'identité doit être le seul système qui effectue des demandes d'écriture à l'API. Si vous effectuez des demandes ad hoc en utilisant les méthodes POST, PUT, PATCH, ou DELETE, les tentatives de synchronisation ultérieures échoueront et l'approvisionnement ne fonctionnera pas comme prévu pour votre entreprise.

Envoyer des demandes valides aux points de terminaison de l'API REST

Les points de terminaison de l'API REST de GitHub pour l'approvisionnement des utilisateurs avec le SCIM nécessitent des requêtes bien formées. Gardez à l'esprit les recommandations suivantes :

  • Les demandes qui ne correspondent pas aux attentes de l'API retournent une erreur 400 Bad Request.
  • Les points de terminaison d'API REST pour l'approvisionnement d'utilisateurs avec SCIM nécessitent un en-tête User-Agent. GitHub Enterprise Cloud rejette les demandes sans cet en-tête.
  • Si votre entreprise se trouve sur GHE.com, assurez-vous d’envoyer les demandes d’API au point de terminaison de votre entreprise, àapi.SUBDOMAIN.ghe.com.

Approvisionnez les utilisateurs avant d'approvisionner les groupes

Les groupes SCIM sont efficaces pour la gestion de l'accès utilisateur à grande échelle. Par exemple, vous pouvez utiliser des groupes sur votre système de gestion des identités pour gérer l'appartenance à l'équipe et à l'organisation sur GitHub Enterprise Cloud.

Pour gérer l'appartenance à l'équipe avec des groupes sur votre système de gestion des identités, vous devez effectuer les étapes suivantes de manière séquentielle :

  1. Approvisionnez les comptes utilisateurs sur GitHub Enterprise Cloud.
  2. Approvisionnez un groupe sur GitHub Enterprise Cloud.
  3. Mettez à jour l'appartenance au groupe sur votre système de gestion des identités.
  4. Créez une équipe sur GitHub Enterprise Cloud mappées au groupe sur votre système de gestion des identités.

Valider l’accès pour les groupes sur GitHub

vous gérez l'accès à l'aide de groupes dans votre système de gestion des identités, vous pouvez vérifier que les utilisateurs obtiennent l'accès que vous souhaitez. Vous pouvez utiliser l'API REST pour comparer les appartenance aux groupes de votre système à la présentation de GitHub de ces groupes. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les groupes externes » et « Points de terminaison d’API REST pour les équipes » dans la documentation de l’API REST.

Comprendre les limites de taux dans GitHub

Pour assurer la disponibilité et la fiabilité de la plateforme, GitHub implémente les limites de débit.

Sans tenir compte des limites de débit, les grandes entreprises qui utilisent Enterprise Managed Users pour la première fois sont susceptibles de dépasser les limites. Pour éviter de dépasser la limitation de débit sur GitHub Enterprise Cloud, n’affectez pas plus de 1 000 utilisateurs par heure à l’intégration SCIM de votre IdP. Si vous utilisez des groupes pour affecter des utilisateurs à l’application IdP, n’ajoutez pas plus de 1 000 utilisateurs à chaque groupe par heure. Si vous dépassez ces seuils, les tentatives de provisionnement d’utilisateurs peuvent échouer avec une erreur « limite de débit ». Vous pouvez consulter les journaux de votre fournisseur d’identité pour vérifier si une tentative de provisionnement SCIM ou d’opérations de poussée a échoué en raison d’une erreur de limite de débit. La réponse à une tentative de provisionnement ayant échoué dépend du fournisseur d’identité.

Pour plus d’informations, consultez « Limites de débit pour l'API REST ».

Configurer la diffusion en continu des journaux d'audit

Le journal d’audit de votre entreprise affiche des détails sur l’activité dans votre entreprise. Vous pouvez utiliser le journal d’audit pour prendre en charge votre configuration de SCIM. Pour plus d’informations, consultez « À propos du journal d’audit de votre entreprise ».

En raison du volume d’événements dans ce journal, GitHub conserve les données pendant 180 jours. Pour vous assurer que vous ne perdez pas les données du journal d’audit et pour afficher une activité plus granulaire dans le journal d’audit, GitHub vous recommande de configurer le streaming du journal d’audit. Lorsque vous diffusez en continu le journal d'audit, vous pouvez éventuellement choisir de diffuser des événements pour les demandes d'API, y compris les demandes adressées aux points de terminaison de l'API REST pour l'approvisionnement SCIM. Pour plus d’informations, consultez « Streaming de journaux d’audit pour votre entreprise ».

Limiter l’étendue du jeton SCIM

Pour une meilleure posture de sécurité, nous vous recommandons d’utiliser un personal access token (classic) avec uniquement l’étendue scim:enterprise pour limiter l’accès du jeton aux points de terminaison de l’API REST requis pour effectuer des appels SCIM.

Si vous utilisez actuellement un jeton avec l’étendue admin:enterprise, sachez que ce jeton accorde l’accès à toutes les actions sur l’entreprise. Vous pouvez échanger votre jeton pour un nouveau jeton avec seulement l’étendue scim:enterprise sans interruption.

Approvisionnement d'utilisateurs avec l'API REST

Pour approvisionner, référencer ou gérer des utilisateurs, adressez des requêtes aux points de terminaison suivants de l'API REST. Vous pouvez lire les points de terminaison d'API associés dans la documentation de l'API REST et consulter des exemples de code. Vous pouvez en outre consulter les événements du journal d'audit associés à chaque requête.

Avant qu'une personne disposant d'une identité sur votre système de gestion des identités puisse se connecter à votre entreprise, vous devez créer l'utilisateur correspondant. Votre entreprise ne nécessite pas de licence disponible pour approvisionner un nouveau compte d'utilisateur.

  • Pour obtenir une vue d'ensemble des attributs pris en charge pour les utilisateurs, consultez « SCIM » dans la documentation de l'API REST.
  • Vous pouvez afficher les utilisateurs approvisionnés dans l'IU Web pour GitHub Enterprise Cloud. Pour plus d’informations, consultez « Visualisation des personnes dans votre entreprise ».
ActionMethodPoint de terminaison et plus d’informationsÉvénements dans le journal d'audit
Référencez tous les utilisateurs approvisionnés pour votre entreprise, ce qui inclut tous les utilisateurs qui sont déprovisionnés de la version réversible en définissant active sur false.GET/scim/v2/enterprises/{enterprise}/UsersS/O
Créez un utilisateur. La réponse de l'API inclut un champ id permettant d'identifier l'utilisateur de manière unique.POST/scim/v2/enterprises/{enterprise}/Users
  • external_identity.provision
  • user.create
  • Si la demande ajoute le rôle enterprise_owner, business.add_admin
  • Si la demande ajoute le rôle billing_manager, business.add_billing_manager
  • Si la requête réussit, external_identity.scim_api_success
  • Si la requête échoue, external_identity.scim_api_failure
Récupérez un utilisateur existant dans votre entreprise à l'aide du champ id de la demande POST que vous avez envoyée pour créer l'utilisateur.GET/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}S/O
Mettez à jour tous les attributs d'un utilisateur existant à l'aide du champ id de la demande POST que vous avez envoyée pour créer l'utilisateur. Mettez à jour active pour false afin de procéder à un déprovisionnement de la version réversible de l'utilisateur, ou true pour réactiver l'utilisateur. Pour plus d’informations, consultez « Déprovisionnement réversible des utilisateurs avec l’API REST » et « Réactivation des utilisateurs avec l’API REST ».PUT/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.update, à moins qu'il ne s'agisse d'un déprovisionnement réversible ou d'un reprovisionnement
  • Si la demande ajoute le rôle enterprise_owner, business.add_admin
  • Si la demande ajoute le billing_manager, business.add_billing_manager
  • Si la demande supprime le rôle enterprise_owner, business.remove_admin
  • Si la demande supprime le rôle billing_manager, business.remove_billing_manager
  • Si la requête réussit, external_identity.scim_api_success
  • Si la requête échoue, external_identity.scim_api_failure
Mettez à jour un attribut individuel pour un utilisateur existant en utilisant le champ id de la demande POST que vous avez envoyée pour créer l'utilisateur. Mettez à jour active pour false afin de procéder à un déprovisionnement de la version réversible de l'utilisateur, ou true pour réactiver l'utilisateur. Pour plus d’informations, consultez « Déprovisionnement réversible des utilisateurs avec l’API REST » et « Réactivation des utilisateurs avec l’API REST ».PATCH/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.update, à moins qu'il ne s'agisse d'un déprovisionnement réversible ou d'un reprovisionnement
  • Si la demande ajoute le rôle enterprise_owner, business.add_admin
  • Si la demande ajoute le billing_manager, business.add_billing_manager
  • Si la demande supprime le rôle enterprise_owner, business.remove_admin
  • Si la demande supprime le rôle billing_manager, business.remove_billing_manager
  • Si la requête réussit, external_identity.scim_api_success
  • Si la requête échoue, external_identity.scim_api_failure
Pour supprimer complètement un utilisateur existant, vous pouvez déprovisionner de manière irréversible l'utilisateur. Après le déprovisionnement irréversible, vous ne pouvez pas réactiver l'utilisateur et vous devez approvisionner l'utilisateur en tant que nouvel utilisateur. Pour plus d'informations, consultez « Déprovisionnement irréversible des utilisateurs à l'aide de l'API REST. »DELETE/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.deprovision
  • user.remove_email
  • Si la requête réussit, external_identity.scim_api_success
  • Si la requête échoue, external_identity.scim_api_failure

Déprovisionnement réversible des utilisateurs avec l'API REST

Pour empêcher un utilisateur de se connecter pour accéder à votre entreprise, vous pouvez déprovisionner de manière réversible l'utilisateur en envoyant demande PUT ou PATCH de mise à jour du champ active d'un utilisateur à false à /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}. Lorsque vous déprovisionnez de manière réversible un utilisateur, GitHub Enterprise Cloud obfusque les champs login et email de l'enregistrement de l'utilisateur, et le compte de ce dernier est suspendu.

Lorsque vous déprovisionnez de manière réversible un utilisateur, l'événement external_identity.update n'apparaît pas dans le journal d'audit. Les événements suivants s'affichent dans le journal d'audit :

  • user.suspend
  • user.remove_email
  • user.rename
  • external_identity.deprovision
  • Si la demande réussit, external_identity.scim_api_success
  • Si la requête échoue, external_identity.scim_api_failure

Vous pouvez afficher tous les utilisateurs suspendus pour votre entreprise. Pour plus d’informations, consultez « Visualisation des personnes dans votre entreprise ».

Réactiver les utilisateurs avec l'API REST

Pour autoriser un utilisateur deprovisionné de manière réversible à se connecter pour accéder à votre entreprise, rétablissez les accès de l'utilisateur en envoyant une demande PUT ou PATCH à /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} qui met à jour le champ active de l'utilisateur sur true.

Lorsque vous réactivez de manière réversible un utilisateur, l'événement external_identity.update n'apparaît pas dans le journal d'audit. Les événements suivants s'affichent dans le journal d'audit :

  • user.unsuspend
  • user.remove_email
  • user.rename
  • external_identity.provision
  • Si la demande réussit, external_identity.scim_api_success
  • Si la requête échoue, external_identity.scim_api_failure

Déprovisionnement irréversible des utilisateurs avec l'API REST

Pour supprimer complètement un utilisateur, vous pouvez déprovisionner l'utilisateur de manière irréversible en envoyant une demande DELETE à /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}. Votre entreprise conserve toutes les ressources et commentaires créés par l'utilisateur.

Lorsque vous déprovisionnez de manière irréversible un utilisateur, les événements suivants se produisent :

  • Les champs login et email de l'enregistrement de l'utilisateur sont obfusqués.
  • Le nom complet de l'utilisateur est défini sur une chaîne vide.
  • GitHub Enterprise Cloud supprime tous les attributs SCIM de l'utilisateur, ses e-mails, ses clés SSH, personal access tokens et ses clés GPG.
  • Le compte de l'utilisateur sur GitHub Enterprise Cloud est suspendu, et l'authentification pour se connecter au compte échoue.

Pour réapprovisionner l'utilisateur, vous devez utiliser la méthode POST pour créer un nouvel utilisateur. Le nouvel utilisateur peut réutiliser les utilisateurs déprovisionnés login. Si les adresses e-mail de l'utilisateur déprovisionné de manière irréversible et du nouvel utilisateur correspondent, GitHub Enterprise Cloud attribuent des validations Git existantes associées à l'adresse e-mail au nouvel utilisateur. Les ressources et commentaires existants créés par l'utilisateur d'origine ne seront pas associés au nouvel utilisateur.

Approvisionnement d'utilisateurs avec l'API REST

Pour contrôler l'accès aux référentiels dans votre entreprise, vous pouvez utiliser les groupes de votre système de gestion des identités pour contrôler l'appartenance à une équipe et son organisation pour les utilisateurs de votre entreprise. Vous pouvez lire les points de terminaison d'API associés dans la documentation de l'API REST et consulter des exemples de code. Vous pouvez en outre consulter les événements du journal d'audit associés à chaque requête.

Bien que votre entreprise n’ait pas besoin d’une licence disponible pour approvisionner un nouveau compte utilisateur, si vous approvisionnez un groupe qui entraîne l’ajout d’utilisateurs à une organisation, vous devez disposer de licences disponibles pour ces utilisateurs. Si votre entreprise utilise uniquement Abonnements Visual Studio avec GitHub Enterprise, l’utilisateur associé doit être assigné à un abonné. Pour plus d’informations, consultez « À propos des abonnements Visual Studio avec GitHub Enterprise ».

ActionMethodPoint de terminaison et plus d’informationsÉvénements connexes dans le journal d'audit
Répertoriez tous les groupes définis pour votre entreprise.GET/scim/v2/enterprises/{enterprise}/GroupsS/O
Pour définir un nouveau groupe IdP pour votre entreprise, créez le groupe. La réponse de l'API inclut un champ id permettant d'identifier le groupe de manière unique.POST/scim/v2/enterprises/{enterprise}/Groups
  • external_group.provision
  • external_group.update_display_name
  • Si la demande incluait une liste d'utilisateurs, external_group.add_member
  • Si la requête réussit, external_group.scim_api_success
  • Si la requête échoue, external_group.scim_api_failure
Récupérez un groupe existant pour votre entreprise en utilisant le id de la demande POST que vous avez envoyée pour créer le groupe.GET/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}S/O
Mettez à jour tous les attributs d'un groupe existant.PUT/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.update
  • Si la demande met à jour le nom du groupe, external_group.update_display_name
  • Si la demande ajoute un utilisateur au groupe, external_group.add_member
  • Si la demande supprime un utilisateur du groupe, external_group.remove_member
  • Si la requête réussit, external_group.scim_api_success
  • Si la requête échoue, external_group.scim_api_failure
  • Des événements supplémentaires peuvent apparaître dans le journal d'audit selon que l'utilisateur est déjà membre de l'organisation avec l'équipe que vous avez liée au groupe IdP. Pour plus d'informations, consultez « Événements de journal d'audit supplémentaires pour les modifications apportées aux groupes IdP. »
Mettez à jour un attribut individuel pour un groupe existant.PATCH/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.update
  • Si la demande met à jour le nom du groupe, external_group.update_display_name
  • Si la demande ajoute un utilisateur au groupe, external_group.add_member
  • Si la demande supprime un utilisateur du groupe, external_group.remove_member
  • Si la requête réussit, external_group.scim_api_success
  • Si la requête échoue, external_group.scim_api_failure
  • Des événements supplémentaires peuvent apparaître dans le journal d'audit selon que l'utilisateur est déjà membre de l'organisation avec l'équipe que vous avez liée au groupe IdP. Pour plus d'informations, consultez « Événements de journal d'audit supplémentaires pour les modifications apportées aux groupes IdP. »
Supprimez complètement un groupe existant.DELETE/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.delete
  • Si la demande supprime un groupe lié à une équipe dans une organisation où l'utilisateur n'a pas d'autre appartenance à l'équipe, org.remove_member
  • Si la demande supprime un groupe lié à une équipe dans une organisation où l'utilisateur est membre d'une autre équipe, team.remove_member
  • Si la requête réussit, external_group.scim_api_success
  • Si la requête échoue, external_group.scim_api_failure

Événements de journal d'audit supplémentaires pour les modifications apportées aux groupes IdP

Si vous mettez à jour les membres d'un groupe existant à l'aide d'une demande PUT ou PATCH à /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}, GitHub Enterprise Cloud peut ajouter l'utilisateur à l'organisation ou le supprimer de l'organisation en fonction de l'appartenance actuelle de l'utilisateur à l'organisation. Si l'utilisateur est déjà membre d'au moins une équipe de l'organisation, l'utilisateur est membre de l'organisation. Si l'utilisateur n'est membre d'aucune équipe de l'organisation, il se peut également qu'il ne soit pas encore membre de l'organisation.

Si votre demande met à jour un groupe lié à une équipe dans une organisation dont l'utilisateur n'est pas encore membre, en plus de external_group.update, les événements suivants apparaissent dans le journal d'audit :

  • org.add_member
  • Si la demande ajoute un utilisateur à un groupe lié à une équipe dans une organisation où l'utilisateur n'est pas déjà membre, org.add_member
  • Si la demande ajoute l'utilisateur à un groupe lié à une équipe dans une organisation, team.add_member

Si votre demande met à jour un groupe lié à une équipe dans une organisation où un utilisateur est déjà membre, en plus de external_group.update, les événements suivants apparaissent dans le journal d'audit :

  • Si la demande supprime l'utilisateur d'un groupe lié à une équipe d'une organisation et que l'équipe n'est pas la dernière équipe de l'organisation où l'utilisateur est membre, team.remove_member
  • Si la demande supprime un utilisateur d'un groupe lié à la dernière équipe d'une organisation dont l'utilisateur est déjà membre, org.remove_member

Migration vers un nouveau fournisseur SCIM

Après avoir configuré l'approvisionnement SCIM pour votre entreprise, vous devrez peut-être migrer vers un nouveau fournisseur SCIM. Pour plus d’informations, consultez « Migration de votre entreprise vers un nouveau fournisseur d’identité ou locataire ».

Résolution des problèmes d'approvisionnement SCIM

Pour obtenir des suggestions de résolution des problèmes supplémentaires, consultez « Résolution des problèmes de gestion des identités et des accès pour votre entreprise .»