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 récentes, veuillez consulter la Documentation en anglais.
 

 

Authentification avec les applications GitHub

Contenu de cet article

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

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

Après avoir créé une application GitHub, vous devez générer une ou plusieurs clés privées. Vous utilisez la clé privée pour signer les demandes de jeton d’accès.

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.

  3. 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

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

  5. 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 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 en générant l’empreinte digitale de votre clé privée et en la comparant à l’empreinte digitale affichée sur GitHub.

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.

Suppression de clés privées

Vous pouvez retirer une clé privée perdue ou compromise en la supprimant, mais vous devez avoir au moins une clé privée. Quand vous n’avez 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

Authentification en tant qu’GitHub App

L’authentification en tant qu’GitHub App vous permet de faire plusieurs choses :

  • Vous pouvez récupérer des informations de gestion générales concernant votre GitHub App.
  • Vous pouvez demander des jetons d’accès pour une installation de l’application.

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 vérifie que la requête est authentifiée en contrôlant le jeton avec la clé publique stockée de l’application.

Voici un script Ruby rapide qui vous permet de générer un jeton JWT. Notez que vous devez exécuter gem install jwt avant de l’utiliser.

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

YOUR_PATH_TO_PEM et YOUR_APP_ID sont les valeurs que vous devez remplacer. Veillez à placer les valeurs entre guillemets doubles.

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://api.github.com/app

YOUR_JWT est la valeur que vous devez remplacer.

L’exemple ci-dessus utilise 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/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 ».

Authentification en tant qu’installation

L’authentification en tant qu’installation vous permet d’effectuer des actions dans l’API pour cette installation. Avant de vous authentifier en tant qu’installation, vous devez créer un jeton d’accès d’installation. Vérifiez que vous avez déjà installé votre application GitHub sur au moins un dépôt. Il est impossible de créer un jeton d’installation sans la moindre installation. Ces jetons d’accès d’installation sont utilisés par les GitHub Apps pour s’authentifier. Pour plus d’informations, consultez « Installation d’applications GitHub ».

Par défaut, les jetons d’accès d’installation ont une étendue qui se limite à tous les dépôts auxquels une installation peut accéder. Vous pouvez limiter l’étendue du jeton d’accès d’installation à des dépôts spécifiques en utilisant le paramètre repository_ids. Pour plus d’informations, consultez le point de terminaison Créer un jeton d’accès d’installation pour une application. Les jetons d’accès d’installation disposent d’autorisations configurées par l’GitHub App et expirent au bout d’une heure.

Pour lister les installations d’une application authentifiée, incluez le jeton JWT généré ci-dessus dans l’en-tête d’autorisation de la requête d’API :

$ curl -i -X GET \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/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 ».

Pour créer un jeton d’accès d’installation, incluez le jeton JWT généré ci-dessus dans l’en-tête d’autorisation de la requête d’API, puis remplacez :installation_id par le id de l’installation :

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/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 :

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

YOUR_INSTALLATION_ACCESS_TOKEN est la valeur que vous devez remplacer.

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