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

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

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

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

识别站点上的用户

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

Web 应用程序流程

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

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

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

1. 请求用户的 GitHub 身份

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 交换为访问令牌。

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 错误。

用户级别的权限

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

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

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

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

用户到服务器请求

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

支持的端点

检查运行
检查套件
行为准则
部署状态
部署
事件
馈送
Git Blob
Git 提交
Git 引用
Git 标记
Git 树
Gitignore 模板
安装设施
议题受理人
议题评论
议题事件
议题时间表
议题
标签
许可
Markdown
元数据
里程碑
组织挂钩
组织成员
组织外部协作者
组织预接收挂钩
组织团队项目
组织团队仓库
组织团队
组织
项目协作者
项目
拉取注释
拉取请求审查事件
拉取请求审查请求
拉取请求审查
拉取
反应
仓库
仓库活动
仓库分支
仓库协作者
仓库提交注释
仓库提交
仓库社区
仓库内容
仓库事件调度
仓库挂钩
仓库邀请
仓库密钥
仓库页面
仓库预接收挂钩
仓库发行版
仓库统计
搜索
状态
团队讨论
主题
用户电子邮件
用户关注者
用户 Gpg 密钥
用户公钥
用户