{"meta":{"title":"OAuth 应用的范围","intro":"通过作用域，您可以准确指定所需的访问权限类型。 作用域限制 OAuth 标记的访问权限。 它们不会授予超出用户权限范围的任何额外权限。","product":"应用","breadcrumbs":[{"href":"/zh/apps","title":"应用"},{"href":"/zh/apps/oauth-apps","title":"OAuth 应用"},{"href":"/zh/apps/oauth-apps/building-oauth-apps","title":"构建 OAuth 应用"},{"href":"/zh/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps","title":"OAuth 应用的范围"}],"documentType":"article"},"body":"# OAuth 应用的范围\n\n通过作用域，您可以准确指定所需的访问权限类型。 作用域限制 OAuth 标记的访问权限。 它们不会授予超出用户权限范围的任何额外权限。\n\n> \\[!NOTE]\n> 请考虑构建GitHub App，而不是OAuth app。\n> GitHub Apps 使用细粒度的权限，而不是范围，这样可以更好地控制应用可以执行的操作。 有关详细信息，请参阅 [GitHub 应用和 OAuth 应用之间的差异](/zh/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) 和 [关于创建GitHub应用](/zh/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)。\n\n在 GitHub 上设置OAuth app时，所请求的权限范围会显示在授权表单中，供用户查看。\n\n> \\[!NOTE]\n> 如果您要构建GitHub App，则无需在授权请求中提供作用域。 有关详细信息，请参阅“[代表用户使用 GitHub 应用进行身份验证](/zh/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)”。\n\n检查标头以查看您拥有哪些 OAuth 作用域，以及 API 操作接受什么：\n\n```shell\n$ curl -H \"Authorization: Bearer OAUTH-TOKEN\" https://api.github.com/users/codertocat -I\nHTTP/2 200\nX-OAuth-Scopes: repo, user\nX-Accepted-OAuth-Scopes: user\n```\n\n* `X-OAuth-Scopes` 列出令牌已授权的范围。\n* `X-Accepted-OAuth-Scopes` 列出操作检查的范围。\n\n## 可用的范围\n\n| 名称 | 描述 |\n| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`(no scope)`** | 授予对公共信息的只读访问权限（包括用户个人资料信息、存储库信息和代码片段） |\n| **`repo`** | 授予对公共 和专用存储库的完全访问权限，包括对代码的读取和写入访问权限、提交状态、存储库邀请、协作者、部署状态和存储库 Webhook。 |\n| **注意：** 除了存储库相关资源外，`repo` 范围还授予对组织拥有的资源（包括项目、邀请、团队成员身份和 Webhook）的管理权限。 此范围还授予对用户所拥有的项目的管理权限。 | |\n| `repo:status` | 授予对 公开和私有仓库中的提交状态的读/写访问权限。 仅在向其他用户或服务授予对专用存储库提交状态的访问权限而不授予对代码的访问权限时，才需要此范围。 |\n| `repo_deployment` | 授予对公共和专用仓库的[部署状态](/zh/rest/repos#deployments)的访问权限。 仅在向其他用户或服务授予对部署状态的访问权限而“不”\\_\\_ 授予对代码的访问权限时，才需要此范围。 |\n| `public_repo` | 限制对公共存储库的访问权限。 这包括对公共仓库和组织的代码、提交状态、仓库项目、协作者以及部署状态的读取/写入权限。 带有星标的公共存储库也需要此权限。 |\n| `repo:invite` | 授予接受/拒绝仓库协作邀请的权限。 仅在向其他用户或服务授予对邀请的访问权限而“不”\\_\\_ 授予对代码的访问权限时，才需要此作用域。 |\n| `security_events` | 授予下列权限：
对[code scanning API](/zh/rest/code-scanning)中安全事件的读写访问权限
仅当您希望向其他用户或服务授予访问安全事件的权限，而不授予对代码的访问权限时，才需要此作用域。 |\n| **`admin:repo_hook`** | 授予对 公共或私有 仓库中的仓库钩子的读取、写入、ping 操作和删除权限。 |\n| `repo` 和 `public_repo` 作用域提供对存储库（包括存储库挂钩）的完全访问权限。 使用 `admin:repo_hook` 范围将访问权限限制为仅存储库挂钩。 | |\n| `write:repo_hook` | 授予对 公共或私有仓库中的钩子的读取、写入和 ping 访问权限。 |\n| `read:repo_hook` | 授予对 公共或私有仓库中的钩子的读取和 ping 访问权限。 |\n| **`admin:org`** | 全面管理组织及其团队、项目和成员。 |\n| `write:org` | 对组织成员身份和组织项目的读写权限。 |\n| `read:org` | 对组织成员身份、组织项目和团队成员身份的只读权限。 |\n| **`admin:public_key`** | 全面管理公钥。 |\n| `write:public_key` | 创建、列出和查看公钥的详细信息。 |\n| `read:public_key` | 列出和查看公钥的详细信息。 |\n| **`admin:org_hook`** | 授予对组织挂钩的读取、写入、ping 和删除权限。 |\n| **注意：** OAuth 令牌只能对由 OAuth app 创建的组织钩子执行这些操作。 | |\n| Personal access tokens 只能对由用户创建的组织钩子执行这些操作。 | |\n| **`gist`** | 授予对 Gist 的写权限。 |\n| **`notifications`** | 授予下列权限：
对用户的通知的读取访问权限
对会话的“标记为读取”访问权限
对存储库的监视和取消监视访问权限，以及
对会话订阅的读取、写入和删除访问权限。 |\n| **`user`** | 仅授予对个人资料的读写权限。 请注意，此范围包括 `user:email` 和 `user:follow`。 |\n| `read:user` | 授予对用户个人资料数据的读取权限。 |\n| `user:email` | 授予对用户电子邮件地址的读取权限。 |\n| `user:follow` | 授予对关注或取消关注其他用户的访问权限。 |\n| **`project`** | 授予对用户和组织项目的读/写访问权限。 |\n| `read:project` | 授予对用户和组织的只读访问权限项目。 |\n| **`delete_repo`** | 授予删除可管理的仓库的权限。 |\n| **`write:packages`** | 授予在 GitHub Packages 中上传或发布包的权限。 有关详细信息，请参阅“[发布包](/zh/packages/learn-github-packages/publishing-a-package)”。 |\n| **`read:packages`** | 授予从 GitHub Packages 下载或安装软件包的权限。 有关详细信息，请参阅“[安装一个包](/zh/packages/learn-github-packages/installing-a-package)”。 |\n| **`delete:packages`** | 授予从 GitHub Packages 删除软件包的权限。 有关详细信息，请参阅“[删除和恢复包](/zh/packages/learn-github-packages/deleting-and-restoring-a-package)”。 |\n| **`admin:gpg_key`** | 全面管理 GPG 密钥。 |\n| `write:gpg_key` | 创建、列出和查看 GPG 密钥的详细信息。 |\n| `read:gpg_key` | 列出和查看 GPG 密钥的详细信息。 |\n| **`codespace`** | 授予创建和管理 Codespace 的权限。 Codespaces 可以暴露可能有不同范围集的 GITHUB\\_TOKEN。 有关详细信息，请参阅 [GitHub Codespaces 中的安全性](/zh/codespaces/reference/security-in-github-codespaces#authentication)。 |\n| **`workflow`** | 授予添加和更新 GitHub Actions 工作流文件的能力。 如果在同一仓库中的另一个分支上存在相同的文件(具有相同的路径和内容)，则工作流程文件可以在没有此作用域的情况下提交。 工作流文件可以公开`GITHUB_TOKEN`，而`GITHUB_TOKEN`可能拥有不同的范围集。 有关详细信息，请参阅 [在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token)。 |\n| **`read:audit_log`** | 读取审核日志数据。 |\n| **`offline_access`** | 请求即将过期的访问令牌和刷新令牌，即使 OAuth app 未配置为使用过期令牌也是如此。 使用此范围可以测试和逐步推出对过期令牌的支持。 有关详细信息，请参阅 [授权 OAuth 应用](/zh/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#expiring-access-tokens)。 |\n\n> \\[!NOTE]\n> 您的 OAuth app 可以在初始授权请求中请求作用域。 可使用 `%20` 以空格分隔多个范围来指定它们：\n>\n> ```text\n> https://github.com/login/oauth/authorize?\n> client_id=...&\n> scope=user%20repo_deployment\n> ```\n\n## 请求的作用域和授予的作用域\n\n`scope` 属性列出了附加到用户授予的令牌的范围。 通常，这些作用域与您请求的作用域相同。\n但是，用户可以编辑其范围，实际授予应用程序更少的权限（相比你最初请求的权限）。 此外，用户还可以在 OAuth 流程完成后编辑令牌范围。\n你应该意识到这种可能性，并相应地调整应用程序的行为。\n\n如果用户选择授予更少的权限（相比你最初请求的权限），妥善处理这种错误情况非常重要。 例如，应用程序可以警告或以其他方式告诉用户，他们可用的功能会减少或者无法执行某些操作。\n\n此外，应用程序可以随时引导用户回到流程，以获取更多权限，但不要忘记，用户总是可以拒绝。\n\n请查看[身份验证基础知识指南](/zh/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app)，其中提供了有关处理可修改令牌范围的提示。\n\n## 标准化范围\n\n请求多个范围时，将用标准化的范围列表保存令牌，而放弃其他请求的范围隐式包含的那些范围。 例如，请求 `user,gist,user:email` 将生成仅具有 `user` 和 `gist` 范围的令牌，因为使用 `user:email` 范围授予的权限包含在 `user` 范围中。"}