以 GitHub App 安装身份进行身份验证

关于以 GitHub App 安装身份进行身份验证

一旦您的 GitHub App 安装在某个帐户上，您就可以让它以 App 安装身份进行 API 请求的身份验证。这允许 App 访问该安装拥有的资源，只要 App 被授予了必要的仓库访问权限和权限。由 App 安装发出的 API 请求将归因于该 App。有关安装 GitHub App 的更多信息，请参阅“安装 GitHub App”。

例如，如果您希望您的 App 更改名为“octo-org”的组织拥有的项目中某个问题的 Status 字段，那么您需要以您的 App 的 octo-org 安装身份进行身份验证。该问题的时序将说明您的 App 更新了状态。

要以安装身份发出 API 请求，您必须首先生成一个安装访问令牌。然后，您将在后续 API 请求的 Authorization 标头中发送安装访问令牌。您也可以使用 GitHub 的 Octokit SDK，它可以为您生成安装访问令牌。

某些 REST API 端点不接受安装访问令牌，大多数 REST API 端点要求您的 App 具有使用端点的某些权限。要查看 REST API 端点是否接受安装访问令牌以及需要哪些权限，请参阅该端点的文档。

App 安装也可以使用 GraphQL API。与 REST API 类似，该 App 必须具有某些权限才能访问 GraphQL API 中的对象。对于 GraphQL 请求，您应该测试您的 App 是否具有您要执行的 GraphQL 查询和变异所需的权限。

您还可以使用安装访问令牌来验证基于 HTTP 的 Git 访问。您的 App 必须具有“内容”仓库权限。然后，您可以将安装访问令牌用作 HTTP 密码。将 TOKEN 替换为安装访问令牌：git clone https://x-access-token:[email protected]/owner/repo.git。

使用安装访问令牌发出的请求有时被称为“服务器到服务器”请求。

有关以用户身份而不是以 App 安装身份进行 App 身份验证的更多信息，请参阅“以用户身份使用 GitHub App 进行身份验证”。

使用安装访问令牌以 App 安装身份进行身份验证

要使用安装访问令牌以安装身份进行身份验证，首先使用 REST API 生成安装访问令牌。然后，在 REST API 或 GraphQL API 请求的 Authorization 标头中使用该安装访问令牌。安装访问令牌将在 1 小时后过期。

生成安装访问令牌

为您的应用生成一个 JSON Web 令牌 (JWT)。有关更多信息，请参阅“为 GitHub 应用生成 JSON Web 令牌 (JWT)”。
获取您要以其身份进行身份验证的安装的 ID。

如果您正在响应 Webhook 事件，Webhook 有效负载将包含安装 ID。

您也可以使用 REST API 查找应用安装的 ID。例如，您可以使用 GET /users/{username}/installation、GET /repos/{owner}/{repo}/installation、GET /orgs/{org}/installation 或 GET /app/installations 端点获取安装 ID。有关更多信息，请参阅“GitHub 应用的 REST API 端点”。

您还可以在应用设置页面上找到应用 ID。应用 ID 与客户端 ID 不同。有关导航到 GitHub 应用设置页面的更多信息，请参阅“修改 GitHub 应用注册”。
向 /app/installations/INSTALLATION_ID/access_tokens 发送 REST API POST 请求。在请求的 Authorization 标头中包含您的 JSON Web 令牌。将 INSTALLATION_ID 替换为您要以其身份进行身份验证的安装的 ID。

例如，发送此 curl 请求。将 INSTALLATION_ID 替换为安装的 ID，将 JWT 替换为您的 JSON Web 令牌
```
curl --request POST \
--url "https://api.github.com/app/installations/INSTALLATION_ID/access_tokens" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer JWT" \
--header "X-GitHub-Api-Version: 2022-11-28"
```
可选地，您可以使用 repositories 或 repository_ids 体参数指定安装访问令牌可以访问的单个存储库。如果您不使用 repositories 或 repository_ids 来授予对特定存储库的访问权限，则安装访问令牌将具有访问安装被授予访问权限的所有存储库的权限。安装访问令牌无法被授予访问安装未被授予访问权限的存储库的权限。您可以列出最多 500 个存储库。

可选地，使用 permissions 体参数指定安装访问令牌应具有的权限。如果未指定 permissions，则安装访问令牌将具有授予应用的所有权限。安装访问令牌无法被授予应用未被授予的权限。

当使用 permissions 参数来减少令牌的访问权限时，由于请求中的权限数量和令牌将具有访问权限的存储库数量，令牌的复杂性会增加。如果复杂性过大，您将收到一条错误消息，指示可以支持的最大存储库数量。在这种情况下，您应该使用 permissions 参数请求更少的权限，使用 repositories 或 repository_ids 参数请求更少的存储库，或在您的组织中的 all 存储库上安装应用。

响应将包含安装访问令牌、令牌到期时间、令牌具有的权限以及令牌可以访问的存储库。安装访问令牌将在 1 小时后过期。

有关此端点的更多信息，请参阅“GitHub Apps 的 REST API 端点”。

注意：在大多数情况下，您可以使用Authorization: Bearer或Authorization: token传递令牌。但是，如果您传递的是 JSON Web 令牌 (JWT)，则必须使用Authorization: Bearer。

使用安装访问令牌进行身份验证

要使用安装访问令牌进行身份验证，请将其包含在 API 请求的Authorization标头中。访问令牌将与 GraphQL API 和 REST API 都兼容。

您的应用必须具有使用端点所需的权限。有关更多信息，请参阅“为 GitHub App 选择权限”。

在以下示例中，将INSTALLATION_ACCESS_TOKEN替换为安装访问令牌

curl --request GET \
--url "https://api.github.com/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

使用 Octokit.js SDK 作为应用安装进行身份验证

您可以使用 GitHub 的 Octokit.js SDK 作为应用安装进行身份验证。使用 SDK 进行身份验证的一个优势是您无需自己生成 JSON Web 令牌 (JWT)。此外，SDK 将负责为您重新生成安装访问令牌，因此您无需担心一小时的过期时间。

您必须安装并导入octokit才能使用 Octokit.js 库。以下示例使用与 ES6 一致的导入语句。有关不同安装和导入方法的更多信息，请参阅Octokit.js README 的使用部分。

使用 Octokit.js 通过安装 ID 进行身份验证

获取您的 GitHub App 的 ID。您可以在 GitHub App 的设置页面上找到您的应用 ID。有关导航到 GitHub App 设置页面的更多信息，请参阅“修改 GitHub App 注册”。
生成私钥。有关更多信息，请参阅“管理 GitHub Apps 的私钥”。
获取您要以其身份进行身份验证的安装的 ID。

如果您正在响应 Webhook 事件，Webhook 有效负载将包含安装 ID。

您也可以使用 REST API 查找应用安装的 ID。例如，您可以使用 GET /users/{username}/installation、GET /repos/{owner}/{repo}/installation、GET /orgs/{org}/installation 或 GET /app/installations 端点获取安装 ID。有关更多信息，请参阅“GitHub 应用的 REST API 端点”。

从octokit导入App。创建一个新的App实例。在以下示例中，将APP_ID替换为对您的应用 ID 的引用。将PRIVATE_KEY替换为对您的应用私钥的引用。

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

使用 getInstallationOctokit 方法创建经过身份验证的 octokit 实例。在以下示例中，将 INSTALLATION_ID 替换为要代表其进行身份验证的应用程序安装的 ID。
JavaScript
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
使用 octokit 方法向 API 发出请求。

您的应用必须具有使用端点所需的权限。有关更多信息，请参阅“为 GitHub App 选择权限”。

例如，要向 GraphQL API 发出请求
JavaScript
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
例如，要向 REST API 发出请求
JavaScript
```
await octokit.request("GET /meta")
```
```
await octokit.request("GET /meta")
```

使用 Octokit.js 在响应 Webhook 事件时进行身份验证

Octokit.js SDK 还将预先经过身份验证的 octokit 实例传递给 Webhook 事件处理程序。

获取您的 GitHub App 的 ID。您可以在 GitHub App 的设置页面上找到您的应用 ID。有关导航到 GitHub App 设置页面的更多信息，请参阅“修改 GitHub App 注册”。
生成私钥。有关更多信息，请参阅“管理 GitHub Apps 的私钥”。
获取在应用程序设置中指定的 Webhook 密钥。有关 Webhook 密钥的更多信息，请参阅“使用 GitHub 应用程序的 Webhook”。

从 octokit 导入 App。创建一个新的 App 实例。在以下示例中，将 APP_ID 替换为应用程序 ID 的引用。将 PRIVATE_KEY 替换为应用程序私钥的引用。将 WEBHOOK_SECRET 替换为应用程序的 Webhook 密钥。