此版本的 GitHub Enterprise 已停止服务 2021-09-23. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

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

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

注:过期用户令牌目前是用户到服务器令牌过期的一部分,可能会更改。 要选择使用用户到服务器令牌过期测试功能,请参阅“激活应用程序的可选功能”。 更多信息请参阅“GitHub 应用程序过期用户到服务器访问令牌”。

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

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

识别站点上的用户

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

Web 应用程序流程

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

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

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

1. 请求用户的 GitHub 身份

Direct the user to the following URL in their browser:

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

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

参数

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

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

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

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

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

将此 code 交换为访问令牌。 When expiring tokens are enabled, the access token expires in 8 hours and the refresh token expires in 6 months. 每次刷新令牌时都会得到一个新的刷新令牌。 更多信息请参阅“刷新用户到服务器访问令牌”。

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

Make a request to the following endpoint to receive an access token:

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 步提供的不可猜测的随机字符串。

响应

默认情况下,响应采用以下形式。 响应参数 expires_inrefresh_tokenrefresh_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

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

获得用户的 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 v4REST v3 端点发出以下请求。

支持的端点

检查运行

检查套件

行为准则

部署状态

部署

事件

馈送

Git Blob

Git 提交

Git 引用

Git 标记

Git 树

Gitignore 模板

安装设施

议题受理人

议题评论

议题事件

议题时间表

议题

标签

许可

Markdown

元数据

里程碑

组织挂钩

组织成员

组织外部协作者

组织预接收挂钩

组织团队项目

组织团队仓库

组织团队

组织

项目协作者

项目

拉取注释

拉取请求审查事件

拉取请求审查请求

拉取请求审查

拉取

反应

仓库

仓库活动

仓库分支

仓库协作者

仓库提交注释

仓库提交

仓库社区

仓库内容

仓库事件调度

仓库挂钩

仓库邀请

仓库密钥

仓库页面

仓库预接收挂钩

仓库发行版

仓库统计

状态

团队讨论

主题

用户电子邮件

用户关注者

用户 Gpg 密钥

用户公钥

用户