以 GitHub 应用安装的身份进行身份验证

关于作为 GitHub 应用安装进行身份验证

在您的 GitHub 应用安装到某个帐户后，您可以使其作为应用安装进行 API 请求的身份验证。这允许应用访问该安装拥有的资源，只要应用被授予必要的存储库访问权限和权限即可。应用安装进行的 API 请求将归因于该应用。有关安装 GitHub 应用的更多信息，请参阅“安装 GitHub 应用”。

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

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

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

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

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

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

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

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

要使用安装访问令牌作为安装进行身份验证，首先使用 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，则安装访问令牌将具有授予应用的所有权限。无法向安装访问令牌授予应用未被授予的权限。

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

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

注意

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

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

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

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

在以下示例中，将 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 应用的 ID。您可以在 GitHub 应用的设置页面上找到您的应用 ID。有关导航到 GitHub 应用设置页面的更多信息，请参阅“修改 GitHub 应用注册”。
生成私钥。有关更多信息，请参阅“管理 GitHub 应用的私钥”。
获取您要以其身份进行身份验证的安装的 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 应用选择权限”。

例如，向 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 应用的 ID。您可以在 GitHub 应用的设置页面上找到您的应用 ID。有关导航到 GitHub 应用设置页面的更多信息，请参阅“修改 GitHub 应用注册”。
生成私钥。有关更多信息，请参阅“管理 GitHub 应用的私钥”。
获取您在应用设置中指定的 Webhook 密钥。有关 Webhook 密钥的更多信息，请参阅“使用 GitHub 应用的 Webhook”。

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