APIOAuth产品新闻开发人员开发人员平台智能体身份

从全有或全无到基于任务的 OAuth 授权

Miller Vargas、Adam Bouhmad和José Enrique Rodríguez

阅读时间：5 分钟

本文另有 English和繁體中文.

自六月以来，开发人员已在 Cloudflare 上创建了数千个第三方 OAuth 应用，至今授权次数已超过一百万次。

OAuth 实现了委托访问。它允许应用代表用户执行操作，而无需用户处理长期有效的凭据或交出密码。当应用能够以少量权限范围描述其访问需求时，这一模型运作良好。

开发人员将 OAuth 用于 SaaS 集成、内部工具、CLI 工具以及 AI 代理。随着时间推移，我们的权限模型已变得更加精细，以便更好地划定这些不同工作流的权限边界。这对安全性大有裨益，但也使纯粹的全有或全无授权同意页面愈发难以为继。

Cloudflare OAuth 已允许客户端请求其已配置权限范围的子集。但一旦客户端发出请求，用户就无法在授权同意页面上进一步缩小范围。对于授权同意页面上的用户而言，体验仍然是全有或全无。如果应用请求的访问权限超出用户愿意授予的范围，用户只有两个选择：批准全部请求，或直接拒绝。

BLOG-3481 3.gif

MCP 服务器就是一个典型例子。MCP 服务器可能会请求一组宽泛的权限，因为理论上 AI 代理可能用到所有这些权限。但大多数用户并不希望 AI 代理拥有如此广泛的访问权限。在此功能推出之前，处理这一问题的唯一方式，是让应用开发人员在将用户引导至我们的授权同意流程之前，自行构建一个自定义权限范围选择页面。

今天，我们正式推出 OAuth 权限范围自定义功能。客户端所有者在配置 OAuth 客户端时，可以将特定权限范围标记为可选，从而让用户能够在授权时仅授予应用所请求访问权限的一个更窄子集。

OAuth 规范已允许授权服务器授予比请求范围更窄的权限范围集合。我们在这一灵活性基础上加以构建，使其能够为每个现有应用干净利落地运作。

更多掌控权，而不令用户不知所措

引入权限范围选择功能的目标，是为注重安全的用户提供更大的灵活性，让其能够针对自身使用场景做出正确选择——同时不将授权同意页面变成冗长的权限范围清单。

借助权限范围自定义功能： 

  • 开发人员可以将 OAuth 客户端上的特定权限范围标记为必选或可选
  • 在授权时，用户可以从请求的权限范围集合中取消勾选可选权限范围
  • 必选和可选权限范围仅针对该次授权流程所请求的权限范围进行评估
  • 如果未请求任何可选权限范围，授权同意体验保持不变
  • 默认情况下，授权同意页面仍将授予所有被请求的权限范围
BLOG-3481 4.gif

权限范围限定于授权请求

一个重要细节是：必选和可选权限范围仅针对特定授权流程中所请求的权限范围进行评估，而不是根据客户端配置的所有权限范围进行评估。这一点至关重要，因为 OAuth 客户端并非总是请求其配置的全部权限范围。

例如，某客户端可能配置了 user-details.read、workers-scripts.write、workers-kv-storage.write 和 zone.read 权限，同时将 workers-kv-storage.write 和 zone.read 标记为可选。如果该客户端发起授权流程并请求全部四个权限范围，授权同意页面将对所有四个权限范围进行评估。在这种情况下，user-details.read 和 workers-scripts.write 仍是必需权限，但用户可以选择是否授予 workers-kv-storage.write 和 zone.read 权限。

但是，如果该客户端稍后仅请求 workers-scripts.write 和 zone.read 权限，则该授权流程仅考虑这两个权限范围。user-details.read 和 workers-kv-storage.write 将不会显示，也不会强制执行，因为它们不在请求范围之列。

这使授权同意页面聚焦于当前任务，而非应用可能请求的所有功能。这也意味着现有 OAuth 客户端的行为默认保持不变：如果客户端未选择启用可选权限范围，授权流程将维持原状。

配置 OAuth 客户端以使用可选权限范围

开发人员可以在配置 OAuth 客户端时选择启用权限范围自定义功能。权限范围的配置方式与现在相同，客户端现在还可以额外指定哪些权限范围为可选：

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "client_name": "ACME Corp",
    "redirect_uris": [
      "https://acme.org/oauth/callback"
    ],
    "grant_types": [
      "authorization_code"
    ],
    "response_types": [
      "code"
    ],
    "token_endpoint_auth_method": "client_secret_basic",
    "scopes": [
      "user-details.read",
      "workers-scripts.write",
      "workers-kv-storage.write",
      "zone.read"
    ],
    "optional_scopes": [
      "workers-kv-storage.write",
      "zone.read"
    ]
  }'

在上述示例中，客户端可以请求全部四个权限范围，但用户在授权同意时只能取消 workers-kv-storage.write 和 zone.read 这两个权限范围。user-details.read 和 workers-scripts.write 一旦包含在授权请求中，将保持为必选。

如果该客户端后续仅请求 workers-scripts.write 和 zone.read 权限，则该授权流程仅考虑这两个权限范围。user-details.read 和 workers-kv-storage.write 将不会显示，也不会强制执行，因为它们不在请求范围之列。

BLOG-3481 5.gif

在开发时考虑部分授权的情况

当用户取消勾选任何可选权限范围并完成授权流程后，生成的访问令牌将只包含其同意授予的权限范围。对开发人员而言，这意味着在交换授权码之后，需要检查实际授予的权限范围集合，而不能假定所有被请求的权限范围均已获批。

一个能够优雅处理较窄授权的应用——例如，一个在其获得的任意权限范围子集内正常运作的 AI 代理——会让用户更放心地授权。仅请求必要的权限并将其余权限标记为可选，这是向用户表明应用尊重其访问决策的良好信号。

覆盖每款产品的权限范围

未来几周内，我们将扩展账户和区域级别的角色体系，覆盖几乎所有 Cloudflare 产品。这意味着将有更多 API 令牌角色、账户成员选项以及 OAuth 权限范围，让客户能够以恰当的访问级别保护其工作负载。

立即使用可选权限范围构建

通过可选 OAuth 权限范围，让开发人员和用户能够更精细地限制访问权限，是朝着在 Cloudflare 上实现更灵活、更可信的授权同意体验迈出的重要一步。借助可选权限范围，开发人员可以构建更细粒度的授权流程，用户也能对其批准的内容拥有更多掌控权。

如需开始使用第三方 OAuth，请参阅我们的文档，或直接前往仪表板中的 OAuth 应用页面，创建您的第一个 OAuth 应用。

感谢我们出色的实习生

此功能是我们在 1111 名实习生的协助下构建的众多功能之一。祝贺 Miller Vargas 和 José Enrique Rodriguez 在此项目中做出的卓越贡献。Miller 是德克萨斯大学奥斯汀分校计算机科学与数学专业的大四学生；José 是墨西哥泛美大学工程学、数据智能与网络安全专业的大四学生。