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

GitHub 应用程序可以代表用户执行操作，例如创建议题、创建部署和使用其他受支持的端点。

本文内容

识别站点上的用户
Web 应用程序流程
检查用户可以访问哪些安装资源
处理已撤销的 GitHub 应用程序授权
用户级别的权限
用户到服务器请求

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

识别站点上的用户

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

Web 应用程序流程

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

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

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

1. 请求用户的 GitHub 身份

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

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

参数

名称	类型	描述
`client_id`	`字符串`	必填。GitHub 应用程序的客户端 ID。选择应用程序时，您可以在 GitHub 应用程序设置中找到它。
`redirect_uri`	`字符串`	用户获得授权后被发送到的应用程序中的 URL。它必须完全匹配设置 GitHub 应用程序时在 User authorization callback URL（用户授权回调 URL）字段中提供的 URL，并且不能包含任何其他参数。
`state`	`字符串`	它应该包含一个随机字符串以防止伪造攻击，并且可以包含任何其他任意数据。
`login`	`字符串`	提供用于登录和授权应用程序的特定账户。

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

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

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

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

将此 code 交换为访问令牌。

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

参数

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

响应

默认情况下，响应采用以下形式：

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&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

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

注：要使用 GitHub 应用程序访问 API，您必须在请求的 Accept 标头中提供自定义媒体类型。

application/vnd.github.machine-man-preview+json

警告： 在预览期间，API 可能会更改，恕不另行通知。预览功能不支持用于生产。如果遇到任何问题，请联系您的站点管理员。

获得用户的 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 错误。