Installation de l’authentification en tant qu’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 Status 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 chronologie du problème indique 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 Authorization 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 tester votre application pour vous assurer qu’elle dispose des autorisations requises pour les requêtes GraphQL et les mutations 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 TOKEN par un jeton d’accès d’installation : git clone https://x-access-token:TOKEN@github.com/owner/repo.git.

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 « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».

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 Authorization 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

Générez un jeton web JSON (JWT) pour votre application. Pour plus d’informations, consultez « Génération d’un jeton web JSON (JWT) pour une application GitHub ».
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 GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation ou GET /app/installations. Pour plus d’informations, consultez « Points de terminaison d’API REST pour GitHub Apps ».

Vous pouvez également trouver l’ID d’application dans la page de paramètres de votre application. L’ID de l’application n’est pas l’ID client. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « Modification d’une inscription d’application GitHub ».
Envoi d’une requête d’API REST POST à /app/installations/INSTALLATION_ID/access_tokens. Incluez votre jeton web JSON dans l’en-tête Authorization de votre requête. Remplacez INSTALLATION_ID par l’ID de l’installation que vous souhaitez utiliser pour l’authentification.

Par exemple, envoyez cette requête curl. Remplacez INSTALLATION_ID par l’ID de l’installation et JWT par votre jeton web JSON :
```
curl --request POST \
--url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer JWT" \
--header "X-GitHub-Api-Version: 2022-11-28"
```
Si vous le souhaitez, vous pouvez utiliser les paramètres de corps repositories ou repository_ids pour spécifier les dépôts individuels auxquels le jeton d’accès d’installation peut accéder. Si vous n’utilisez pas repositories ou repository_ids pour accorder l’accès à des dépôts spécifiques, le jeton d’accès d’installation aura accès à tous les dépôts auxquels l’installation a obtenu l’accès. Le jeton d’accès d’installation ne peut pas être accordé aux référentiels auxquels l’installation n’a pas accordé l’accès. Vous pouvez répertorier jusqu’à 500 référentiels.

Si vous le souhaitez, utilisez le paramètre de corps permissions pour spécifier les autorisations dont doit disposer le jeton d’accès d’installation. Si permissions n’est pas spécifié, le jeton d’accès d’installation aura toutes les autorisations qui ont été accordées à l’application. Impossible d’accorder au jeton d’accès d’installation des autorisations qui n’ont pas été accordées à l’application.

Lorsque l'on utilise les paramètres permissionspour réduire l'accès au jeton, la complexité du jeton est augmentée en raison du nombre de permissions dans la requête et du nombre de dépôts auxquels le jeton aura accès. Si cette complexité apparaît trop prononcée, vous recevrez un message d'erreur qui vous indiquera le nombre maximum de référentiels pouvant être pris en charge. Dans ce cas, vous devez demander moins d’autorisations avec le paramètre permissions, utiliser le paramètre repositories ou repository_ids pour demander moins de référentiels, ou installer l’application sur les référentiels all de votre organisation.

La réponse inclut un jeton d’accès d’installation, l’heure d’expiration du jeton, les autorisations dont dispose le jeton et les dépôts auxquels le jeton peut accéder. Le jeton d’accès d’installation expire après 1 heure.

Pour plus d’informations sur ce point de terminaison, consultez « Points de terminaison d’API REST pour GitHub Apps ».

Note

Dans la plupart des cas, vous pouvez utiliser Authorization: Bearer ou Authorization: token pour passer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliser Authorization: Bearer.

Authentification avec 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 Authorization 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 « Choix des autorisations pour une application GitHub ».

Dans l’exemple suivant, remplacez INSTALLATION_ACCESS_TOKEN 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.

Vous devez installer et importer octokit pour utiliser la bibliothèque Octokit.js. L’exemple suivant utilise des instructions import conformément à ES6. Pour plus d’informations sur les différentes méthodes d’installation et d’importation, consultez la section Usage du fichier README d’Octokit.js.

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

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 « Modification d’une inscription d’application GitHub ».
Générez une clé privée. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ».
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 GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation ou GET /app/installations. Pour plus d’informations, consultez « Points de terminaison d’API REST pour GitHub Apps ».
Importez App depuis octokit. Créez une nouvelle instance de App. Dans l’exemple suivant, remplacez APP_ID par une référence à l’ID de votre application. Remplacez PRIVATE_KEY 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,
});
```
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
Utilisez la méthode getInstallationOctokit pour créer une instance octokit authentifiée. Dans l’exemple suivant, remplacez INSTALLATION_ID par l’ID de l’installation de votre application que vous souhaitez authentifier.
JavaScript
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
Utilisez une méthode octokit 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 « Choix des autorisations pour une application GitHub ».

Par exemple, pour faire une requête auprès de l’API GraphQL :
JavaScript
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
```
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")
```
```
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 octokit pré-authentifiée aux gestionnaires d’événements de webhook.

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 « Modification d’une inscription d’application GitHub ».
Générez une clé privée. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ».
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 « Utilisation de webhooks avec des applications GitHub ».
Importez App depuis octokit. Créez une nouvelle instance de App. Dans l’exemple suivant, remplacez APP_ID par une référence à l’ID de votre application. Remplacez PRIVATE_KEY par une référence à la clé privée de votre application. Remplacez WEBHOOK_SECRET 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 },
});
```
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  webhooks: { WEBHOOK_SECRET },
});
```

Utilisez une méthode app.webhooks.* pour gérer les événements de webhook. Pour plus d’informations, consultez la section Webhooks du fichier Lisez-moi 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",
      },
    }
  )
});