Authentifizieren 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 finden Sie unter Installing GitHub Apps.

Wenn du beispielsweise möchtest, dass deine App das Feld eines Issues für ein Projekt ändert, das einer Organisation namens „octo-org“ gehört, dann würdest du dich als Installation deiner App in „octo-org“ authentifizieren. In der Problem-Zeitleiste wird angezeigt, dass Ihre 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 -Header deiner nachfolgenden API-Anforderungen. Du kannst auch die Octokit-SDKs von GitHub verwenden, die ein Installationszugriffstoken für dich generieren können.

Manche REST-API-Endpunkte akzeptieren keine Installationszugriffstoken, und bei den meisten REST-API-Endpunkten muss eine App bestimmte Berechtigungen für die Verwendung eines Endpunkts haben. Informationen dazu, ob ein REST-API-Endpunkt Installationszugriffstoken akzeptiert und welche Berechtigungen erforderlich sind, sind in der Dokumentation für den Endpunkt zu finden.

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. Für GraphQL-Anforderungen solltest du testen, ob deine App über die erforderlichen Berechtigungen für die gewünschten GraphQL-Abfragen und -Mutationen verfügt.

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 durch das Installationszugriffstoken: .

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

Weitere Informationen zum Authentifizieren als App im Namen eines Benutzers anstatt als App-Installation findest du unter AUTOTITLE.

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 -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 finden Sie unter Generieren eines JSON-Webtokens (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. Du kannst beispielsweise eine Installations-ID 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 REST-API-Endpunkte für GitHub Apps.

Sie finden die App-ID auch auf der Einstellungsseite Ihrer App. Die App-ID unterscheidet sich von der Client-ID. Weitere Informationen zum Aufrufen der Einstellungsseite für deine GitHub App findest du unter Ändern einer GitHub App-Registrierung.
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 "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"
```
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. Sie können bis zu 500 Repositorys auflisten.

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, sofern zutreffend. Das Installationszugriffstoken läuft nach 1 Stunde ab.

Weitere Informationen zu diesem Endpunkt findest du unter REST-API-Endpunkte für 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 -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 finden Sie unter AUTOTITLE.

Ersetze im folgenden Beispiel durch ein Installationszugriffstoken:

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"

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 Installationszugangstoken für dich neu zu generieren, damit du dir keine Gedanken über das einstündige Verfallsdatum machen musst.

Hinweis

Du musst 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 GitHub App ab. Du findest die App-ID auf der Seite mit den Einstellungen für deine GitHub App. Weitere Informationen zum Navigieren zur Einstellungsseite deiner GitHub App findest du unter AUTOTITLE.
Erstellen eines privaten Schlüssels. Weitere Informationen finden Sie unter AUTOTITLE.
Ruf die ID der Installation ab, als die du dich authentifizieren möchtest.

Wenn du auf ein Webhook-Ereignis reagierst, enthält die Webhook-Nutzlast 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 , , , oder abrufen. Weitere Informationen finden Sie unter AUTOTITLE.

Importiere aus . Erstelle eine neue .-Instanz. Ersetze im folgenden Beispiel durch einen Verweis auf die ID deiner App. Ersetze 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,
});

import { App } from "octokit";

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

Verwenden die -Methode, um eine authentifizierte -Instanz zu erstellen. Ersetze im folgenden Beispiel durch die ID der Installation der App, für die du dich authentifizieren möchtest.
JavaScript
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
Verwende eine -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 finden Sie unter AUTOTITLE.

Stelle beispielsweise so eine Anforderung an die GraphQL-API:
JavaScript
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
Stelle beispielsweise so eine Anforderung an die REST-API:
JavaScript
```
await octokit.request("GET /meta")
```
```
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 Instanz an Webhookereignishandler.

Rufe die ID deiner GitHub App ab. Du findest die App-ID auf der Seite mit den Einstellungen für deine GitHub App. Weitere Informationen zum Navigieren zur Einstellungsseite deiner GitHub App findest du unter AUTOTITLE.
Erstellen eines privaten Schlüssels. Weitere Informationen finden Sie unter AUTOTITLE.
Rufe das Webhookgeheimnis ab, das du in den Einstellungen deiner App angegeben hast. Weitere Informationen zu Webhook-Geheimnissen finden Sie unter AUTOTITLE.

Importiere aus . Erstelle eine neue Instanz von . Ersetze im folgenden Beispiel durch einen Verweis auf die ID deiner App. Ersetze durch einen Verweis auf den privaten Schlüssel deiner App. Ersetze durch das Webhookgeheimnis deiner App.

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

Verwende eine -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.`,
      headers: {
        "x-github-api-version": "2022-11-28",
      },
    }
  )
});

In diesem Artikel