Synchroniser les utilisateurs et les équipes

Vue d'ensemble

Recréer votre organisation à la main dans GitGuardian ne passe pas à l'échelle : les équipes, leurs membres et les dépôts qu'elles possèdent existent déjà ailleurs, et ils changent sans cesse. GitGuardian propose plusieurs moyens de garder cette structure synchronisée automatiquement.

Méthode	Ce qu'elle synchronise	Prérequis
SSO	Les utilisateurs, provisionnés à la première connexion (Just-In-Time)	SAML SSO configuré sur votre workspace
SCIM	Les utilisateurs et les équipes depuis votre fournisseur d'identité, y compris le déprovisionnement	SCIM activé avec un fournisseur d'identité pris en charge
Synchronisation des équipes GitHub	Les équipes, leurs membres et leurs périmètres depuis votre organisation GitHub	Une organisation GitHub dont GitGuardian peut lire les e-mails des membres, généralement GitHub Enterprise Cloud avec SAML SSO
Scripts de mappage	Les équipes, leurs membres et leurs périmètres depuis GitHub ou GitLab	Une machine pour exécuter et maintenir les scripts

Pour la gestion du cycle de vie des utilisateurs, nous recommandons fortement de configurer le SSO et d'activer SCIM : ce sont les seules méthodes qui gèrent aussi le déprovisionnement lorsqu'une personne quitte votre organisation.

Pour refléter la structure de votre VCS, privilégiez la synchronisation native des équipes GitHub lorsque votre organisation est éligible, et repliez-vous sur les scripts de mappage pour GitLab ou pour les organisations GitHub qui ne remplissent pas les prérequis.

Synchronisation automatique des équipes avec GitHub

GitGuardian peut refléter votre organisation GitHub dans votre workspace : les équipes sont créées, les membres sont ajoutés avec les bonnes permissions, et chaque périmètre d'équipe est rempli avec les dépôts que l'équipe possède.

Prérequis

• L'application GitHub GitGuardian installée sur l'organisation, avec ses permissions par défaut. GitHub.com et GitHub Enterprise Server sont tous deux pris en charge.
• Un moyen pour GitGuardian de lire l'e-mail de chaque membre, ce qui permet de faire correspondre les utilisateurs GitHub aux Members GitGuardian : les identités SAML d'une organisation GitHub Enterprise Cloud avec SAML SSO, ou les e-mails des membres lisibles par l'application. Sans SAML SSO, les membres qui masquent leur e-mail dans GitHub sont ignorés.

GitGuardian vérifie ces conditions lorsque vous ajoutez l'organisation et affiche le résultat dans la colonne Eligibility, avec la raison lorsqu'un élément manque, comme No SAML SSO ou No readable member emails. Utilisez Re-check eligibility une fois que vous avez corrigé le problème. Si votre organisation cesse par la suite de les remplir, la synchronisation s'arrête et vos Managers de workspace sont notifiés par e-mail.

Ce qui est synchronisé

• Équipes : chaque équipe de l'organisation, sous-équipes comprises. L'imbrication est aplatie, et une équipe enfant conserve son parent dans son nom.
• Membres : chaque membre de l'équipe, avec la permission GitGuardian correspondant au niveau d'accès qu'il a dans GitHub. Les mainteneurs d'équipe deviennent des leaders d'équipe dans GitGuardian.
• Périmètres : les dépôts surveillés auxquels l'équipe a accès dans GitHub.
• Invitations (facultatif) : avec Invite missing members, les membres GitHub qui ne font pas encore partie de votre workspace y sont invités, et placés dans leurs équipes une fois qu'ils acceptent. Cette option est désactivée par défaut.

Activer la synchronisation

1. Ouvrez Settings > Integrations, sélectionnez votre intégration GitHub, et faites défiler jusqu'à Team synchronization.
2. Cliquez sur Add organization et sélectionnez l'organisation GitHub à refléter.
3. Gardez Enable synchronization activé, et choisissez les options dont vous avez besoin :
   • Notify members : les membres reçoivent un e-mail concernant les changements d'équipe que la synchronisation leur applique. Désactivé par défaut.
   • Invite missing members : les membres GitHub qui ne font pas encore partie de votre workspace y sont invités. Désactivé par défaut.
4. Cliquez sur Synchronize teams. La première synchronisation démarre immédiatement.

L'organisation apparaît alors dans le tableau Team synchronization avec son statut, son éligibilité et la date de sa dernière synchronisation. Les intégrations existantes ne sont jamais activées silencieusement : ajoutez chaque organisation vous-même.

Comment cela fonctionne

La synchronisation s'exécute toutes les 24 heures. Depuis le menu d'une organisation, vous pouvez également :

• Sync now pour appliquer les derniers changements GitHub sans attendre la prochaine exécution.
• Re-check eligibility après avoir corrigé un prérequis.
• View history pour voir chaque exécution avec son statut, son déclencheur (activation, planifié ou manuel), sa durée et les changements qu'elle a appliqués.

Les équipes synchronisées affichent un badge GitHub et sont en lecture seule dans GitGuardian : leur nom, leur description et leur composition sont gérés par GitHub. Les équipes que vous créez manuellement et les équipes provisionnées via SCIM continuent de fonctionner à leurs côtés, mais une équipe donnée appartient à une seule source.

Désactiver Enable synchronization met en pause la synchronisation et conserve les équipes synchronisées en l'état. Supprimer l'organisation du tableau Team synchronization détache ses équipes : elles restent dans votre workspace en tant qu'équipes ordinaires, que vous pouvez modifier ou supprimer depuis la page Teams.

L'origine de chaque équipe est également disponible via l'API publique, sur les endpoints /v1/teams et /v1/teams/{team_id}, et les changements d'équipe et de composition sont enregistrés dans l'audit log.

Scripts de mappage des utilisateurs et des équipes

Si vous avez besoin de plus de flexibilité que les options ci-dessus, l'API publique GitGuardian vous permet de répliquer n'importe quelle structure d'équipe et n'importe quel modèle de permissions dans votre workspace, quel que soit le système dont elle provient : un système de gestion de versions, mais aussi un outil de gestion de tickets, un catalogue de services interne, ou toute autre source de vérité. La bibliothèque cliente de l'API GitGuardian, py-gitguardian, se charge des appels à l'API pour vous.

Nous maintenons deux scripts d'exemple, pour GitHub et GitLab, que vous pouvez exécuter tels quels ou utiliser comme point de départ pour votre propre source. Ils gèrent la synchronisation à grande échelle, et la même approche s'applique aux sources non-VCS.

Fonctionnalités clés

1. Mappage des utilisateurs et des équipes

• Mappage : Mappe automatiquement les groupes GitLab ou les équipes GitHub, ainsi que les dépôts qu'ils possèdent et les utilisateurs qui leur sont associés, vers les Teams GitGuardian et leurs périmètres respectifs. Pour GitHub, cela est réalisé en exploitant les utilisateurs IDP lorsque GitHub Enterprise Server est utilisé, ou alternativement, en analysant les membres de l'organisation comme solution de repli. Cependant, pour les membres de l'organisation, la synchronisation sera ignorée si leurs adresses e-mail sont masquées par défaut, car elles sont nécessaires au mappage.
• Plateformes prises en charge : GitHub, GitLab.
• Gestion automatisée des utilisateurs : Invite les nouveaux utilisateurs et synchronise les compositions. Ne gère pas les utilisateurs inactifs ni leur suppression — pour cela, veuillez utiliser SCIM, qui prend désormais en charge à la fois le provisionnement et le déprovisionnement des utilisateurs. Pour GitHub, le script ne mappe que les utilisateurs qui ont une adresse e-mail sur leur profil ou si SAML est configuré sur GitHub avec un plan Enterprise.

2. Gestion des permissions

• Permissions sélectives : Exclut les rôles élevés (par exemple, managers, owners) pour éviter un excès de permissions.

3. Notifications

• Alertes e-mail : Possibilité de notifier les utilisateurs des changements, invitations ou suppression d'équipes.

4. Journalisation et gestion des erreurs

• Journaux détaillés : Suit les détails de succès, d'échec et d'erreur à l'aide du module Python logging.
• Gestion des erreurs : Fournit une gestion élégante des erreurs d'API avec une journalisation appropriée.

5. Évolutivité

• Prise en charge de grands jeux de données : Gère de grands jeux de données (plus de 1000 utilisateurs et équipes) avec pagination.

6. Personnalisation

• Authentification : Facilement configurable à l'aide de tokens pour GitHub.
• Modifications du script : Conçu pour la modularité, permettant une personnalisation facile pour étendre les fonctionnalités.

Démarrer

Consultez le fichier README du dépôt pour des instructions détaillées sur la configuration et l'exécution du script pour votre plateforme :

• GitHub : team-mapping-github-gitguardian
• GitLab : team-mapping-gitlab-gitguardian

Support

Pour toute assistance supplémentaire, contactez-nous à support@gitguardian.com.