为 GitHub 应用生成用户访问令牌

关于用户访问令牌

注意：过期的用户访问令牌目前是一项可选功能，可能会有变动。若要选择加入或退出令牌过期功能，请参阅“激活 GitHub 应用的可选功能”。有关详细信息，请参阅“GitHub 应用的用户到服务器访问令牌过期”。

用户访问令牌是一种 OAuth 标记。不同于传统 OAuth 标记，用户访问令牌不使用范围。而是使用细粒度的权限。用户访问令牌仅具有用户和应用都拥有的权限。例如，如果向应用授予了写入存储库内容的权限，但用户只能读取内容，则用户访问令牌也只能读取内容。

同样，用户访问令牌只能访问用户和应用都可访问的资源。例如，如果向应用授予了对存储库 A 和 B 的访问权限，并且用户可以访问存储库 B 和 C，那么用户访问令牌可以访问存储库 B，但不能访问 A 或 C。可以使用 REST API 检查用户访问令牌可以访问哪些安装以及安装中的哪些存储库。有关详细信息，请参阅“GitHub 应用安装”中的 GET /user/installations 和 GET /user/installations/{installation_id}/repositories。

使用用户访问令牌发出 API 请求时，用户访问令牌的速率限制适用。有关详细信息，请参阅“GitHub 应用的速率限制”。

默认情况下，用户访问令牌在 8 小时后过期。可以使用刷新令牌重新生成用户访问令牌。有关详细信息，请参阅“刷新用户访问令牌”。

用户可以撤销其对 GitHub App 的授权。有关详细信息，请参阅“令牌过期和吊销”。如果用户撤销其对 GitHub App 的授权，应用会收到 github_app_authorization Webhook。 GitHub Apps 无法取消订阅此事件。如果应用收到此 Webhook，应停止代表已撤销令牌的用户调用 API。如果应用继续使用已撤销的访问令牌，它将收到 401 Bad Credentials 错误。有关此 Webhook 的详细信息，请参阅“Webhook 事件和有效负载”。

应确保用户访问令牌和刷新令牌的安全。有关详细信息，请参阅“Best practices for creating a GitHub App”。

使用 Web 应用程序流生成用户访问令牌

如果应用在浏览器中运行，应使用 Web 应用程序流来生成用户访问令牌。有关使用 Web 应用流的教程，请参阅“Building a "Login with GitHub" button with a GitHub App”。

将用户定向到此 URL，并从以下参数列表添加任何必需的查询参数：http(s)://HOSTNAME/login/oauth/authorize。例如，此 URL 指定 client_id 和 state 参数：http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg。

查询参数	类型	说明
`client_id`	`string`	必填。 GitHub App 的客户端 ID。客户端 ID 不同于应用 ID。可以在应用的设置页上找到客户端 ID。对于用户拥有的应用，设置页为 `https://github.com/settings/apps/APP-SLUG`。对于组织拥有的应用，设置页为 `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`。将 `APP-SLUG` 替换为应用的转换名称，将 `ORGANIZATION` 替换为组织的转换名称。例如，`https://github.com/organizations/octo-org/settings/apps/octo-app`。
`redirect_uri`	`string`	用户获得授权后被发送到的应用程序中的 URL。此 URL 必须与在应用设置中作为“回叫 URL”提供的 URL 之一完全匹配，并且不能包含任何附加参数。
`state`	`string`	指定后，该值应该包含一个随机字符串，以防止伪造攻击，并且可以包含任何其他任意数据。
`login`	`string`	指定后，Web 应用程序流会显示特定帐户，提示用户可使用该帐户登录和授权应用。
`allow_signup`	`boolean`	在 OAuth 流程中，是否向未经身份验证的用户提供注册 GitHub 的选项。默认为 `true`。在策略禁止注册时使用 `false`。

如果用户接受授权请求，GitHub 会将用户重定向到应用设置中的回叫 URL 之一，并提供可用于在下一步中创建用户访问令牌的 code 查询参数。如果在上一步中指定了 redirect_uri，则会使用该回叫 URL。否则，将使用应用设置页上的第一个回叫 URL。

如果在上一步中指定了 state 参数，GitHub 还将包含state 参数。如果 state 参数与在上一步中发送的 state 参数不匹配，则无法信任请求，应中止 Web 应用程序流。

通过向此 URL 发出 POST 请求以及以下查询参数，将上一步中的 code 换为用户访问令牌：http(s)://HOSTNAME/login/oauth/access_token

查询参数	类型	说明
`client_id`	`string`	必填。 GitHub App 的客户端 ID。客户端 ID 不同于应用 ID。可以在应用的设置页上找到客户端 ID。对于用户拥有的应用，设置页为 `https://github.com/settings/apps/APP-SLUG`。对于组织拥有的应用，设置页为 `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`。将 `APP-SLUG` 替换为应用的转换名称，将 `ORGANIZATION` 替换为组织的转换名称。例如，`https://github.com/organizations/octo-org/settings/apps/octo-app`。
`client_secret`	`string`	必填。 GitHub App的客户端密码。可以在应用的设置页上生成客户端密码。
`code`	`string`	必填。在上一步中收到的代码。
`redirect_uri`	`string`	用户获得授权后被发送到的应用程序中的 URL。此 URL 必须与在设置 GitHub App 时作为“回叫 URL”提供的 URL 之一完全匹配，并且不能包含任何附加参数。
`repository_id`	`string`	用户访问令牌可以访问的单个存储库的 ID。如果 GitHub App 或用户无法访问存储库，将忽略此项。使用此参数可进一步限制用户访问令牌的访问权限。

GitHub will give a response that includes the following parameters:

响应参数	类型	说明
`access_token`	`string`	用户访问令牌。令牌以 `ghu_` 开头。
`expires_in`	`integer`	`access_token` 过期前需经历的秒数。如果禁用了用户访问令牌的有效期限，将省略此参数。值将始终为 `28800`（8 小时）。
`refresh_token`	`string`	刷新令牌。如果禁用了用户访问令牌的有效期限，将省略此参数。令牌以 `ghr_` 开头。
`refresh_token_expires_in`	`integer`	`refresh_token` 过期前需经历的秒数。如果禁用了用户访问令牌的有效期限，将省略此参数。值将始终为 `15811200`（6 个月）。
`scope`	`string`	令牌具有的范围。此值将始终为空字符串。不同于传统的 OAuth 标记，用户访问令牌仅限于应用和用户拥有的权限。
`token_type`	`string`	令牌类型。值将始终为 `bearer`。

使用上一步中的用户访问令牌代表用户发出 API 请求。在 API 请求的 Authorization 标头中包含用户访问令牌。例如：

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

使用设备流生成用户访问令牌

注意：设备流处于公开测试阶段，可能会发生更改。

如果应用无外设应用或无权访问浏览器，应使用设备流来生成用户访问令牌。例如，CLI 工具、简单的 Raspberry Pi 和桌面应用程序应使用设备流。有关使用设备流的教程，请参阅“Building a CLI with a GitHub App”。

必须先在应用的设置中启用设备流，才能使用设备流。有关启用设备流的详细信息，请参阅“Modifying a GitHub App registration”。

设备流使用 OAuth 2.0 设备授权模式。

向 http(s)://HOSTNAME/login/device/code 发送 POST 请求和 client_id 查询参数。客户端 ID 不同于应用 ID。可以在应用的设置页上找到客户端 ID。
- 对于用户拥有的应用，设置页为 https://github.com/settings/apps/APP-SLUG。
- 对于组织拥有的应用，设置页为 https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG。
将 APP-SLUG 替换为应用的转换名称，将 ORGANIZATION 替换为组织的转换名称。例如 https://github.com/organizations/octo-org/settings/apps/octo-app。

GitHub 将做出包含以下查询参数的响应：

响应参数	类型	说明
`device_code`	`string`	用于验证设备的验证码。该验证码长度为 40 个字符。
`user_code`	`string`	应用程序应该显示的验证码，以便用户可以在浏览器中输入该验证码。此代码为 8 个字符，中间有连字符。例如，`WDJB-MJHT`。
`verification_uri`	`string`	用户需要在其中输入其 `user_code` 的 URL。该 URL 为： `https://HOSTNAME/login/device`。
`expires_in`	`integer`	`device_code` 和 `user_code` 过期之前的秒数。默认值为 900 秒（15 分钟）。
`interval`	`integer`	在能够发出新的访问令牌请求 (`POST http(s)://HOSTNAME/login/oauth/access_token`) 以完成设备授权之前必须经过的最短秒数。如果在经过此时间间隔前发出请求，则会达到速率限制并出现 `slow_down` 错误。默认值为 5 秒。

提示用户在 https://HOSTNAME/login/device 输入上一步中的 user_code。

如果用户未在 expires_in 时间内输入该代码，该代码会失效。在这种情况下，应重启设备流。

轮询 POST http(s)://HOSTNAME/login/oauth/access_token 以及 client_id、device_code 和 grant_type 查询参数（如下所述），直到设备和用户代码过期或用户通过输入 user_code 成功授权应用。

查询参数	类型	说明
`client_id`	`string`	必填。 GitHub App 的客户端 ID。
`device_code`	`string`	必填。在上一步中收到的设备验证码。
`grant_type`	`string`	必填。授权类型必须是 `urn:ietf:params:oauth:grant-type:device_code`。
`repository_id`	`string`	用户访问令牌可以访问的单个存储库的 ID。如果 GitHub App 或用户无法访问存储库，将忽略此项。使用此参数可进一步限制用户访问令牌的访问权限。

轮询此终结点的频率不要高于 interval 指示的频率。如果这样做，会达到速率限制并出现 slow_down 错误。 slow_down 错误响应向上一个 interval 添加 5 秒钟的时间。

在用户输入代码之前，GitHub 将做出响应，其中包含一个 200 状态和一个 error 响应查询参数。

错误名称	说明
`authorization_pending`	授权请求待处理并且用户尚未输入用户代码时，将发生此错误。应用应持续轮询 `POST http(s)://HOSTNAME/login/oauth/access_token`，且轮询频率低于 `interval` 指定的频率。
`slow_down`	收到 `slow_down` 错误时，会使用 `POST http(s)://HOSTNAME/login/oauth/access_token` 向请求之间所需的最短 `interval` 或时间范围添加 5 秒钟的额外时间。例如，如果请求之间的启动间隔至少需要 5 秒，并且你收到了 `slow_down` 错误响应，那么现在必须等待至少 10 秒，然后才能发出新的令牌请求。错误响应包括必须使用的新 `interval`。
`expired_token`	如果设备代码已过期，则将看到 `token_expired` 错误。您必须发出新的设备代码请求。
`unsupported_grant_type`	轮询 OAuth 令牌请求 `POST http(s)://HOSTNAME/login/oauth/access_token` 时，授权类型必须为 `urn:ietf:params:oauth:grant-type:device_code` 并且必须作为输入参数包含在内。
`incorrect_client_credentials`	对于设备流程，您必须传递应用程序的客户端 ID，您可以在应用程序设置页面上找到该 ID。客户端 ID 不同于应用程序 ID 和客户端密码。
`incorrect_device_code`	提供的 `device_code` 无效。
`access_denied`	当用户在授权过程中单击取消时，你将收到 `access_denied` 错误，该用户将无法再次使用验证码。
`device_flow_disabled`	尚未在应用的设置中启用设备流。有关启用设备流的详细信息，请参阅“Modifying a GitHub App registration”。

用户输入 user_code 后，GitHub 将做出包含以下查询参数的响应：

响应参数	类型	说明
`access_token`	`string`	用户访问令牌。令牌以 `ghu_` 开头。
`expires_in`	`integer`	`access_token` 过期前需经历的秒数。如果禁用了用户访问令牌的有效期限，将省略此参数。值将始终为 `28800`（8 小时）。
`refresh_token`	`string`	刷新令牌。如果禁用了用户访问令牌的有效期限，将省略此参数。令牌以 `ghr_` 开头。
`refresh_token_expires_in`	`integer`	`refresh_token` 过期前需经历的秒数。如果禁用了用户访问令牌的有效期限，将省略此参数。值将始终为 `15811200`（6 个月）。
`scope`	`string`	令牌具有的范围。此值将始终为空字符串。不同于传统的 OAuth 标记，用户访问令牌仅限于应用和用户拥有的权限。
`token_type`	`string`	令牌类型。值将始终为 `bearer`。

使用上一步中的用户访问令牌代表用户发出 API 请求。在 API 请求的 Authorization 标头中包含用户访问令牌。例如：

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

在用户安装应用时生成用户访问令牌

如果在应用设置中选择“在安装过程中请求用户授权(OAuth)”，GitHub 会在用户安装应用后立即启动 Web 应用程序流。

无论应用是安装在用户帐户上还是组织帐户上，都可以使用此方法生成用户访问令牌。但是，如果应用安装在组织帐户上，则需要使用 Web 应用程序流或设备流来为组织中的其他用户生成用户访问令牌。

当用户安装应用时，GitHub 会将用户重定向到 http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID，其中 CLIENT_ID 是应用的客户端 ID。
如果用户接受你的授权请求，GitHub 会将用户重定向到应用设置中的第一个回叫 URL，并提供 code 查询参数。

如果要控制使用的回叫 URL，请不要选择“在安装过程中请求用户授权(OAuth)”。而是要引导用户完成整个 Web 应用程序流，并指定 redirect_uri 参数。

通过向此 URL 发出 POST 请求以及以下查询参数，将上一步中的 code 换为用户访问令牌：http(s)://HOSTNAME/login/oauth/access_token

查询参数	类型	说明
`client_id`	`string`	必填。 GitHub App 的客户端 ID。客户端 ID 不同于应用 ID。可以在应用的设置页上找到客户端 ID。对于用户拥有的应用，设置页为 `https://github.com/settings/apps/APP-SLUG`。对于组织拥有的应用，设置页为 `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`。将 `APP-SLUG` 替换为应用的转换名称，将 `ORGANIZATION` 替换为组织的转换名称。例如，`https://github.com/organizations/octo-org/settings/apps/octo-app`。
`client_secret`	`string`	必填。 GitHub App的客户端密码。可以在应用的设置页上生成客户端密码。
`code`	`string`	必填。在上一步中收到的代码。
`redirect_uri`	`string`	用户获得授权后被发送到的应用程序中的 URL。此 URL 必须与在设置 GitHub App 时作为“回叫 URL”提供的 URL 之一完全匹配，并且不能包含任何附加参数。
`repository_id`	`string`	用户访问令牌可以访问的单个存储库的 ID。如果 GitHub App 或用户无法访问存储库，将忽略此项。使用此参数可进一步限制用户访问令牌的访问权限。

GitHub will give a response that includes the following parameters:

响应参数	类型	说明
`access_token`	`string`	用户访问令牌。令牌以 `ghu_` 开头。
`expires_in`	`integer`	`access_token` 过期前需经历的秒数。如果禁用了用户访问令牌的有效期限，将省略此参数。值将始终为 `28800`（8 小时）。
`refresh_token`	`string`	刷新令牌。如果禁用了用户访问令牌的有效期限，将省略此参数。令牌以 `ghr_` 开头。
`refresh_token_expires_in`	`integer`	`refresh_token` 过期前需经历的秒数。如果禁用了用户访问令牌的有效期限，将省略此参数。值将始终为 `15811200`（6 个月）。
`scope`	`string`	令牌具有的范围。此值将始终为空字符串。不同于传统的 OAuth 标记，用户访问令牌仅限于应用和用户拥有的权限。
`token_type`	`string`	令牌类型。值将始终为 `bearer`。

使用上一步中的用户访问令牌代表用户发出 API 请求。在 API 请求的 Authorization 标头中包含用户访问令牌。例如：

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

获取源

列出用户访问令牌可访问的存储库

列出问题事件

议题时间表

列出问题的时间线事件

元数据

获取存储库的行为准则

仓库内容

仓库事件调度

创建存储库调度事件

为 GitHub 应用生成用户访问令牌

本文内容