Authentification en tant qu’installation d’application GitHub

À propos de l’authentification en tant qu’installation GitHub App

Une fois que votre GitHub App est installée sur un compte, vous pouvez l’authentifier en tant qu’installation d’application pour les requêtes d’API. Cela permet à l’application d’accéder aux ressources appartenant à cette installation, tant qu’elle a obtenu l’accès au dépôt et les autorisations nécessaires. Les requêtes d’API effectuées par une installation d’application sont attribuées à l’application. Pour plus d’informations sur l’installation de GitHub Apps, consultez Installation d’applications GitHub.

Par exemple, si vous souhaitez que votre application modifie le champ d’un problème sur un projet appartenant à une organisation appelée « octo-org », vous devez vous authentifier en tant qu’installation octo-org de votre application. La ligne de temps du problème indiquerait que votre application a mis à jour l'état.

Pour effectuer une demande d’API en tant qu’installation, vous devez d’abord générer un jeton d’accès à l’installation. Ensuite, vous allez envoyer le jeton d’accès d’installation dans l’en-tête de vos requêtes d’API suivantes. Vous pouvez également utiliser les SDK Octokit de GitHub, qui peuvent générer un jeton d’accès d’installation pour vous.

Certains points de terminaison d’API REST n’acceptent pas les jetons d’accès d’installation, et la plupart des points de terminaison d’API REST nécessitent que votre application dispose de certaines autorisations pour utiliser un point de terminaison. Consultez la documentation du point de terminaison pour savoir si un point de terminaison d’API REST accepte les jetons d’accès d’installation et pour voir quelles autorisations sont requises.

Les installations d’applications peuvent également utiliser l’API GraphQL. Comme pour l’API REST, l’application doit disposer de certaines autorisations pour accéder aux objets dans l’API GraphQL. Pour les requêtes GraphQL, vous devez vérifier que votre application dispose des autorisations requises pour les requêtes et mutations GraphQL que vous souhaitez effectuer.

Vous pouvez également utiliser un jeton d’accès d’installation pour vous authentifier pour l’accès à Git basé sur HTTP. Votre application doit disposer de l’autorisation de référentiel « Contenu ». Vous pouvez ensuite utiliser le jeton d’accès d’installation en tant que mot de passe HTTP. Remplacez par un jeton d’accès d’installation : .

Les requêtes effectuées avec un jeton d’accès d’installation sont parfois appelées requêtes « serveur à serveur ».

Pour plus d’informations sur l’authentification en tant qu’application au nom d’un utilisateur et non en tant qu’installation d’application, consultez « AUTOTITLE ».

Utilisation d’un jeton d’accès d’installation pour s’authentifier en tant qu’installation d’application

Pour vous authentifier en tant qu’installation avec un jeton d’accès d’installation, utilisez d’abord l’API REST pour générer un jeton d’accès d’installation. Ensuite, utilisez ce jeton d’accès d’installation dans l’en-tête d’une requête d’API REST ou d’API GraphQL. Le jeton d’accès d’installation expire après 1 heure.

Génération d’un jeton d’accès d’installation

Authentification à l'aide d'un jeton d'accès d'installation

Pour vous authentifier avec un jeton d’accès d’installation, incluez-le dans l’en-tête d’une requête d’API. Le jeton d’accès fonctionne à la fois avec l’API GraphQL et l’API REST.

Votre application doit disposer des autorisations requises pour utiliser le point de terminaison. Pour plus d’informations, consultez « AUTOTITLE ».

Dans l’exemple suivant, remplacez par un jeton d’accès d’installation :

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Utilisation du Kit de développement logiciel (SDK) Octokit.js pour s’authentifier en tant qu’installation d’application

Vous pouvez utiliser le SDK Octokit.js de GitHub pour vous authentifier en tant qu’installation d’application. L’un des avantages de l’utilisation du SDK pour vous authentifier est que vous n’avez pas besoin de générer vous-même un jeton web JSON (JWT). En outre, le SDK prend en charge la régénération d’un jeton d’accès d’installation pour vous afin que vous n’ayez pas à vous soucier de l’expiration après une heure.

Utilisation d’Octokit.js pour s’authentifier avec un ID d’installation

1. Obtenez l’ID de votre GitHub App. Vous pouvez rechercher l’ID de l’application sur la page des paramètres de votre GitHub App. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « AUTOTITLE ».

2. Générez une clé privée. Pour plus d’informations, consultez « AUTOTITLE ».

3. Obtenez l’ID de l’installation que vous souhaitez utiliser pour l’authentification.

   Si vous répondez à un événement de webhook, la charge utile du webhook inclut l’ID d’installation.

   Vous pouvez également utiliser l’API REST pour rechercher l’ID d’une installation de votre application. Par exemple, vous pouvez obtenir un ID d’installation avec les points de terminaison , , ou . Pour plus d’informations, consultez « AUTOTITLE ».

4. Importez depuis . Créez une nouvelle instance de . Dans l’exemple suivant, remplacez par une référence à l’ID de votre application. Remplacez par une référence à la clé privée de votre application.

   JavaScript

   import { App } from "octokit";
   
   const app = new App({
     appId: APP_ID,
     privateKey: PRIVATE_KEY,
   });
   

5. Utilisez la méthode pour créer une instance authentifiée. Dans l’exemple suivant, remplacez par l’ID de l’installation de votre application que vous souhaitez authentifier.

   JavaScript

   const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
   

6. Utilisez une méthode pour effectuer une requête auprès de l’API.

   Votre application doit disposer des autorisations requises pour utiliser le point de terminaison. Pour plus d’informations, consultez « AUTOTITLE ».

   Par exemple, pour faire une requête auprès de l’API GraphQL :

   JavaScript

   await octokit.graphql(`
     query {
       viewer {
         login
       }
     }
     `)
   

   Par exemple, pour effectuer une requête auprès de l’API REST :

   JavaScript

   await octokit.request("GET /meta")
   

Utilisation d’Octokit.js pour s’authentifier en réponse à un événement de webhook

Le SDK Octokit.js transmet également une instance pré-authentifiée aux gestionnaires d’événements de webhook.

1. Obtenez l’ID de votre GitHub App. Vous pouvez rechercher l’ID de l’application sur la page des paramètres de votre GitHub App. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « AUTOTITLE ».

2. Générez une clé privée. Pour plus d’informations, consultez « AUTOTITLE ».

3. Obtenez le secret de webhook que vous avez spécifié dans les paramètres de votre application. Pour plus d’informations sur les secrets de webhook, consultez « AUTOTITLE ».

4. Importez depuis . Créez une nouvelle instance de . Dans l’exemple suivant, remplacez par une référence à l’ID de votre application. Remplacez par une référence à la clé privée de votre application. Remplacez par le secret de webhook de votre application.

   JavaScript

   import { App } from "octokit";
   
   const app = new App({
     appId: APP_ID,
     privateKey: PRIVATE_KEY,
     webhooks: { WEBHOOK_SECRET },
   });
   

5. Utilisez une méthode pour gérer les événements de webhook. Pour plus d’informations, consultez la section Webhooks du README d’Octokit.js. Par exemple, pour créer un commentaire sur un problème lors de l’ouverture du problème :

   app.webhooks.on("issues.opened", ({ octokit, payload }) => {
     await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
         owner: payload.repository.owner.login,
         repo: payload.repository.name,
         issue_number: payload.issue.number,
         body: `This is a bot post in response to this issue being opened.`,
         headers: {
           "x-github-api-version": "2022-11-28",
         },
       }
     )
   });