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

Dans cet article

Note

SCIM pour GitHub Enterprise Server est en version bêta publique et est susceptible de changer. GitHub recommande d’effectuer les tests avec une instance de préproduction d’abord. Consulter « Configuration d’une instance de préproduction ».

À propos de l’approvisionnement SCIM sur GitHub Enterprise Server

Pour approvisionner et gérer des comptes d’utilisateur à l’aide de SCIM, votre système de gestion des identités doit offrir les fonctionnalités suivantes :

  • Authentification unique implémentant Security Assertion Markup Language (SAML) 2.0
  • 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 de de l’attribution d’utilisateurs avec SCIM sur GitHub Enterprise Server ».

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

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 GitHub Enterprise Server 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

Pour implémenter SCIM à l’aide de l’API REST, les conditions générales préalables à l’utilisation de SCIM sur GitHub Enterprise Server s’appliquent. Consultez la section « Conditions préalables » dans « Configurer l’approvisionnement SCIM pour gérer les utilisateurs ».

En outre, prenez en compte les conditions préalables suivantes :

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

Avertissement : 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 Server rejette les demandes sans cet en-tête.

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

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 Server.
  2. Approvisionnez un groupe sur GitHub Enterprise Server.
  3. Mettez à jour l'appartenance au groupe sur votre système de gestion des identités.
  4. Créez une équipe sur GitHub Enterprise Server 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

Si un administrateur de site a activé les limites de débit sur votre instance, vous pouvez rencontrer des erreurs lorsque vous approvisionnez des utilisateurs pour la première fois. 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 ».

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 Server. 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/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/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/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/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/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/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/Users/{scim_user_id}. Lorsque vous déprovisionnez de manière réversible un utilisateur, GitHub Enterprise Server 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 demande é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/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 demande é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/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 Server 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 Server 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 Server 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.

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/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/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/Groups/{scim_group_id}S/O
Mettez à jour tous les attributs d'un groupe existant.PUT/scim/v2/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/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/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/Groups/{scim_group_id}, GitHub Enterprise Server 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

Résolution des problèmes d'approvisionnement SCIM

  • Si vos demandes à l’API REST sont limitées, vous pouvez en savoir plus dans « Comprendre les limites de débit sur GitHub ».

  • Si vous activez la diffusion en continu du journal d'audit et diffusez des événements pour les demandes d'API, vous pouvez passer en revue toutes les demandes adressées aux points de terminaison de l'API REST pour l'approvisionnement SCIM en filtrant les événements à partir des contrôleurs EnterpriseUsersScim ou EnterpriseGroupsScim.

  • Si une demande SCIM échoue et que vous ne parvenez pas à en déterminer la cause, vérifiez l’état de votre système de gestion des identités pour vous assurer que les services étaient disponibles.

  • Si une demande d'approvisionnement d'un utilisateur échoue avec une erreur 400 et que le message d'erreur dans le journal de votre système de gestion des identités indique les problèmes liés à la propriété du compte ou à la mise en forme du nom d'utilisateur, passez en revue « Considérations relatives au nom d'utilisateur pour une authentification externe ».

  • Une fois l’authentification réussie, GitHub Enterprise Server lie l’utilisateur qui s’est authentifié à une identité approvisionnée par SCIM. Les identificateurs uniques pour l’authentification et l’approvisionnement doivent correspondre. Pour plus d’informations, consultez « Points de terminaison d’API REST pour SCIM ».

  • Si vous gérez l'accès à l'aide de groupes dans votre système de gestion des identités, vous pouvez résoudre le problème en utilisant l'API REST ou l'IU Web pour GitHub Enterprise Server.

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