Skip to main content

Approvisionnement d’utilisateurs avec SCIM à l’aide de l’API REST

Vous pouvez gérer le cycle de vie des comptes d’utilisateurs de votre entreprise sur GitHub.com à partir 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é ?

Pour gérer les utilisateurs de votre entreprise avec votre fournisseur d’identité, votre entreprise doit être activée pour Enterprise Managed Users, qui est disponible avec GitHub Enterprise Cloud. Pour plus d’informations, consultez « À propos d’Enterprise Managed Users ».

Remarques :

  • La prise en charge de l’approvisionnement des utilisateurs avec le schéma SCIM public de GitHub est en phase bêta privée et sujette à des modifications. Pour demander l’accès à la version bêta, discutez avec votre gestionnaire de compte dans L’équipe commerciale GitHub.
  • Cette opération vous permet de provisionner des comptes d’utilisateur pour votre entreprise sur GitHub Enterprise Cloud à l’aide de SCIM. L’opération est disponible uniquement pour une utilisation avec Enterprise Managed Users. Si vous n’utilisez pas Enterprise Managed Users et que vous souhaitez provisionner l’accès à vos organisations à l’aide de SCIM, consultez « Points de terminaison d’API REST pour SCIM ».
  • GitHub vous recommande de tester l’approvisionnement dans un environnement isolé des données de production sur votre fournisseur d’identité et GitHub.com.

À propos du provisionnement pour Enterprise Managed Users

Pour créer, gérer et désactiver des comptes d’utilisateurs pour les membres de votre entreprise sur GitHub.com, votre fournisseur d’identité doit implémenter SCIM pour la communication avec GitHub. SCIM est une spécification ouverte pour la gestion des identités utilisateur entre différents systèmes. Chaque IdP aura une expérience de configuration différente pour l’approvisionnement SCIM. Pour plus d’informations sur l’approvisionnement sur GitHub Enterprise Cloud, consultez « Configuration du provisionnement SCIM pour Enterprise Managed Users ».

Les partenaires GitHub, avec certains développeurs de systèmes de gestion des identités, doivent fournir une intégration « prête à l’emploi » à Enterprise Managed Users. Si votre entreprise n’utilise pas de fournisseur d’identité partenaire, vous pouvez configurer l’approvisionnement à partir d’un système d’identité qui communique avec l’API REST de GitHub. Ce guide vous aidera à comprendre les rubriques suivantes relatives à l’implémentation de GitHub.

  • Comment passer en revue et diffuser en continu des journaux d’audit détaillés pour votre entreprise
  • L’API REST, y compris les points de terminaison pour les attentes en matière de SCIM et d’utilisation
  • Dépannage

Vous pouvez également utiliser un fournisseur d’identité du partenaire pour l’authentification et l’approvisionnement. Pour plus d’informations, consultez « À propos d’Enterprise Managed Users ».

GitHub n’a pas testé chaque fournisseur d’identité. Support GitHub fournit une prise en charge limitée des fournisseurs d’identité de partenaire. Vous pouvez éventuellement intégrer un fournisseur d’identité conforme à la spécification SCIM et aux instructions de GitHub, mais pour prendre en charge le fournisseur d’identité lui-même ou créer une intégration, consultez la documentation du développeur, à l’équipe de support technique ou à d’autres ressources.

Prérequis

  • Avant de configurer l’approvisionnement, vous devez configurer l’authentification. Pour plus d’informations, consultez « Configuration de l’authentification pour les utilisateurs gérés par l’entreprise ».

  • Avant de configurer l’approvisionnement, vérifiez que vous comprenez les exigences d’intégration et le niveau de prise en charge de votre fournisseur d’identité. Pour plus d’informations, consultez « À propos d’Enterprise Managed Users ».

  • Pour effectuer l’intégration avec l’API REST de GitHub, le fournisseur d’identité doit prendre en charge la norme System for Cross-domain Identity Management (SCIM) 2.0. Pour plus d’informations, consultez les RFC suivants sur le site web IETF.

  • GitHub vous recommande d’authentifier uniquement les demandes aux points de terminaison d’API REST pour SCIM à l’aide d’un personal access token (classic) associé à l’utilisateur de configuration de votre entreprise. Le jeton nécessite l’étendue admin:enterprise. Pour plus d’informations, consultez « Configuration du provisionnement SCIM pour Enterprise Managed Users ».

  • Les enregistrements utilisateur pour les systèmes que vous utilisez pour l’authentification et l’approvisionnement doivent partager un identificateur unique et satisfaire les critères de correspondance de GitHub. Pour plus d'informations, consultez « SCIM » dans la documentation de l'API REST.

  • Une fois la configuration initiale de l’authentification et de l’approvisionnement terminée, GitHub ne recommande pas de migrer vers une autre plateforme pour ces deux fonctionnalités. Si vous devez migrer une entreprise existante vers une autre plateforme pour l’authentification ou l’approvisionnement, contactez votre responsable de compte sur L’équipe commerciale GitHub.

Configuration du streaming 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 pour l’approvisionnement SCIM. Pour plus d’informations, consultez « Streaming de journaux d’audit pour votre entreprise ».

Présentation de l’API REST pour SCIM

Pour effectuer des appels SCIM et gérer des utilisateurs, vous allez utiliser l’API REST de GitHub. Pour plus d’informations sur l’accès aux ressources dans l’API REST, consultez « Prise en main de l’API REST ».

Points de terminaison d’API REST pour SCIM

Les tableaux suivants décrivent les points de terminaison SCIM proposés par l’API REST. Vous trouverez plus d’informations dans la documentation de l’API REST. La documentation inclut des exemples de code, des en-têtes requis et des paramètres de chemin d’accès et des codes de réponse HTTP.

Pour plus d’informations sur l’authentification des demandes adressées à ces points de terminaison, consultez « SCIM » dans la documentation de l’API REST.

Les demandes qui ne correspondent pas aux attentes de l’API REST retournent une erreur 400 Bad Request.

Points de terminaison d’API REST pour la gestion des utilisateurs

Pour approvisionner des utilisateurs, effectuez des demandes aux points de terminaison d’API REST suivants.

ActionMéthodePoint de terminaison et plus d’informations
Créer un utilisateurPOSTApprovisionner un utilisateur d’entreprise SCIM
Récupérer un utilisateurGETObtenir les informations d’approvisionnement SCIM d’un utilisateur d’entreprise
Mettre à jour tous les attributs d’un utilisateurPUTDéfinir les informations SCIM d’un utilisateur d’entreprise approvisionné
Mettre à jour un attribut utilisateur individuelPATCHMettre à jour un attribut pour un utilisateur d’entreprise SCIM
Lister tous les utilisateursGETLister les identités approvisionnées SCIM pour une entreprise
Supprimer un utilisateurDELETESupprimer un utilisateur SCIM d’une entreprise

Points de terminaison d’API REST pour la gestion des groupes

Pour contrôler l’accès aux référentiels de votre entreprise, votre intégration SCIM peut gérer l’appartenance de l’organisation et de l’équipe aux utilisateurs via des groupes sur votre fournisseur d’identité. Pour plus d’informations, consultez « Gestion des appartenances aux équipes avec les groupes d’un fournisseur d’identité ».

Pour gérer des groupes, effectuez des demandes aux points de terminaison d’API REST suivants.

ActionMéthodePoint de terminaison et plus d’informations
Créer un groupePOSTApprovisionner un groupe d’entreprise SCIM
Récupérer un groupeGETObtenir les informations d’approvisionnement SCIM d’un groupe d’entreprise
Mettre à jour tous les attributs d’un groupePUTDéfinir les informations SCIM d’un groupe d’entreprise approvisionné
Mettre à jour un attribut groupe individuelPATCHMettre à jour un attribut pour un groupe d’entreprise SCIM
Répertorier tous les groupesGETLister les groupes approvisionnés SCIM pour une entreprise
Supprimer un groupeDELETESupprimer un groupe SCIM d’une entreprise

À propos des limites de débit

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

Attributs utilisateur et groupe

Les demandes adressées à l’API REST prennent en charge des attributs spécifiques pour les utilisateurs et les groupes. Pour plus d’informations, consultez « Attributs utilisateur SCIM pris en charge » et « Attributs de groupe SCIM pris en charge » dans la documentation de l’API REST pour les opérations SCIM.

Par exemple, vous pouvez utiliser l’attribut roles pour attribuer un rôle dans l’entreprise à un utilisateur ou un groupe. Si vous accordez plusieurs rôles à un utilisateur, le rôle disposant d’un accès plus privilégié est prioritaire.

RôlePlus d’informations dans « Rôles dans une entreprise »
enterprise_ownerPropriétaires d’entreprise
billing_managerGestionnaires de facturation
userMembres d’entreprise
guest_collaboratorCollaborateurs invités

À propos du mappage des identités externes

Une fois l’authentification réussie, GitHub Enterprise Cloud 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 « SCIM » dans la documentation de l’API REST.

Vous pouvez afficher ce mappage sur GitHub.com. Pour plus d’informations, consultez « Visualisation et gestion de l’accès SAML d’un utilisateur à votre entreprise ».

S’assurer que les utilisateurs ont l’accès souhaité

Si votre intégration gère l’accès à l’aide de groupes sur votre fournisseur d’identité, vous pouvez vérifier que les utilisateurs obtiennent l’accès souhaité. Vous pouvez utiliser l’API REST pour comparer les appartenances des groupes de votre fournisseur d’identité à la présentation de GitHub de ces groupes. Pour plus d’informations, consultez « Groupes externes » et « Points de terminaison d’API REST pour les équipes ».

À propos de la suspension et du reprovisionnement des utilisateurs

Vous ne pouvez pas supprimer complètement un compte d’utilisateur managé sur GitHub.com. Au lieu de cela, vous pouvez suspendre temporairement ou définitivement le compte.

Pour suspendre temporairement un utilisateur, définissez l’attribut active de l’enregistrement utilisateur sur false à l’aide d’une requête PATCH ou d’une requête PUT. Après avoir suspendu temporairement un compte, l’utilisateur ne peut plus se connecter pour accéder à votre entreprise sur GitHub.com. Pour plus d’informations, consultez « Mettre à jour un attribut pour un utilisateur d’entreprise SCIM » ou « Définir des informations SCIM pour un utilisateur d’entreprise approvisionné » dans la documentation de l’API REST pour les opérations SCIM.

Pour suspendre définitivement un utilisateur, envoyez une demande DELETE. Si vous suspendez définitivement un compte, vous ne pouvez pas réactiver le compte. Pour plus d’informations, consultez « Supprimer un utilisateur SCIM d’une entreprise » dans la documentation de l’API REST pour les opérations SCIM.

Pour reprovisionner un utilisateur, définissez l’attribut active de l’enregistrement utilisateur sur true à l’aide d’une demande POST, PUT ou PATCH. Si vous avez suspendu définitivement le compte, un événement d’approvisionnement ultérieur crée un compte pour la personne qui se connecte. Le compte nouvellement approvisionné n’aura aucune relation avec le compte d’origine. Pour plus d’informations, consultez « Mettre en service un utilisateur d’entreprise SCIM », « Définir des informations SCIM pour un utilisateur d’entreprise approvisionné » ou « Mettre à jour un attribut pour un utilisateur d’entreprise SCIM » dans la documentation de l’API REST pour les opérations SCIM.

Dépannage

  • Si GitHub limite votre débit de vos demandes à l’API REST, vous pouvez en savoir plus dans « À propose des limites de débit ».

  • Si vous activez le streaming 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 SCIM en filtrant les événements à partir des contrôleurs EnterpriseUsersScim ou EnterpriseGroupsScim.

  • Si votre intégration gère l’accès à l’aide de groupes sur votre fournisseur d’identité, vous pouvez passer en revue les événements de catégorie external_group dans le journal d’audit de votre entreprise pour confirmer la réussite des appels SCIM. Vous pouvez également afficher les informations de résolution des problèmes dans l’interface web pour GitHub. Pour plus d’informations, consultez « Événements du journal d’audit pour votre entreprise » et « Dépannage des problèmes d’appartenance à l’équipe avec des groupes de fournisseur d’identité ».

Pour aller plus loin