Authentifizieren mit GitHub-Apps

Generieren eines privaten Schlüssels

Nachdem du eine GitHub-App erstellt hast, musst du mindestens einen privaten Schlüssel generieren. Du verwendest den privaten Schlüssel, um Zugriffstokenanforderungen zu signieren.

Du kannst mehrere private Schlüssel erstellen und diese rotieren, um Ausfallzeiten zu verhindern, wenn ein Schlüssel kompromittiert wird oder verloren geht. Informationen zum Überprüfen, ob ein privater Schlüssel mit einem öffentlichen Schlüssel übereinstimmt, findest du unter Überprüfen privater Schlüssel.

So generierst du einen privaten Schlüssel

1. Klicken Sie auf einer beliebigen Seite in der oberen rechten Ecke auf Ihr Profilfoto und anschließend auf Einstellungen.

   

2. Klicken Sie in der linken Seitenleiste auf Entwicklereinstellungen. 1. Klicke auf der linken Randleiste auf GitHub-Apps. 1. Klicke rechts neben der GitHub App, die du ändern möchtest, auf Bearbeiten.

3. Klicke in „Private Schlüssel“ auf Privaten Schlüssel generieren.

4. Es wird ein privater Schlüssel im PEM-Format auf deinen Computer heruntergeladen. Du muss diese Datei unbedingt speichern, da GitHub nur den öffentlichen Teil des Schlüssels speichert.

Überprüfen privater Schlüssel

GitHub AE generiert mit der SHA-256-Hashfunktion einen Fingerabdruck für jedes Paar aus privatem und öffentlichem Schlüssel. Du kannst überprüfen, ob dein privater Schlüssel dem öffentlichen Schlüssel entspricht, der auf GitHub AE gespeichert ist, indem du den Fingerabdruck deines privaten Schlüssels generierst und mit dem Fingerabdruck vergleichst, der auf GitHub AE angezeigt wird.

So überprüfst du einen privaten Schlüssel

1. Suche den Fingerabdruck für das Schlüsselpaar aus privatem und öffentlichem Schlüssel, das du auf der Seite mit den Entwicklereinstellungen deiner GitHub App im Abschnitt „Private Schlüssel“ findest. Weitere Informationen findest du unter Generating a private key („Generieren eines privaten Schlüssels“).
2. Generiere den Fingerabdruck deines privaten Schlüssels (PEM) lokal mithilfe des folgenden Befehls:

   $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64

3. Vergleiche die Ergebnisse des lokal generierten Fingerabdrucks mit dem Fingerabdruck, der in GitHub AE angezeigt wird.

Löschen privater Schlüssel

Du kannst einen verloren gegangenen oder kompromittierten privaten Schlüssel entfernen, indem du ihn löschst, du benötigst aber immer mindestens einen privaten Schlüssel. Wenn du nur über einen Schlüssel verfügst, musst du zunächst einen neuen generieren, bevor du den alten löschst.

Authentifizieren als GitHub App

Die Authentifizierung als GitHub App ermöglicht dir verschiedene Aktionen:

• Du kannst Verwaltungsinformationen auf hoher Ebene über deine GitHub App abrufen.
• Du kannst Zugriffstoken für eine Installation der App anfordern.

Für die Authentifizierung als GitHub App generierst du einen privaten Schlüssel im PEM-Format und lädst ihn auf deinen lokalen Computer herunter. Du verwendest diesen Schlüssel, um ein JSON Web Token (JWT) zu signieren und mithilfe des RS256-Algorithmus zu codieren. GitHub AE überprüft, ob die Anforderung authentifiziert ist, indem das Token mit dem gespeicherten öffentlichen Schlüssel der App verglichen wird.

Generieren eines JSON-Webtokens (JWT)

Verwenden von Ruby

Mit diesem Ruby-Skript kannst du ein JWT generieren. Achte darauf, dass du vor der Verwendung zunächst gem install jwt ausführen musst. YOUR_PATH_TO_PEM und YOUR_APP_ID sind die Werte, die du ersetzen musst. Die Werte müssen in doppelte Anführungszeichen eingeschlossen werden.

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

Verwenden von Python

Hier ist ein ähnliches Skript zum Generieren eines JWT in Python. Beachte, dass du pip install jwt verwenden musst, um dieses Skript nutzen zu können. Dieses Skript fordert dich zur Angabe des Speicherorts deiner PEM-Datei und der App-ID auf, oder du kannst diese Werte als Inlineargumente übergeben, wenn du das Skript ausführst.

#!/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)

Verwende den Bezeichner deiner GitHub App (YOUR_APP_ID) als Wert für den JWT-Anspruch iss (Aussteller). Du kannst den Bezeichner der GitHub App über den anfänglichen Webhook-Ping nach dem Erstellen der App oder jederzeit über die App-Einstellungsseite auf der Benutzeroberfläche von GitHub.com abrufen.

Lege das JWT nach dem Erstellen im Header der API-Anforderung fest:

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

Du musst den Wert YOUR_JWT ersetzen.

In den obigen Beispielen wird eine maximale Ablaufzeit von 10 Minuten verwendet. Danach gibt die API den Fehler 401 zurück:

{
  "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"
}

Du musst nach Ablauf der Zeit ein neues JWT erstellen.

Zugreifen auf API-Endpunkte als GitHub App

Eine Liste der REST-API-Endpunkte, mit der du Informationen zu einer GitHub App abrufen kannst, findest du unter GitHub-Apps.

Authentifizieren als Installation

Mit der Authentifizierung als Installation kannst du Aktionen in der API für diese Installation ausführen. Vor der Authentifizierung als Installation muss du ein Installationszugriffstoken erstellen. Stelle sicher, dass deine GitHub-App bereits in mindestens einem Repository installiert ist. Es ist unmöglich, ein Installationstoken ohne eine Installation zu erstellen. Diese Installationszugriffstoken werden von GitHub Apps für die Authentifizierung verwendet. Weitere Informationen findest du unter Installieren von GitHub-Apps.

Standardmäßig gelten Installationszugriffstoken für alle Repositorys, auf die eine Installation Zugriff hat. Du kannst den Bereich für das Installationszugriffstoken auf bestimmte Repositorys beschränken, indem du den Parameter repository_ids verwendest. Weitere Details findest du unter Erstellen eines Installationszugriffstokens für eine App. Installationszugriffstoken verfügen über die Berechtigungen, die von der GitHub App konfiguriert wurden, und sie laufen nach einer Stunde ab.

Um die Installationen für eine authentifizierte App aufzulisten, fügst du das oben generierte JWT in den Autorisierungsheader der API-Anforderung ein:

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

Die Antwort enthält eine Liste der Installationen, in der jede id der Installation zum Erstellen eines Installationszugriffstokens verwendet werden kann. Weitere Informationen zum Antwortformat findest du unter Auflisten von Installationen für eine authentifizierte App.

Um ein Installationszugriffstoken zu erstellen, fügst du das oben generierte JWT in den Autorisierungsheader der API-Anforderung ein und ersetzt:installation_id durch die id der Installation:

$ 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

Die Antwort umfasst dein Installationszugriffstoken, das Ablaufdatum, die Berechtigungen des Token und die Repositorys, auf die das Token Zugriff hat. Weitere Informationen zum Antwortformat findest du unter Erstellen eines Installationszugriffstokens für eine App.

Für die Autorisierung mit einem Installationszugriffstoken fügst du dieses in den Autorisierungsheader der API-Anforderung ein:

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

Du musst den Wert YOUR_INSTALLATION_ACCESS_TOKEN ersetzen.

Zugreifen auf API-Endpunkte als Installation

Eine Liste der REST-API-Endpunkte, die für die Verwendung von GitHub Apps mit einem Installationszugriffstoken verfügbar sind, findest du unter Verfügbare Endpunkte.

Eine Liste der Endpunkte im Zusammenhang mit Installationen findest du unter Installationen.

HTTP-basierter Git-Zugriff durch eine Installation

Installationen mit Berechtigungen für contents in einem Repository können ihre Installationszugriffstoken verwenden, um sich für den Git-Zugriff zu authentifizieren. Verwende dazu das Installationszugriffstoken als HTTP-Kennwort:

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