Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.
GitHub AE est actuellement en version limitée.

Authentification avec les applications GitHub

Vous pouvez vous authentifier en tant que GitHub App ou en tant qu’installation.

Authentification en tant qu’GitHub App

L’authentification en tant qu’GitHub App est requise pour les appels d’API server-to-server, ce qui permet à votre GitHub App d’effectuer deux opérations :

  • Récupérer des informations générales de gestion concernant votre GitHub App.
  • Demander des jetons d’accès pour une installation de l’application, ce qui vous permet d’effectuer des appels d’API sans utilisateur connecté.

Pour vous authentifier en tant qu’GitHub App, générez une clé privée au format PEM, puis téléchargez-la sur votre machine locale. Vous allez utiliser cette clé pour signer un jeton JWT (JSON Web Token) et l’encoder à l’aide de l’algorithme RS256. GitHub AE valide l’identité de votre application en vérifiant le jeton avec la clé publique stockée de l’application. Vous allez échanger ce jeton JWT contre un jeton d’installation, utilisé pour authentifier votre application en tant qu’installation spécifique.

Liste des installations d’une application

Pour lister les installations de votre application, incluez le jeton JWT dans l’en-tête d’autorisation d’une requête d’API de type GET /app/installations. Pour plus d’informations sur la génération de jetons JWT, consultez « Charge utile JWT ».

$ curl -i -X GET \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://HOSTNAME/api/v3/app/installations

La réponse comprend une liste d’installations, où le id de chaque installation peut être utilisé pour créer un jeton d’accès d’installation. Pour plus d’informations sur le format de réponse, consultez « Lister les installations de l’application authentifiée ».

Authentification en tant qu’installation

L’authentification en tant qu’installation permet à votre application d’accéder à cette organisation ou à cet utilisateur via l’API, ainsi qu’à des ressources publiques sur GitHub AE. Pour vous authentifier en tant qu’installation, vous devez utiliser un jeton d’accès d’installation, que vous obtenez en envoyant un jeton JWT à GitHub AE pour prouver l’identité de votre application. Vérifiez que vous avez déjà installé votre application GitHub sur au moins une organisation ou un compte d’utilisateur. Il est impossible de créer un jeton d’installation sans installation. Pour plus d’informations, consultez « Installation d’applications GitHub ».

Par défaut, l’étendue des jetons d’accès d’installation englobe tous les dépôts auxquels une installation a été autorisée à accéder. Vous pouvez limiter davantage l’étendue du jeton d’accès d’installation à des dépôts spécifiques en utilisant le paramètre repository_ids. Les jetons d’accès d’installation ont les autorisations configurées par l’GitHub App et, comme l’accès au dépôt, peuvent également être limités à l’aide du paramètre permissions. Pour plus d’informations, consultez la documentation sur les points de terminaison Créer un jeton d’accès d’installation pour une application. Tous les jetons d’installation expirent au bout d’une heure.

Pour créer un jeton d’accès d’installation, incluez le jeton JWT dans l’en-tête d’autorisation de la requête d’API, en remplaçant :installation_id par l’id de l’installation. Pour plus d’informations sur la génération de jetons JWT, consultez « Charge utile JWT ».

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://HOSTNAME/api/v3/app/installations/:installation_id/access_tokens

La réponse comprend votre jeton d’accès d’installation, la date d’expiration, les autorisations du jeton ainsi que les dépôts auxquels le jeton peut accéder. Pour plus d’informations sur le format de réponse, consultez le point de terminaison Créer un jeton d’accès d’installation pour une application.

Pour vous authentifier avec un jeton d’accès d’installation, incluez-le dans l’en-tête d’autorisation de la requête d’API. Remplacez YOUR_INSTALLATION_ACCESS_TOKEN par un jeton d’accès d’installation :

$ curl -i \
-H "Authorization: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://HOSTNAME/api/v3/installation/repositories

Remarque : 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.

Accès aux points de terminaison d’API en tant qu’installation

Pour obtenir la liste des points de terminaison d’API REST pouvant être utilisés par les GitHub Apps à l’aide d’un jeton d’accès d’installation, consultez « Points de terminaison disponibles pour les applications GitHub ».

Pour obtenir la liste des points de terminaison liés aux installations, consultez « Installations ».

Accès HTTP à Git par une installation

Les installations disposant d’autorisations sur le contents d’un dépôt peuvent utiliser leurs jetons d’accès d’installation pour s’authentifier dans le cadre de l’accès à Git. Utilisez le jeton d’accès d’installation en tant que mot de passe HTTP :

git clone https://x-access-token:<token>@github.com/owner/repo.git

Génération d’un jeton JWT (JSON Web Token)

Le jeton JWT utilisé pour authentifier votre application se compose de plusieurs revendications, ainsi que d’une signature utilisée pour valider son authenticité. Ces revendications sont les suivantes :

RevendicationSignificationDétails
iatÉmis àHeure de création du jeton JWT. Pour vous protéger contre la dérive de l’horloge, nous vous recommandons de définir ces 60 secondes dans le passé.
expExpire àHeure d’expiration du jeton JWT, après laquelle il ne peut pas être utilisé pour demander un jeton d’installation. La valeur exp ne doit pas être de plus de 10 minutes dans le futur.
issÉmetteurVotre ID d’application, utilisé pour trouver la clé publique appropriée permettant de vérifier la signature du jeton JWT.

Les jetons doivent être signés à l’aide de l’algorithme RS256, avec une revendication alg RS256 correspondante.

Utilisation de Ruby

Voici un script Ruby qui vous permet de générer un jeton JWT. Notez que vous devez exécuter gem install jwt avant de l’utiliser. YOUR_PATH_TO_PEM et YOUR_APP_ID sont les valeurs que vous devez remplacer. Veillez à placer les valeurs entre guillemets doubles.

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Private key contents
private_pem = File.read("YOUR_PATH_TO_PEM")
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
payload = {
  # issued at time, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub App's identifier
  iss: "YOUR_APP_ID"
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

Utilisation de Python

Voici un script similaire pour générer un JWT dans Python. Notez que vous devrez utiliser pip install jwt pour utiliser ce script. Ce script vous invite à entrer l’emplacement de votre fichier PEM et l’ID de votre application, ou vous pouvez les passer comme arguments inline lorsque vous exécutez le script.

python
#!/usr/bin/env python3
import jwt
import time
import sys

# Get PEM file path
if len(sys.argv) > 1:
    pem = sys.argv[1]
else:
    pem = input("Enter path of private PEM file: ")

# Get the App ID
if len(sys.argv) > 2:
    app_id = sys.argv[2]
else:
    app_id = input("Enter your APP ID: ")

# Open PEM
with open(pem, 'rb') as pem_file:
    signing_key = jwt.jwk_from_pem(pem_file.read())

payload = {
    # Issued at time
    'iat': int(time.time()),
    # JWT expiration time (10 minutes maximum)
    'exp': int(time.time()) + 600,
    # GitHub App's identifier
    'iss': app_id
}

# Create JWT
jwt_instance = jwt.JWT()
encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256')

print(f"JWT:  ", encoded_jwt)

Utilisez l’identificateur (YOUR_APP_ID) de votre GitHub App en tant que valeur de la revendication JWT iss (émetteur). Vous pouvez obtenir l’identificateur de l’GitHub App via le ping de webhook initial après la création de l’application, ou à tout moment à partir de la page des paramètres de l’application dans l’IU de GitHub.com.

Après avoir créé le jeton JWT, définissez-le dans le Header de la requête d’API :

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github+json" https://HOSTNAME/api/v3/app

YOUR_JWT est la valeur que vous devez remplacer.

Les exemples ci-dessus utilisent le délai d’expiration maximal de 10 minutes. Une fois ce délai atteint, l’API retourne une erreur 401 :

{
  "message": "'Expiration' claim ('exp') must be a numeric value representing the future time at which the assertion expires.",
  "documentation_url": "https://docs.github.com/github-ae@latest/rest"
}

Vous devez créer un jeton JWT après l’expiration du délai.

Accès aux points de terminaison d’API en tant qu’GitHub App

Pour obtenir la liste des points de terminaison d’API REST que vous pouvez utiliser afin d’obtenir des informations générales sur une GitHub App, consultez « Applications GitHub ».

Génération d’une clé privée

Après avoir créé une GitHub App, vous devez générer une ou plusieurs clés privées afin d’effectuer des requêtes à l’API GitHub AE en tant qu’application elle-même. Vous allez utiliser la clé privée pour signer les jetons JWT utilisés pour demander un jeton d’accès d’installation.

Vous pouvez créer plusieurs clés privées et les alterner pour éviter les temps d’arrêt si une clé est compromise ou perdue. Pour vérifier qu’une clé privée correspond à une clé publique, consultez Vérification des clés privées.

Pour générer une clé privée :

  1. Dans le coin supérieur droit d’une page, cliquez sur votre photo de profil, puis sur Paramètres.

    Icône Paramètres dans la barre de l’utilisateur

  2. Dans la barre latérale gauche, cliquez sur Paramètres de développeur. Paramètres de développeur 1. Dans la barre latérale gauche, cliquez sur GitHub Apps. Section GitHub Apps 1. À droite de GitHub App que vous souhaitez modifier, cliquez sur Modifier. Sélection de l’application

  3. Dans « Clés privées », cliquez sur Générer une clé privée. Générer une clé privée

  4. Une clé privée au format PEM est téléchargée sur votre ordinateur. Veillez à stocker ce fichier, car GitHub stocke uniquement la partie publique de la clé.

Remarque : Si vous utilisez une bibliothèque qui nécessite un format de fichier spécifique, le fichier PEM que vous téléchargez est au format PKCS#1 RSAPrivateKey.

Vérification des clés privées

GitHub AE génère une empreinte digitale pour chaque paire de clés privée et publique à l’aide de la fonction de hachage SHA-256. Vous pouvez vérifier que votre clé privée correspond à la clé publique stockée sur GitHub AE en générant l’empreinte digitale de votre clé privée et en la comparant à l’empreinte digitale affichée sur GitHub AE.

Pour vérifier une clé privée :

  1. Recherchez l’empreinte digitale de la paire de clés privée et publique à vérifier dans la section « Clés privées » de la page des paramètres de développement de l’GitHub App. Pour plus d’informations, consultez Génération d’une clé privée. Empreinte digitale de clé privée
  2. Générez localement l’empreinte digitale de votre clé privée (PEM) à l’aide de la commande suivante :
    $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64
  3. Comparez les résultats de l’empreinte digitale générée localement à l’empreinte digitale que vous voyez dans GitHub AE.

Suppression de clés privées

Vous pouvez retirer une clé privée perdue ou compromise en la supprimant, mais vous devez toujours avoir au moins une clé privée inscrite pour votre GitHub App. Quand votre GitHub App n’a qu’une seule clé, vous devez en générer une nouvelle avant de supprimer l’ancienne. Suppression de la dernière clé privée