识别和授权 GitHub 应用程序用户

注：过期用户令牌目前是可选功能，可能会更改。要选择使用或退出用户到服务器令牌过期功能，请参阅“激活应用程序的可选功能”。更多信息请参阅“GitHub 应用程序过期用户到服务器访问令牌”。

当 GitHub 应用程序代表用户时，它执行用户到服务器请求。这些请求必须使用用户的访问令牌进行授权。用户到服务器请求包括请求用户的数据，例如确定要向特定用户显示哪些仓库。这些请求还包括用户触发的操作，例如运行构建。

为使用户到服务器的访问令牌更安全，您可以使用将在 8 小时后过期的访问令牌，以及可交换新访问令牌的刷新令牌。更多信息请参阅“刷新用户到服务器访问令牌”。

识别站点上的用户

要授权用户使用在浏览器中运行的� �准应用程序，请使用 web 应用程序流程。

要授权用户使用不直接访问浏览器的� 头应用程序（例如 CLI 工具或 Git 凭据管理器），请使用设备流程。设备流程使用 OAuth 2.0 设备授权授予。

Web 应用程序流程

使用 web 应用程序流程时，识别您站点上用户的过程如下：

用户被重定向，以请求他们的 GitHub 身份
用户被 GitHub 重定向回您的站点
您的 GitHub 应用程序使用用户的访问令牌访问 API

如果您在创建或修改应用程序时选择在安装过程中请求用户授权 (OAuth)，则步骤 1 将在应用程序安装过程中完成。更多信息请参阅“在安装过程中授权用户”。

1. 请求用户的 GitHub 身份

将用户引导到其浏览器中的以下URL：

GET http(s)://[hostname]/login/oauth/authorize

当您的 GitHub 应用程序指定 login 参数后，它将提示拥有特定账户的用户可以用来登录和授权您的应用程序。

参数

名称	类型	描述
`client_id`	`字符串`	必填。GitHub 应用程序的客户端 ID。选择应用程序时，您可以在 GitHub 应用程序设置中找到它。注意：应用程序 ID 和客户端 ID 不相同，� 法互换。
`redirect_uri`	`字符串`	用户获得授权后被发送到的应用程序中的 URL。它必须完全匹配设置 GitHub 应用程序时作为 Callback URL（回调 URL）提供的 URL 之一，并且不能包含任何其他参数。
`state`	`字符串`	它应该包含一个随机字符串以防止伪� 攻击，并且可以包含任何其他任意数据。
`login`	`字符串`	提供用于登录和授权应用程序的特定账户。
`allow_signup`	`字符串`	在 OAuth 流程中，是否向经过验证的用户提供注册 GitHub 的选项。默认值为 `true`。如有政策禁止注册，请使用 `false`。

注：不需要在授权请求中提供作用域。不同于� 统的 OAuth，授权令牌仅限于与您的 GitHub 应用程序和用户的应用程序相关联的权限。

2. 用户被 GitHub 重定向回您的站点

如果用户接受您的请求，GitHub 将重定向回您的站点，其中，代� �参数为临时 code，state 参数为您在上一步提供的状态。如果状态不匹配，则请求是由第三方创建的，该过程应中止。

注：如果您在创建或修改应用程序时选择在安装过程中请求用户授权 (OAuth)，则 GitHub 将返回需要交换访问令牌的临时 code。当 GitHub 在应用程序安装过程中启动 OAuth 流程时，不会返回 state 参数。

将此 code 交换为访问令牌。启用令牌有效期时，访问令牌在 8 小时后过期，刷新令牌在 6 个月后过期。每次刷新令牌时都会得到一个新的刷新令牌。更多信息请参阅“刷新用户到服务器访问令牌”。

过期用户令牌目前是一个可选的功能，可能会更改。要选择使用用户到服务器令牌过期功能，请参阅“激活应用程序的可选功能”。

向以下端点提出请求以接收访问令牌：

POST http(s)://[hostname]/login/oauth/access_token

参数

名称	类型	描述
`client_id`	`字符串`	必填。GitHub 应用程序的客户端 ID。
`client_secret`	`字符串`	必填。GitHub 应用程序的客户端密钥。
`代� �`	`字符串`	必填。您收到的响应第 1 步的代� �。
`redirect_uri`	`字符串`	用户获得授权后被发送到的应用程序中的 URL。它必须完全匹配设置 GitHub 应用程序时作为 Callback URL（回调 URL）提供的 URL 之一，并且不能包含任何其他参数。
`state`	`字符串`	您在第 1 步提供的不可猜测的随机字符串。

响应

默认情况下，响应采用以下形式。响应参数 expires_in、refresh_token 和 refresh_token_expires_in 仅当您启用过期用户到服务器访问令牌功能时才会返回。

{
  "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "expires_in": 28800,
  "refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

3. 您的 GitHub 应用程序使用用户的访问令牌访问 API

用户的访问令牌允许 GitHub 应用程序代表用户向 API 发出请求。

Authorization: token OAUTH-TOKEN
GET http(s)://[hostname]/api/v3/user

例如，您可以像以下这� �在 curl 中设置“授权”� �头：

curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user

设备流程

注：设备流程处于公开测试阶段，可能会有变化。

设备流程允许您授权用户使用� 头应用程序，例如 CLI 工具或 Git 凭据管理器。

有关使用设备流程授权用户的更多信息，请参阅“授权 OAuth 应用程序”。

检查用户可以访问哪些安装资源

获得用户的 OAuth 令牌后，您可以检查该用户可以访问哪些安装。

Authorization: token OAUTH-TOKEN
GET /user/installations

您还可以检查用户可以访问哪些仓库进行安装。

Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

更多信息请参阅：列出用户访问令牌可访问的应用程序安装和列出用户访问令牌可访问的仓库。

处理已撤销的 GitHub 应用程序授权

默认情况下，如果用户撤销对 GitHub 应用程序的授权，该应用程序将收到 github_app_authorization web 挂钩。 GitHub 应用程序� 法取消订阅此事件。任何人都可以从 GitHub 帐户设置页面撤销他们对 GitHub 应用程序的授权。撤销对 GitHub 应用程序的授权不会卸载 GitHub 应用程序。您应该编程 GitHub 应用程序，使其在收到此 web 挂钩后，不再代表已撤销令牌的人调用 API。如果 GitHub 应用程序继续使用已撤销的访问令牌，它将收到 401 Bad Credentials 错误。

用户级别的权限

您可以向 GitHub 应用程序添� 用户级别的权限，以访问用户电子邮件等用户资源，这些权限是单个用户在用户授权流程中授予的。用户级别的权限不同于仓库和组织级别的权限，后者是在组织或个人帐户上安装时授予的。

您可以在 Permissions & webhooks（权限和 web 挂钩）页面 User permissions（用户权限）部分的 GitHub 应用程序设置中选择用户级别的权限。有关选择权限的更多信息，请参阅“编辑 GitHub 应用程序的权限”。

当用户在他们的帐户上安装您的应用程序时，安装提示将列出应用程序请求的用户级别权限，并说明应用程序会向各个用户请求这些权限。

由于用户级别的权限是基于单个用户授予的，� 此您可以将它们添� 到现有应用中，而� 需提示用户升级。但是，您需要通过用户授权流程发送现有用户，以授权新权限并为这些请求获取新的用户到服务器令牌。

用户到服务器请求

虽然大多数 API 交互应使用服务器到服务器安装访问令牌进行，但某些端点允许您使用用户访问令牌通过 API 执行操作。您的应用程序可以使用GraphQL 或 REST 端点发出以下请求。

识别和授权 GitHub 应用程序用户

本文内容

识别站点上的用户

Web 应用程序流程

1. 请求用户的 GitHub 身份

参数

2. 用户被 GitHub 重定向回您的站点

参数

响应

3. 您的 GitHub 应用程序使用用户的访问令牌访问 API

设备流程

检查用户可以访问哪些安装资源

处理已撤销的 GitHub 应用程序授权

用户级别的权限

用户到服务器请求

支持的端点

检查运行

检查套件

行为准则

部署状态

部署

事件

馈送

Git Blob

Git 提交

Git 引用

Git � �记

Git � �

Gitignore 模板

安装设施

议题受理人

议题评论

议题事件

议题时间表

议题

� �签

许可

Markdown

元数据

里程碑

组织挂钩

组织成员

组织外部协作者

组织预接收挂钩

组织团队项目

组织团队仓库

组织团队

组织

项目协作者

项目

拉取注释

拉取请求审查事件

拉取请求审查请求

拉取请求审查

拉取

反应

仓库

仓库活动

仓库分支

仓库协作者

仓库提交注释

仓库提交

仓库社区

仓库内容

仓库事件调度

仓库挂钩

仓库邀请

仓库密钥

仓库页面

仓库预接收挂钩

仓库发行版

仓库统计

� �

搜索

状态

团队讨论

主题

用户电子邮件

用户关注者

用户 Gpg 密钥