OAuth 应用程序的作用域

通过作用域,您可以准确指定所需的访问权限类型。 作用域限制 OAuth 令牌的访问权限。 它们不会授予超出用户权限范围的任何额外权限。

在 GitHub 上设置 OAuth 应用程序时,请求的作用域会在授权表单上显示给用户。

:如果您在构建 GitHub 应用程序,则不需要在授权请求中提供作用域。 更多信息请参阅“识别和授权 GitHub 应用程序用户”。

如果 OAuth 应用程序 无法访问浏览器(如 CLI 工具),则无需为用户指定向应用程序验证的作用域。 更多信息请参阅“授权 OAuth 应用程序”。

检查标头以查看您拥有哪些 OAuth 作用域,以及 API 操作接受什么:

$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
  • X-OAuth-Scopes 列出令牌已授权的作用域。
  • X-Accepted-OAuth-Scopes 列出操作检查的作用域。

可用作用域

名称描述
(无作用域)授予对公共信息的只读访问权限(包括用户个人资料信息、公共仓库信息和 gist)
site_admin授予站点管理员对 GitHub Enterprise Server 管理 API 端点的访问权限。
repo授予对仓库(包括私有仓库)的完全访问权限。 这包括对仓库和组织的代码、提交状态、仓库和组织项目、邀请、协作者、添加团队成员身份、部署状态以及仓库 web 挂钩的读取/写入权限。 还授予管理用户项目的权限。
repo:status授予对公共和私有仓库提交状态的读/写权限。 仅在授予其他用户或服务对私有仓库提交状态的访问权限而授予对代码的访问权限时,才需要此作用域。
repo_deployment授予对公共和私有仓库的部署状态的访问权限。 仅在授予其他用户或服务对部署状态的访问权限而授予对代码的访问权限时,才需要此作用域。
public_repo将访问权限限制为公共仓库。 这包括对公共仓库和组织的代码、提交状态、仓库项目、协作者以及部署状态的读取/写入权限。 标星公共仓库也需要此权限。
repo:invite授予接受/拒绝仓库协作邀请的权限。 仅在授予其他用户或服务对邀请的访问权限而授予对代码的访问权限时,才需要此作用域。
security_events授予:
代码扫描 API 中安全事件的读取和写入权限
秘密扫描 API 中安全事件的读取和写入权限
仅在授予其他用户或服务对安全事件的访问权限而授予对代码的访问权限时,才需要此作用域。
admin:repo_hook授予对公共和私人仓库中仓库挂钩的读取、写入、ping 和删除权限。 repopublic_repo 范围授予对仓库(包括仓库挂钩)的完全访问权限。 使用 admin:repo_hook 作用域将访问权限限制为仅仓库挂钩。
write:repo_hook授予对公共或私人仓库中仓库挂钩的读取、写入和 ping 权限。
read:repo_hook授予对公共或私人仓库中仓库挂钩的读取和 ping 权限。
admin:org全面管理组织及其团队、项目和成员。
write:org对组织成员身份、组织项目和团队成员身份的读取和写入权限。
read:org对组织成员身份、组织项目和团队成员身份的只读权限。
admin:public_key全面管理公钥。
write:public_key创建、列出和查看公钥的详细信息。
read:public_key列出和查看公钥的详细信息。
admin:org_hook授予对组织挂钩的读取、写入、ping 和删除权限。 注:OAuth 令牌只能对由 OAuth 应用程序创建的组织挂钩执行这些操作。 个人访问令牌只能对用户创建的组织挂钩执行这些操作。
gist授予对 gist 的写入权限。
通知授予:
对用户通知的读取权限
对线程的标记读取权限
对仓库的关注和取消关注权限,以及
对线程订阅的读取、写入和删除权限。
用户仅授予对个人资料的读取/写入权限。 请注意,此作用域包括 user:emailuser:follow
read:user授予读取用户个人资料数据的权限。
user:email授予对用户电子邮件地址的读取权限。
user:follow授予关注或取消关注其他用户的权限。
delete_repo授予删除可管理仓库的权限。
write:discussion授予对团队讨论的读取和写入权限。
read:discussion授予对团队讨论的读取权限。
admin:gpg_key全面管理 GPG 密钥。
write:gpg_key创建、列出和查看 GPG 密钥的详细信息。
read:gpg_key列出和查看 GPG 密钥的详细信息。

注:您的 OAuth 应用程序可以在初始重定向中请求作用域。 您可以使用 %20 以空格分隔多个作用域来指定它们:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user%20repo_deployment

请求的作用域和授予的作用域

scope 属性列出了用户授予的附加到令牌的作用域。 通常,这些作用域与您请求的作用域相同。 但是,用户可以编辑其作用域,实际上授予应用程序更少的权限(相比您最初请求的权限)。 此外,用户还可以在 OAuth 流程完成后编辑令牌作用域。 您应该意识到这种可能性,并相应地调整应用程序的行为。

如果用户选择授予更少的权限(相比您最初请求的权限),妥善处理这种错误情况非常重要。 例如,应用程序可以警告或以其他方式告诉用户,他们可用的功能会减少或者无法执行某些操作。

此外,应用程序总是可以将用户送回流程以获取更多权限,但不要忘记,用户总是可以说不。

请查看身份验证基础知识指南,其中提供了有关处理可修改令牌作用域的提示。

标准化作用域

请求多个作用域时,将用标准化的作用域列表保存令牌,而放弃其他请求的作用域隐式包含的那些作用域。 例如,请求 user,gist,user:email 将生成仅具有 usergist 作用域的令牌,因为使用 user:email 作用域授予的权限包含在 user 作用域中。

此文档对您有帮助吗?

隐私政策

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

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

做出贡献

或者, 了解如何参与。