vtex-io-auth-tokens-and-context

身份验证令牌与请求上下文

何时适用此技能

当主要决策是选择哪个 VTEX IO 身份来对 VTEX 服务进行后端请求身份验证时，使用此技能。

• 在 ctx.authToken、ctx.storeUserAuthToken 和 ctx.adminUserAuthToken 之间进行选择
• 决定 VTEX 客户端调用应使用 AUTH_TOKEN、STORE_TOKEN 还是 ADMIN_TOKEN
• 检查应遵循当前用户身份的店面和 Admin 集成
• 替换 VTEX IO 应用中硬编码的 appKey 和 appToken

以下情况不要使用此技能：

• 决定哪些策略应写入 manifest.json
• 建模路由级授权或基于资源的策略
• 在 ExternalClient、JanusClient 和其他客户端抽象之间进行选择
• 浏览器端登录或会话 UX 流程
• 验证路由输入或决定哪些数据可以跨越应用边界

决策规则

• 使用此技能来决定哪个身份与 VTEX 端点通信，而不是决定该身份获准执行哪些操作。
• 仅当应用级操作与当前购物者或 Admin 用户无关时，才将 AUTH_TOKEN 与 ctx.authToken 配合使用。
• 当操作来自店面浏览或由购物者触发的流程，且集成应遵循购物者权限时，使用 STORE_TOKEN 与 ctx.storeUserAuthToken。
• 当操作来自 Admin 界面，且集成应遵循已登录 Admin 用户的 License Manager 权限时，使用 ADMIN_TOKEN 与 ctx.adminUserAuthToken。
• 尽可能优先使用用户令牌。官方指南建议避免使用应用令牌进行身份验证；如果店面或 Admin 用户令牌能够更准确地代表请求者，就应使用这些令牌。
• 如果对应的用户令牌不存在，仅当操作确实属于应用级，且不依赖当前购物者或 Admin 身份时，才回退到 AUTH_TOKEN。
• 使用接受 authMethod 的 VTEX IO 客户端时，如果默认应用身份不适用于该请求，请明确传入令牌选项。
• 封装自定义 VTEX 客户端时，应在客户端边界从 IOContext 传递匹配的身份验证令牌，而不是在处理程序中硬编码凭据。
• 令牌选择应与用户旅程保持一致：店面流程不应悄然升级为应用级权限，Admin 流程也不应绕过当前 Admin 角色上下文。
• ADMIN_TOKEN 与 ctx.adminUserAuthToken 必须仅限服务端使用，绝不能暴露给浏览器客户端或代理给它们。
• 将令牌选择和策略设计视为不同的问题：此技能决定由哪个身份发起调用，而身份验证与策略决定该身份获准执行哪些操作。
• 除非正常 VTEX IO 身份验证令牌模型之外存在有文档记录的例外，否则不要在 VTEX IO 应用中使用 appKey 和 appToken。
• 绝不要记录原始令牌，也不要在响应中返回令牌。令牌是请求机密，下游调用方应只接收业务数据。

令牌选择一览：

令牌	上下文字段	适用场景	应避免的场景
AUTH_TOKEN	ctx.authToken	应用级任务、服务间工作，或与当前用户无关的操作	购物者或 Admin 用户已在驱动该操作
STORE_TOKEN	ctx.storeUserAuthToken	店面及购物者触发的操作	后端任务或仅限 Admin 的操作
ADMIN_TOKEN	ctx.adminUserAuthToken	必须遵循当前用户 LM 角色的 Admin 请求	店面流程或后台应用任务

硬性限制

约束：由用户发起的请求必须优先使用用户令牌，而不是应用令牌

如果请求由当前的购物者或 Admin 用户发起，VTEX 集成必须使用对应的用户令牌，而不是默认使用应用令牌。

为何重要

在用户发起的操作中使用应用令牌，会不必要地扩大权限，并使请求脱离应当用于控制访问的真实用户上下文。

检测

如果代码运行在店面或 Admin 请求路径中，却仍使用 ctx.authToken 或隐式使用应用令牌，请停止并确认是否应改用 ctx.storeUserAuthToken 或 ctx.adminUserAuthToken。

正确

export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.storeUserAuthToken,
      },
    })
  }
}

错误

export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}

约束：应用令牌必须仅用于与用户无关的应用级操作

仅当请求确实属于应用级操作，且当前购物者或 Admin 身份不应控制该操作时，才使用 ctx.authToken。

为何重要

应用令牌具有应用清单中声明的权限。将其用于用户触发的操作，可能绕过平台预期的、更受限的购物者或 Admin 权限模型。

检测

如果请求来自 Admin 页面、店面交互或其他面向用户的工作流，请在使用 ctx.authToken 前停止，并确认该操作确实属于应用级操作，而非用户级操作。

正确

export class RatesAndBenefitsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}

错误

export class AdminOrdersClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}

如果客户端用于应遵循已登录用户角色的 Admin 流程，这种做法就是错误的。

约束：VTEX IO 应用在有可用身份验证令牌时不得硬编码 VTEX API 凭据

VTEX IO 应用必须使用来自 IOContext 或 authMethod 的令牌，而不是在源代码或常规运行时配置中嵌入 appKey、appToken 或静态 VTEX 凭据。

为何重要

硬编码的 VTEX 凭据更难轮换、更容易泄露，也绕过了 VTEX IO 客户端已支持的请求上下文模型。

检测

如果在常规 IO 应用集成中看到 X-VTEX-API-AppKey、X-VTEX-API-AppToken、原始 VTEX API 凭据，或用于存放永久 VTEX 凭据的环境变量，请停止并将其替换为正确的身份验证令牌流程，除非有明确记录的例外情况。

正确

await ctx.clients.catalog.getSkuById(id, {
  authMethod: 'ADMIN_TOKEN',
})

错误

await fetch(`https://${ctx.vtex.account}.myvtex.com/api/catalog/pvt/stockkeepingunit/${id}`, {
  headers: {
    'X-VTEX-API-AppKey': process.env.VTEX_APP_KEY!,
    'X-VTEX-API-AppToken': process.env.VTEX_APP_TOKEN!,
  },
})

首选模式

从请求方上下文出发，选择与请求方身份匹配的令牌，并在客户端层内传递令牌。

最简选择指南：

storefront request -> STORE_TOKEN / ctx.storeUserAuthToken
admin request -> ADMIN_TOKEN / ctx.adminUserAuthToken
background app work -> AUTH_TOKEN / ctx.authToken

当客户端支持 authMethod 时，显式传递令牌：

await ctx.clients.orders.listOrders({
  authMethod: 'ADMIN_TOKEN',
})

await ctx.clients.orders.listOrders({
  authMethod: 'STORE_TOKEN',
})

或者在自定义 VTEX 客户端中注入匹配的令牌：

import type { IOContext, InstanceOptions } from '@vtex/api'
import { JanusClient } from '@vtex/api'

export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.adminUserAuthToken,
      },
    })
  }
}

在请求边界附近做出选择，然后让下游处理程序和服务依赖正确配置的客户端，而不是在多个位置随意选择令牌。

常见故障模式

• 将每个 VTEX 请求都默认设置为 ctx.authToken，即使操作是由购物者或 Admin 用户发起的。
• 在 Admin 页面中使用 ctx.authToken，意外绕过当前 Admin 用户的 License Manager 角色上下文。
• 在应受购物者权限限制的店面流程中使用 ctx.authToken。
• 在 IO 应用中硬编码 appKey 和 appToken，而不是使用来自 IOContext 的身份验证令牌。
• 在某个客户端方法中选择了正确的令牌，却忘记在相关调用中始终使用相同的身份。
• 将令牌选择与策略建模混为一谈，把它们当作同一个决策。
• 以明文记录 ctx.authToken、ctx.storeUserAuthToken 或 ctx.adminUserAuthToken，或将原始令牌转发给并不需要它们的下游服务。

审查清单

• 每个 VTEX 集成是否都使用了正确的请求者身份：购物者、Admin 用户或应用？
• 用户实际发起操作时，是否优先使用 ctx.storeUserAuthToken 和 ctx.adminUserAuthToken？
• 是否仅在与当前用户无关的应用级操作中使用 ctx.authToken？
• 常规 IO 应用集成中是否没有硬编码的 VTEX 凭据？
• Token 传递是否集中在客户端层，或通过显式的 authMethod 使用，而不是分散在各个处理程序中？

相关技能

• vtex-io-auth-and-policies - 当主要问题是所选身份应携带哪些权限和策略时使用

参考资料

• 使用身份验证 Token 进行应用身份验证 - AUTH_TOKEN、STORE_TOKEN 和 ADMIN_TOKEN 的官方 Token 模型
• 使用 VTEX IO 客户端 - 补充 Token 选择的客户端使用模式
• 策略 - 应用 Token 权限与清单中声明的策略之间的关系