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

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

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

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

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

识别站点上的用户

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

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

Web 应用程序流程

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

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

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

1. 请求用户的 GitHub 身份

Direct the user to the following URL in their browser:

GET https://github.com/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 将重定向回您的站点,其中,代码参数为临时 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 https://github.com/login/oauth/access_token

参数

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

响应

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

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

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

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

Authorization: token OAUTH-TOKEN
GET https://api.github.com/user

例如,您可以像以下这样在 curl 中设置“授权”标头:

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/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 v4REST v3 端点发出以下请求。

支持的端点

操作运行器

操作密钥

构件

检查运行

检查套件

行为准则

部署状态

部署

事件

馈送

Git Blob

Git 提交

Git 引用

Git 标记

Git 树

Gitignore 模板

安装设施

交互限制

议题受理人

议题评论

议题事件

议题时间表

议题

Jobs

标签

许可

Markdown

元数据

里程碑

组织挂钩

组织邀请

组织成员

组织外部协作者

组织团队项目

组织团队仓库

组织团队同步

组织团队

组织

组织凭据授权

组织 SCIM

源导入

项目协作者

项目

拉取注释

拉取请求审查事件

拉取请求审查请求

拉取请求审查

拉取

反应

仓库

仓库活动

仓库自动安全修复

仓库分支

仓库协作者

仓库提交注释

仓库提交

仓库社区

仓库内容

仓库事件调度

仓库挂钩

仓库邀请

仓库密钥

仓库页面

仓库发行版

仓库统计

仓库漏洞警报

状态

团队讨论

主题

流量

用户阻止

用户电子邮件

用户关注者

用户 Gpg 密钥

用户公钥

用户

工作流程运行

工作流程

延伸阅读

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。