Authentifizierung als GitHub-App-Installation

Informationen zur Authentifizierung als GitHub App-Installation

Sobald deine GitHub App in einem Konto installiert ist, kannst du sie als App-Installation für API-Anforderungen authentifizieren lassen. Dadurch kann die App auf Ressourcen zugreifen, die sich im Besitz dieser Installation befinden, solange der App der erforderliche Repositoryzugriff und die erforderlichen Berechtigungen gewährt werden. Von einer App-Installation vorgenommene API-Anforderungen werden der App zugeordnet. Weitere Informationen zum Installieren von GitHub-Apps findest du unter Installieren von GitHub-Apps.

Wenn du beispielsweise möchtest, dass deine App das Status-Feld eines Issues für ein Projekt ändert, das einer Organisation namens „octo-org“ gehört, dann würdest du dich als octo-org-Installation deiner App authentifizieren. Auf der Zeitachse des Issues wird angezeigt, dass deine App den Status aktualisiert hat.

Um eine API-Anforderung als Installation zu erstellen, musst du zunächst ein Installationszugriffstoken generieren. Anschließend sendest du das Installationszugriffstoken im Authorization-Header deiner nachfolgenden API-Anforderungen. Du kannst auch die Octokit-SDKs von GitHub verwenden, die ein Installationszugriffstoken für dich generieren können.

Wenn ein REST-API-Endpunkt mit einem GitHub App-Installationszugriffstoken funktioniert, findest du in der REST-Referenzdokumentation für diesen Endpunkt den Hinweis „Funktioniert mit GitHub Apps“. Darüber hinaus muss deine App über die erforderlichen Berechtigungen für die Verwendung des Endpunkts verfügen. Weitere Informationen findest du unter Choosing permissions for a GitHub App.

App-Installationen können auch die GraphQL-API verwenden. Ähnlich wie die REST-API muss die App über bestimmte Berechtigungen für den Zugriff auf Objekte in der GraphQL-API verfügen. Bei GraphQL-Anforderungen solltest du deine App testen, um sicherzustellen, dass sie über die erforderlichen Berechtigungen für die GraphQL-Abfragen und -Mutationen verfügt, die du vornehmen möchtest.

Du kannst auch ein Installationszugriffstoken verwenden, um dich für den HTTP-basierten Git-Zugriff zu authentifizieren. Deine App muss über die Repositoryberechtigung für Inhalte verfügen. Anschließend kannst du das Installationszugriffstoken als HTTP-Kennwort verwenden. Ersetze TOKEN durch das Installationszugriffstoken: git clone https://x-access-token:TOKEN@github.com/owner/repo.git".

Anforderungen, die mit einem Installationszugriffstoken gestellt werden, werden manchmal als Server-zu-Server-Anforderungen bezeichnet.

Weitere Informationen zur Authentifizierung als App im Namen eines Benutzers und nicht als App-Installation findest du unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen.

Verwenden eines Installationszugriffstokens zur Authentifizierung als App-Installation

Verwende zur Authentifizierung als Installation mit einem Installationszugriffstoken zunächst die REST-API, um ein Installationszugriffstoken zu generieren. Verwende dieses Installationszugriffstoken dann im Authorization-Header einer REST-API- oder GraphQL-API-Anforderung. Das Installationszugriffstoken läuft nach 1 Stunde ab.

Generieren eines Installationszugriffstokens:

Generiere ein JSON-Webtoken (JWT) für deine App. Weitere Informationen findest du unter Generieren eines JSON Web Token (JWT) für eine GitHub-App.
Ruf die ID der Installation ab, als die du dich authentifizieren möchtest.

Wenn du auf ein Webhookereignis reagierst, enthält die Webhooknutzlast die Installations-ID.

Du kannst auch die REST-API verwenden, um die ID für eine Installation deiner App zu ermitteln. Eine Installations-ID kannst du z. B. mit den Endpunkten GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation oder GET /app/installations abrufen. Weitere Informationen findest du unter GitHub Apps.
Sende eine REST-API-POST-Anforderung an /app/installations/INSTALLATION_ID/access_tokens. Fügen dein JSON-Webtoken in den Authorization-Header deiner Anforderung ein. Ersetze INSTALLATION_ID durch die ID der Installation, als die du dich authentifizieren möchtest.

Sende beispielsweise diese cURL-Anforderung. Ersetze INSTALLATION_ID durch die ID der Installation und JWT durch dein JSON-Webtoken:
```
curl --request POST \
--url "https://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer JWT"
```
Optional kannst du den Textparameter repositories oder repository_ids verwenden, um einzelne Repositorys anzugeben, auf die das Installationszugriffstoken zugreifen kann. Wenn du nicht repositories oder repository_ids verwendest, um Zugriff auf bestimmte Repositorys zu gewähren, hat das Installationszugriffstoken Zugriff auf alle Repositorys, auf die der Installation Zugriff gewährt wurde. Dem Installationszugriffstoken kann kein Zugriff auf Repositorys gewährt werden, auf die der Installation kein Zugriff gewährt wurde.

Verwende optional den Textparameter permissions, um die Berechtigungen anzugeben, die das Installationszugriffstoken haben soll. Wenn permissions nicht angegeben ist, verfügt das Installationszugriffstoken über alle Berechtigungen, die der App gewährt wurden. Dem Installationszugriffstoken können keine Berechtigungen gewährt werden, die der App nicht erteilt wurden.

Die Antwort enthält ein Installationszugriffstoken, den Zeitpunkt, zu dem das Token abläuft, die Berechtigungen des Tokens und die Repositorys, auf die das Token zugreifen kann. Das Installationszugriffstoken läuft nach 1 Stunde ab.

Weitere Informationen zu diesem Endpunkt findest du unter GitHub Apps.

Hinweis: In den meisten Fällen kannst du Authorization: Bearer oder Authorization: token verwenden, um ein Token zu übergeben. Wenn du jedoch ein JWT (JSON Web Token) übergibst, musst du Authorization: Bearer verwenden.

Authentifizieren mit einem Installationszugriffstoken

Zur Authentifizierung mit einem Installationszugriffstoken füge es in den Authorization-Header einer API-Anforderung ein. Das Zugriffstoken funktioniert sowohl mit der GraphQL-API als auch der REST-API.

Deine App muss über die erforderlichen Berechtigungen für die Verwendung des Endpunkts verfügen. Weitere Informationen findest du unter Choosing permissions for a GitHub App.

Ersetze INSTALLATION_ACCESS_TOKEN im folgenden Beispiel durch ein Installationszugriffstoken:

curl --request GET \
--url "https://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN"

Verwenden des Octokit.js-SDK zur Authentifizierung als App-Installation

Du kannst das Octokit.js-SDK von GitHub zur Authentifizierung als App-Installation verwenden. Ein Vorteil der Authentifizierung über das SDK besteht darin, dass du das JSON-Webtoken (JWT) nicht selbst generieren musst. Darüber hinaus kümmert sich das SDK darum, ein Installationszugriffstoken für dich neu zu generieren, damit du dir keine Gedanken über den einstündigen Ablauf machen musst.

Du musst octokit installieren und importieren, um die Octokit.js-Bibliothek nutzen zu können. Im folgenden Beispiel werden Importanweisungen gemäß ES6 verwendet. Weitere Informationen zu verschiedenen Installations- und Importmethoden findest du im Abschnitt „Verwendung“ der Octokit.js-Infodatei.

Verwenden von Octokit.js zur Authentifizierung mit einer Installations-ID

Rufe die ID deiner App ab. Du findest die App-ID auf der Einstellungsseite deiner App. Für benutzereigene Apps lautet die Einstellungsseite https://github.com/settings/apps/APP-SLUG. Für organisationseigene Apps lautet die Einstellungsseite https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG. Ersetze APP-SLUG durch den Slugified-Namen deiner Anwendung. Ersetze ORGANIZATION durch den Slugified-Namen deiner Organisation. Beispiel: https://github.com/organizations/octo-org/settings/apps/octo-app.
Erstellen eines privaten Schlüssels. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.
Ruf die ID der Installation ab, als die du dich authentifizieren möchtest.

Wenn du auf ein Webhookereignis reagierst, enthält die Webhooknutzlast die Installations-ID.

Du kannst auch die REST-API verwenden, um die ID für eine Installation deiner App zu ermitteln. Eine Installations-ID kannst du z. B. mit den Endpunkten GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation oder GET /app/installations abrufen. Weitere Informationen findest du unter GitHub Apps.
Importiere App aus octokit. Erstelle eine neue App-Instanz. Ersetze APP_ID im folgenden Beispiel durch einen Verweis auf die ID deiner App. Ersetze PRIVATE_KEY durch einen Verweis auf den privaten Schlüssel deiner App.
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
Verwenden die getInstallationOctokit-Methode, um eine authentifizierte octokit-Instanz zu erstellen. Ersetze im folgenden Beispiel INSTALLATION_ID durch die ID der Installation der App, für die du dich authentifizieren möchtest.
JavaScript
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
Verwende eine octokit-Methode, um eine Anforderung an die API zu senden.

Deine App muss über die erforderlichen Berechtigungen für die Verwendung des Endpunkts verfügen. Weitere Informationen findest du unter Choosing permissions for a GitHub App.

Stelle beispielsweise so eine Anforderung an die GraphQL-API:
JavaScript
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
Stelle beispielsweise so eine Anforderung an die REST-API:
JavaScript
```
await octokit.request("GET /meta")
```

Verwenden von „Octokit.js“ zur Authentifizierung als Reaktion auf ein Webhookereignis

Das Octokit.js-SDK übergibt auch eine vorab authentifizierte octokit-Instanz an Webhookereignishandler.

Rufe die ID deiner App ab. Du findest die App-ID auf der Einstellungsseite deiner App. Für benutzereigene Apps lautet die Einstellungsseite https://github.com/settings/apps/APP-SLUG. Für organisationseigene Apps lautet die Einstellungsseite https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG. Ersetze APP-SLUG durch den Slugified-Namen deiner Anwendung. Ersetze ORGANIZATION durch den Slugified-Namen deiner Organisation. Beispiel: https://github.com/organizations/octo-org/settings/apps/octo-app.
Erstellen eines privaten Schlüssels. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.
Rufe das Webhookgeheimnis ab, das du in den Einstellungen deiner App angegeben hast. Weitere Informationen zu Webhookgeheimnissen findest du unter Using webhooks with GitHub Apps.
Importiere App aus octokit. Erstelle eine neue App-Instanz. Ersetze APP_ID im folgenden Beispiel durch einen Verweis auf die ID deiner App. Ersetze PRIVATE_KEY durch einen Verweis auf den privaten Schlüssel deiner App. Ersetze WEBHOOK_SECRET durch das Webhookgeheimnis deiner App.
JavaScript
```
import { App } from "octokit";

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

Verwende eine app.webhooks.*-Methode, um Webhookereignisse zu behandeln. Weitere Informationen findest du im Abschnitt zu Webhooks der Octokit.js-Infodatei. So erstellst du beispielsweise einen Kommentar zu einem Issue, wenn das Issue geöffnet wird:

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.`,
      
    }
  )
});