vtex-io-auth-and-policies

授权与策略设计

适用场景

当 VTEX IO 应用需要明确权限来调用外部服务、使用 VTEX 资源或公开受访问控制的行为时，请使用此技能。

• 添加外部 API 集成
• 使用需要声明权限的 VTEX 资源
• 检查路由或客户端是否需要更改策略
• 收紧现有集成的应用权限

以下情况请勿使用此技能：

• 服务运行时调优
• HTTP 处理程序结构
• 前端 UI 授权行为
• 更广泛的信任边界或敏感数据建模
• 在 AUTH_TOKEN、STORE_TOKEN 和 ADMIN_TOKEN 之间进行选择

决策规则

• 将 manifest.json 中的策略视为应用获准访问内容的明确声明。
• 使用此技能来决定应用获准执行哪些操作，而不是决定应由哪种运行时令牌身份发起调用。
• 仅添加应用实际使用的集成和资源所需的策略。
• 如果应用需要访问受 LM 资源键保护的 VTEX 平台资源，请使用 License Manager 策略。
• 如果应用使用其他 VTEX IO 应用通过基于角色的策略公开的资源或操作，请使用应用策略，例如 "vendor.app-name:policy-name"。
• 如果应用需要调用不受 License Manager 或应用策略涵盖的外部 HTTP 服务或 URL，请使用 outbound-access。
• 与通配主机或路径相比，优先使用范围更窄的 outbound-access 声明。
• 公开自有路由或操作时，应通过基于资源的策略、路由保护或 auth 指令在服务器端定义访问权限，而不要假定调用方会在自己的清单中声明权限。
• VRN（VTEX Resource Name，VTEX 资源名称）是 VTEX 用于资源和身份的内部标识符格式。基于角色的策略使用以 VRN 表示的 resources，基于资源的策略使用以 VRN 表示的 principals。
• 仅在平台要求使用 VRN 的地方使用它，尤其是在 service.json 的基于资源的策略中，或用于解读授权错误时。不要在 manifest.json 中为调用方声明策略生成 VRN。
• 在基于资源的策略中，多个 principals 按备选项进行评估，明确的 deny 规则优先于 allow 规则。
• 公开自有的基于角色的策略时，应保持精简并针对具体操作，避免使用宽泛的兜底权限。
• 添加依赖受保护访问的新客户端、外部集成或服务路由时，请检查其策略要求。
• 保持路由实现与策略声明一致：如果某条路由依赖受保护的集成，请确保权限边界清晰明确。

策略类型一览：

• License Manager 策略：

{
  "policies": [
    { "name": "Sku.aspx" }
  ]
}

• 应用策略：

{
  "policies": [
    { "name": "vtex.messages:graphql-translate-messages" }
  ]
}

• Outbound-access 策略：

{
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "partner.example.com",
        "path": "/api/*"
      }
    }
  ]
}

• 使用应用主体 VRN 的基于资源的路由策略：

{
  "routes": {
    "privateStatus": {
      "path": "/_v/private/status/:code",
      "public": false,
      "policies": [
        {
          "effect": "allow",
          "actions": ["POST"],
          "principals": [
            "vrn:apps:*:my-sponsor-account:*:app/[email protected]"
          ]
        }
      ]
    }
  }
}

此路由允许特定的 IO 应用主体访问。由于其他应用不匹配任何允许规则，因此默认情况下仍被拒绝访问。

• 使用 VTEX ID 主体 VRN 的基于资源的路由策略：

{
  "routes": {
    "status": {
      "path": "/_v/status/:code",
      "public": false,
      "policies": [
        {
          "effect": "allow",
          "actions": ["POST"],
          "principals": [
            "vrn:vtex.vtex-id:-:bibi:-:user/vtexappkey-mcc77-HBXYAE"
          ]
        },
        {
          "effect": "deny",
          "actions": ["POST"],
          "principals": [
            "vrn:vtex.vtex-id:-:bibi:-:user/*@vtex.com"
          ]
        }
      ]
    }
  }
}

这是适用于通过特定 VTEX ID 主体识别调用方的集成的高级模式，包括基于 appkey 的契约。如果调用方是另一个 VTEX IO 应用，IO 到 IO 的访问应优先使用应用 VRN。AUTH_TOKEN、STORE_TOKEN 和 ADMIN_TOKEN 等 VTEX IO 身份验证令牌作用不同：它们用于验证对 VTEX 服务的请求并帮助保留请求方上下文，但不会自动取代基于 VRN 主体的路由级资源策略。

硬性约束

约束：每项受保护的集成都必须有明确的支持策略

如果客户端或路由依赖由 License Manager 策略、基于角色的应用策略或 outbound-access 控制的访问权限，应用就必须在 manifest.json 中明确声明相应权限。由基于资源的策略保护的资源在服务端定义访问权限，消费者应用无需仅为该服务端强制措施额外声明策略。

为什么这很重要

如果缺少所需策略，即使代码正确，平台仍会在运行时阻止访问，导致仅查看处理程序代码很难排查的故障。

检测

如果发现正在使用新的外部主机、VTEX 资源或受保护功能，请停止并确认所需的消费者端策略存在，然后再合并代码。如果应用正在公开受保护的路由或操作，请停止并确认服务端也执行了相应的访问规则。

正确

{
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "partner.example.com",
        "path": "/api/*"
      }
    }
  ]
}

错误

{
  "policies": []
}

约束：出站策略必须遵循最小权限原则

出站访问策略必须针对目标主机和路径尽可能精确地设定范围。

为什么这很重要

宽泛的出站规则会增加风险、加大审查难度，并使集成在超出预期范围时不易察觉。

检测

如果集成实际使用的范围小得多，但你发现了通配符主机或过于宽泛的路径，请停止并缩小声明范围。

正确

{
  "name": "outbound-access",
  "attrs": {
    "host": "partner.example.com",
    "path": "/orders/*"
  }
}

错误

{
  "name": "outbound-access",
  "attrs": {
    "host": "*",
    "path": "/*"
  }
}

约束：必须结合策略所启用的行为一并审查策略变更

添加或扩大策略范围时，必须在同一项变更中审查依赖该策略的路由或集成行为。

为什么这很重要

权限只有结合具体情境才有意义。如果不连同使用该策略的代码一起审查，就更容易忽略权限过度扩张和隐藏的副作用。

检测

如果 PR 修改了 manifest.json 中的权限，却没有展示相关的路由、客户端或集成代码，请停止并要求提供相应的行为代码，然后再批准。

正确

{
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "partner.example.com",
        "path": "/orders/*"
      }
    }
  ]
}

错误

{
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "partner.example.com",
        "path": "/api/*"
      }
    }
  ]
}

仅凭这一更宽泛的策略，无法说明应用为何需要扩大的访问权限。

推荐模式

从客户端或路由的行为入手，确定所需的最小访问权限，并仅在 manifest.json 中声明该权限。如果应用公开受保护的路由或操作，则应在同一项审查中于服务端定义基于资源的访问规则。

示例模式：

{
  "policies": [
    {
      "name": "outbound-access",
      "attrs": {
        "host": "partner.example.com",
        "path": "/orders/*"
      }
    }
  ]
}

每当集成发生变化时都要审查权限，而不只是等到运行时出现策略错误时才审查。

常见故障模式

• 为新的外部集成忘记声明 outbound-access 策略。
• 实际需求是 License Manager 资源密钥或其他 VTEX IO 应用公开的应用策略，却误用了 outbound-access 策略。
• 本可使用范围更窄的声明，却使用了通配符主机或路径。
• 误以为消费者应用必须为实际由服务端基于资源的策略强制执行的资源声明 manifest 策略。
• 添加权限时未审查其所启用的路由或客户端行为。
• 将策略故障当作代码错误，而不是权限错误。
• 将错误信息中指出 VRN 资源或主体的 403 当作处理程序错误，而不是授权或策略映射问题。

审查清单

• 每项受保护的集成是否都有明确的策略？
• 策略类型是否与访问模式相符：License Manager、应用策略还是 outbound-access？
• outbound-access 规则对于实际集成范围而言是否足够精确？
• 如果应用公开受保护的路由或操作，是否也明确设置了服务端访问控制？
• 策略变更是否与所需的路由或客户端一并审查？
• 是否避免使用通配符权限，除非确有必要？

参考

• Policies - 策略类型和 manifest 声明
• Accessing external resources within a VTEX IO app - 出站访问策略指南
• Policies from License Manager - License Manager 资源键和策略用法
• Controlling access to app resources - 控制对自有应用资源的基于角色和基于资源的访问
• VTEX Resource Name (VRN) - VTEX 在策略中表示资源和主体的方式
• Manifest - 应用契约和权限声明