Skip to main content

OAuth 应用程序的作用域

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

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

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

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

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

$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
  • X-OAuth-Scopes 列出令牌已授权的作用域。
  • X-Accepted-OAuth-Scopes 列出操作检查的作用域。

可用作用域

名称描述
(无作用域)授予对公共信息的只读访问权限(包括用户个人资料信息、公共仓库信息和 gist)
repoGrants full access to public, internal, and private repositories including read and write access to code, commit statuses, repository invitations, collaborators, deployment statuses, and repository webhooks. Note: In addition to repository related resources, the repo scope also grants access to manage organization-owned resources including projects, invitations, team memberships and webhooks. This scope also grants the ability to manage projects owned by users.
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授予关注或取消关注其他用户的权限。
projectGrants read/write access to user and organization projects.
read:projectGrants read only access to user and organization projects.
delete_repo授予删除可管理仓库的权限。
write:discussion授予对团队讨论的读取和写入权限。
read:discussion允许对团队讨论进行读取访问。
write:packages授予在 GitHub Packages 中上传或发布包的权限。 更多信息请参阅“发布包”。
read:packages授予从 GitHub Packages 下载或安装包的权限。 更多信息请参阅“安装包”。
delete:packages授予从 GitHub Packages 删除包的权限。 更多信息请参阅“删除和恢复软件包”。
admin:gpg_key全面管理 GPG 密钥。
write:gpg_key创建、列出和查看 GPG 密钥的详细信息。
read:gpg_key列出和查看 GPG 密钥的详细信息。
代码空间授予创建和管理代码空间的能力。 Codespaces 可以暴露可能有不同范围集的 GITHUB_TOKEN。 更多信息请参阅“GitHub Codespaces 中的安全性”。
工作流程授予添加和更新 GitHub Actions 工作流程文件的权限。 如果在同一仓库中的另一个分支上存在相同的文件(具有相同的路径和内容),则工作流程文件可以在没有此作用域的情况下提交。 工作流程文件可以暴露可能有不同范围集的 GITHUB_TOKEN。 更多信息请参阅“工作流程中的身份验证

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

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

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

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

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

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

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

标准化作用域

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