À 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
ouGET /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 « AUTOTITRE ».
-
Envoi d’une requête d’API REST
POST
à/app/installations/INSTALLATION_ID/access_tokens
. Incluez votre jeton web JSON dans l’en-têteAuthorization
de votre requête. RemplacezINSTALLATION_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 etJWT
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
ourepository_ids
pour spécifier les dépôts individuels auxquels le jeton d’accès d’installation peut accéder. Si vous n’utilisez pasrepositories
ourepository_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.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. Sipermissions
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.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 ».
Remarque : Dans la plupart des cas, vous pouvez utiliser
Authorization: Bearer
ouAuthorization: token
pour passer un jeton. Toutefois, si vous passez un jeton web JSON (JWT), vous devez utiliserAuthorization: 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
ouGET /app/installations
. Pour plus d’informations, consultez « Points de terminaison d’API REST pour GitHub Apps ». -
Importez
App
depuisoctokit
. Créez une nouvelle instance deApp
. Dans l’exemple suivant, remplacezAPP_ID
par une référence à l’ID de votre application. RemplacezPRIVATE_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 instanceoctokit
authentifiée. Dans l’exemple suivant, remplacezINSTALLATION_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
depuisoctokit
. Créez une nouvelle instance deApp
. Dans l’exemple suivant, remplacezAPP_ID
par une référence à l’ID de votre application. RemplacezPRIVATE_KEY
par une référence à la clé privée de votre application. RemplacezWEBHOOK_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", }, } ) });