Gestion des comptes d’entreprise

À propos de la gestion des comptes d’entreprise avec GraphQL

Pour vous aider à superviser et à apporter des modifications dans vos organisations et à maintenir la conformité, vous pouvez utiliser l’API Enterprise Accounts et l’API Audit Log, qui sont disponibles uniquement en tant qu’API GraphQL.

Les points de terminaison de compte d’entreprise fonctionnent à la fois pour GitHub Enterprise Cloud et pour GitHub Enterprise Server.

GraphQL vous permet de demander et de retourner uniquement les données que vous spécifiez. Par exemple, vous pouvez créer une requête GraphQL ou demander des informations pour afficher tous les nouveaux membres de l’organisation ajoutés à votre organisation. Ou vous pouvez effectuer une mutation, ou un changement, pour inviter un administrateur à votre compte d’entreprise.

Avec l’API Audit Log, vous pouvez surveiller quand quelqu’un :

Accède aux paramètres de votre organisation ou de votre référentiel.
Modifie les autorisations.
Ajoute ou supprime des utilisateurs dans une organisation, un référentiel ou une équipe.
Promeut les utilisateurs en administrateurs.
Modifie les autorisations d’une application GitHub.

L’API Audit Log vous permet de conserver des copies de vos données de journal d’audit. Pour les requêtes effectuées avec l’API Audit Log, la réponse GraphQL peut inclure des données pendant 90 à 120 jours. Pour obtenir la liste des champs disponibles avec l’API de journal d'audit, consultez Administration d’entreprise.

Avec l’API Enterprise Accounts, vous pouvez :

Lister et passer en revue toutes les organisations et dépôts qui appartiennent à votre compte d’entreprise.
Modifier les paramètres de compte d’entreprise.
Configurer des stratégies pour les paramètres sur votre compte d’entreprise et ses organisations.
Inviter des administrateurs à votre compte d’entreprise.
Créer de nouvelles organisations dans votre compte d’entreprise.

Pour obtenir la liste des champs disponibles avec l’API Comptes d’entreprise, consultez Gestion des comptes d’entreprise.

Commencer en utilisant GraphQL pour les comptes d'entreprise

Consultez Utilisation des clients GraphQL pour commencer à utiliser GraphQL et gérer vos comptes d'entreprise.

Pour obtenir des exemples de requêtes, consultez Exemple de requête à l’aide de l’API Enterprise Accounts.

1. Choisir une méthode d’authentification

Nous vous recommandons d’utiliser un GitHub App pour les opérations GraphQL d’entreprise qui le prennent en charge. GitHub Apps fournir des autorisations affinées et des jetons de courte durée sans dépendre du propriétaire de l’entreprise personal access token. Certaines requêtes et mutations GraphQL d’entreprise ne prennent pas en charge GitHub Apps. Utilisez personal access token pour les opérations qui ne les prennent pas en charge.

Utilisation d’un GitHub App

Inscrivez un GitHub App et sélectionnez les autorisations d’entreprise nécessaires pour vos opérations. Consultez « Inscription d’une application GitHub ».
Installez l’application sur l’instance que vous souhaitez gérer. Si vous n’êtes pas le propriétaire de l’entreprise, vous devez demander au propriétaire de l’entreprise de l’installer. Consultez « Installer une GitHub App sur votre entreprise ».
Authentifiez-vous avec un jeton d’accès d’installation ou un jeton d’accès utilisateur, selon l’opération et si l’application doit agir pour le compte d’un utilisateur. Les instructions Insomnia ci-dessous utilisent un jeton d’accès utilisateur.

Une installation d’entreprise accorde uniquement des autorisations d’entreprise. Il n’accorde pas l’accès aux organisations ou aux dépôts de l’entreprise. Pour les opérations d’organisation ou de dépôt, l’application a besoin d’installations distinctes sur les organisations pertinentes et des autorisations appropriées. Une fois installée dans les organisations, votre application peut fonctionner sur plusieurs d’entre elles dans une requête GraphQL à l’aide d’un jeton d’accès utilisateur. Les jetons d’installation sont verrouillés sur un compte d’entreprise ou d’organisation unique et ne peuvent pas être utilisés d’un compte à l’autre.

Utilisation d’un personal access token

Utilisez une personal access token option si l’opération dont vous avez besoin ne prend pas en charge GitHub Appsou si vous créez une automatisation pour accéder à plusieurs organisations ou données de référentiel dans une seule requête GraphQL.

Pour vous authentifier auprès de GraphQL avec un jeton d’accès personal access token, créez-en un dans les paramètres du développeur. Pour plus d’informations, consultez Gestion de vos jetons d’accès personnels.
Accordez à votre personal access token des autorisations d’administrateur et de contrôle total pour les secteurs de votre entreprise auxquels vous souhaitez accéder. Pour obtenir une autorisation complète pour les dépôts privés, les organisations, les équipes, les données utilisateur et l’accès aux données de facturation et de profil d’entreprise, nous vous recommandons de sélectionner ces étendues pour votre personal access token:
- repo
- admin:org
- user
- admin:enterprise
Les étendues propres au compte d’entreprise sont les suivantes :
- admin:enterprise : donne le contrôle total des entreprises (y compris manage_runners:enterprise, manage_billing:enterprise et read:enterprise)
- manage_billing:enterprise: Lire et écrire des données de facturation d’entreprise.
- read:enterprise : lire les données de profil d’entreprise.
Copiez votre personal access token et conservez-le en lieu sûr jusqu’à ce que vous l’ajoutiez à votre client GraphQL.

2. Choisir un client GraphQL

Nous vous recommandons d’utiliser GraphiQL ou un autre client GraphQL autonome qui vous permet de configurer l’URL de base.

Vous pouvez également envisager d’utiliser ces clients GraphQL :

Les étapes suivantes utilisent Insomnia.

3. Configurer Insomnia pour utiliser l'API GraphQL GitHub avec des comptes d'entreprise

Ajoutez l’URL de base et la méthode POST à votre client GraphQL. Lorsque vous utilisez GraphQL pour demander des informations (requêtes), modifier des informations (mutations) ou transférer des données à l’aide de l’API GitHub, la méthode HTTP par défaut est POST et l’URL de base suit cette syntaxe :
- Pour votre instance d’entreprise : https://<HOST>/api/graphql
- Pour GitHub Enterprise Cloud : https://api.github.com/graphql
- Pour GitHub Enterprise Cloud avec résidence des données : https://api.SUBDOMAIN.ghe.com/graphql

S’authentifier avec un GitHub App

Cette procédure utilise le flux de code d’autorisation OAuth 2.0 pour obtenir un ****GitHub App, et non un jeton d’accès d’installation.

Dans les paramètres de votre application, définissez l’URL de rappel sur http://localhost. Cela doit correspondre exactement à l’URL de redirection que vous utilisez dans Insomnia.
Copiez l’ID client de votre application, et non son ID d’application. Générez et copiez un secret client. Gardez le secret en sécurité et ne le partagez pas dans des captures d’écran ou du code source. Ce flux n’utilise pas la clé privée de l’application.
Dans Insomnia, sélectionnez l’onglet Authentification, puis sélectionnez OAuth 2.0. Si vous avez précédemment sélectionné une autre méthode d’authentification, l’onglet peut être étiqueté avec cette méthode.

Configurez ces paramètres avec les informations d’identification de votre propre application.

Setting	Value
Enabled	✔️
Type d’autorisation	Code d’autorisation
URL d’autorisation	`https://github.com/login/oauth/authorize`
URL du jeton d’accès	`https://github.com/login/oauth/access_token`
ID du client	ID client de votre application
Clé secrète client	Secret client de votre application
Utiliser PKCE

Sélectionné | | | | méthode Code Challenge | SHA-256 | | | | URL de redirection | http://localhost | | Utilisation du navigateur par défaut | Laissez décoché, sauf si l’authentification unique de votre entreprise est activée, ce qui peut échouer dans le navigateur incorporé d’Insomnia. Si l’authentification unique est activée, cochez cette case et suivez les instructions pour mettre à jour l’URL de redirection de votre application | | Scope | Laissez ce champ vide. GitHub Apps utilisez des autorisations à partir de l’enregistrement de l’application, et non des portées OAuth. |

Si vous utilisez GitHub Enterprise Cloud avec la résidence des données, remplacez https://SUBDOMAIN.ghe.com par SUBDOMAIN dans les deux URL OAuth, où https://github.com est le sous-domaine de votre entreprise. Utilisez l’URL web, et non le nom d’hôte api.SUBDOMAIN.ghe.com .

Cliquez sur Récupérer des jetons, connectez-vous et autorisez l’application en tant qu’utilisateur disposant des autorisations d’entreprise requises. Le jeton d’accès utilisateur est limité aux autorisations et aux ressources auxquelles l’utilisateur et l’application peuvent accéder. Insomnia utilise le jeton récupéré pour vos demandes.

Pour plus d’informations, consultez Génération d’un jeton d’accès utilisateur pour une application GitHub.

S’authentifier à l’aide d’un personal access token

Si vous utilisez un personal access token à la place, configurez l’authentification Bearer.

Sélectionnez le menu Authentification, puis cliquez sur Jeton Bearer. Si vous avez précédemment sélectionné une autre méthode d’authentification, le menu est étiqueté avec cette méthode, par exemple « Authentification de base », à la place.
Dans le champ « TOKEN », entrez votre personal access token provenant d’une étape précédente.

Capture d’écran des paramètres d’authentification « Porteur » dans Insomnia. Le champ « JETON » est indiqué en orange foncé.

Définir le type de contenu

Après avoir configuré votre méthode d’authentification, définissez le type de contenu de la requête.

Cliquez sur En-têtes.

Capture d’écran des onglets de paramètres dans Insomnia. L’onglet « En-têtes » est présenté en orange foncé.

Sous l’onglet En-têtes, cliquez sur Ajouter.
Dans le champ « en-tête », entrez Content-Type.
Dans le champ « value », entrez application/json.

Maintenant, vous êtes prêt à effectuer des requêtes.

Exemple de requête utilisant l’API Enterprise Accounts

Cette requête GraphQL demande le nombre total de public dépôts dans chacune des organisations de votre appliance à l’aide de l’API Enterprise Accounts. Pour personnaliser cette requête, remplacez <enterprise-account-name> par le handle de votre compte d’entreprise. Par exemple, si votre compte d’entreprise se trouve à https://github.com/enterprises/octo-enterprise, remplacez <enterprise-account-name> par octo-enterprise.

query publicRepositoriesByOrganization($slug: String!) {
  enterprise(slug: $slug) {
    ...enterpriseFragment
  }
}

fragment enterpriseFragment on Enterprise {
  ... on Enterprise{
    name
    organizations(first: 100){
      nodes{
        name
        ... on Organization{
          name
          repositories(privacy: PUBLIC){
            totalCount
          }
        }
      }
    }
  }
}

# Passing our Enterprise Account as a variable
variables {
  "slug": "<enterprise-account-name>"
}

L’exemple de requête GraphQL suivant montre combien il est difficile de récupérer le nombre de référentiels public dans chaque organisation sans utiliser l’API Enterprise Accounts. Notez que l’API GraphQL Enterprise Accounts simplifie cette tâche pour les entreprises, car vous n’avez besoin de personnaliser qu’une seule variable. Pour personnaliser cette requête, remplacez <name-of-organization-one> et <name-of-organization-two>, etc. par les noms d’organisation de votre instance.

# Each organization is queried separately
{
  organizationOneAlias: organization(login: "nameOfOrganizationOne") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}

## How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

Interroger chaque organisation séparément

query publicRepositoriesByOrganization {
  organizationOneAlias: organization(login: "<name-of-organization-one>") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "<name-of-organization-two>") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}
# How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

Cette requête GraphQL demande les cinq dernières entrées de journal pour une organisation d’entreprise. Pour personnaliser cette requête, remplacez <org-name> et <user-name>.

{
  organization(login: "<org-name>") {
    auditLog(last: 5, query: "actor:<user-name>") {
      edges {
        node {
          ... on AuditEntry {
# Get Audit Log Entry by 'Action'
            action
            actorLogin
            createdAt
# User 'Action' was performed on
           user{
              name
                email
            }
          }
        }
      }
    }
  }
}

Pour plus d’informations sur la prise en main de GraphQL, consultez Présentation de GraphQL et Création d’appels avec GraphQL.

Types et champs GraphQL pour l’API Enterprise Accounts

Pour plus d’informations sur les nouvelles requêtes, mutations et types définis par schéma disponibles pour une utilisation avec l’API Enterprise Accounts, consultez la barre latérale où figurent des définitions GraphQL détaillées à partir de n’importe quelle page de référence GraphQL.

Vous pouvez accéder aux documents de référence à partir des clients GraphQL. Pour plus d’informations, consultez Utilisation des clients GraphQL. Pour d’autres informations, telles que les détails de la limite d’authentification et de débit, consultez la guides.

Dans cet article