vtex-io-auth-tokens-and-context

認証トークンとリクエストコンテキスト

このスキルを使用する場面

バックエンドから VTEX サービスにリクエストを送る際、どの VTEX IO ID で認証するかが主な判断事項である場合に、このスキルを使用します。

• ctx.authToken、ctx.storeUserAuthToken、ctx.adminUserAuthToken のいずれを選ぶか
• VTEX クライアントの呼び出しで AUTH_TOKEN、STORE_TOKEN、ADMIN_TOKEN のいずれを使用するか
• 現在のユーザー ID を尊重する必要があるストアフロントおよび Admin のインテグレーションをレビューする場合
• VTEX IO アプリ内のハードコードされた appKey と appToken の使用を置き換える場合

次の用途には、このスキルを使用しないでください。

• manifest.json にどのポリシーを指定するかの判断
• ルートレベルの認可やリソースベースのポリシーの設計
• ExternalClient、JanusClient、その他のクライアント抽象化の選択
• ブラウザー側のログインやセッションの UX フロー
• ルート入力の検証や、アプリの境界を越えて受け渡し可能なデータの判断

判断ルール

• このスキルでは、VTEX エンドポイントへの呼び出しにどの ID を使用するかを判断します。その ID に何が許可されているかは判断しません。
• ctx.authToken と AUTH_TOKEN は、現在の購入者や Admin ユーザーに紐づかないアプリレベルの操作にのみ使用します。
• ストアフロントの閲覧や購入者が開始したフローに起因する操作では、常に ctx.storeUserAuthToken と STORE_TOKEN を使用します。インテグレーションは購入者の権限を尊重する必要があります。
• Admin インターフェースに起因する操作では、常に ctx.adminUserAuthToken と ADMIN_TOKEN を使用します。インテグレーションはログイン中の Admin ユーザーの License Manager 権限を尊重する必要があります。
• ユーザートークンが利用可能な場合は、ユーザートークンを優先します。公式ガイダンスでは、ストアまたは Admin ユーザーのトークンでリクエスト元をより正確に表せる場合、アプリトークン認証を避けるよう推奨されています。
• 対応するユーザートークンがない場合、操作が真にアプリスコープであり、現在の購入者や Admin の ID に依存しないときに限り、AUTH_TOKEN にフォールバックします。
• authMethod を受け取る VTEX IO クライアントを使用する場合、デフォルトのアプリ ID がリクエストに適さないときは、トークンの選択を明示的に渡します。
• カスタム VTEX クライアントをラップする場合、ハンドラーに認証情報をハードコードするのではなく、クライアントの境界で IOContext から対応する認証トークンを渡します。
• トークンの選択はユーザージャーニーに沿ったものにします。ストアフロントのフローでアプリレベルの権限に暗黙に昇格させてはならず、Admin のフローで現在の Admin のロールコンテキストを迂回してはなりません。
• ctx.adminUserAuthToken と ADMIN_TOKEN はサーバー側のみで使用し、ブラウザークライアントに決して公開したり、プロキシしたりしてはなりません。
• トークンの選択とポリシーの設計は別の関心事として扱います。このスキルでは呼び出しを行う ID を決め、auth-and-policies ではその ID に許可されている操作を決めます。
• 通常の VTEX IO 認証トークンモデル以外の、文書化された例外がない限り、VTEX IO アプリ内で appKey と appToken を使用してはなりません。
• 生のトークンをログに記録したり、レスポンスで返したりしてはなりません。トークンはリクエストの機密情報であり、後続の呼び出し元には業務データのみを返します。

トークン選択の概要：

トークン	コンテキストフィールド	使用する場面	使用を避ける場面
AUTH_TOKEN	ctx.authToken	アプリレベルのジョブ、サービス間の処理、または現在のユーザーに紐づかない操作	購入者または Admin ユーザーがすでに操作を開始している場合
STORE_TOKEN	ctx.storeUserAuthToken	ストアフロントおよび購入者が開始する操作	バックエンドジョブまたは Admin 専用の操作
ADMIN_TOKEN	ctx.adminUserAuthToken	現在のユーザーの LM ロールを尊重する必要がある Admin リクエスト	ストアフロントのフローまたはバックグラウンドのアプリタスク

厳守事項

制約：ユーザー起点のリクエストでは、アプリトークンよりユーザートークンを優先する

現在の購入者または管理者ユーザーがリクエストを開始した場合、VTEX インテグレーションでは、デフォルトでアプリトークンを使用するのではなく、対応するユーザートークンを必ず使用してください。

重要な理由

ユーザー起点の処理にアプリトークンを使用すると、権限が不必要に広がり、アクセスを制御するべき実際のユーザーコンテキストからリクエストが切り離されます。

検出方法

コードがストアフロントまたは管理者リクエストの経路で実行されているにもかかわらず、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,
      },
    })
  }
}

制約：アプリトークンは、ユーザーに紐付かないアプリレベルの処理に限って使用する

リクエストが真にアプリスコープであり、現在の購入者や管理者のアイデンティティに処理を委ねるべきでない場合に限り、ctx.authToken を使用してください。

重要な理由

アプリトークンには、アプリのマニフェストで宣言された権限が付与されています。ユーザーが開始した処理にこれを使用すると、プラットフォームが想定する、より限定的な購入者または管理者の権限モデルを迂回するおそれがあります。

検出方法

リクエストが管理者ページ、ストアフロントでの操作、またはその他のユーザー向けワークフローから発生している場合は、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,
      },
    })
  }
}

ログイン中のユーザーのロールを尊重すべき管理者フローでクライアントを使用する場合、これは誤りです。

制約：認証トークンを利用できる場合、VTEX IO アプリで VTEX API 認証情報をハードコードしない

VTEX IO アプリでは、ソースコードまたは通常のランタイム設定に appKey、appToken、静的な VTEX 認証情報を埋め込むのではなく、IOContext または authMethod のトークンを必ず使用してください。

重要な理由

ハードコードされた 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 をデフォルトとして使用する。
• 管理者ページで ctx.authToken を使用し、現在の管理者ユーザーの License Manager ロールコンテキストを誤って迂回する。
• 購入者の権限で制限されるべきストアフロントのフローで ctx.authToken を使用する。
• IOContext の認証トークンを使用せず、IO アプリに appKey と appToken をハードコードする。
• あるクライアントメソッドでは正しいトークンを選んでも、関連する呼び出し全体で同じアイデンティティを一貫して適用し忘れる。
• トークンの選択とポリシーのモデル化を混同し、同じ判断として扱う。
• ctx.authToken、ctx.storeUserAuthToken、または ctx.adminUserAuthToken を平文でログに記録する、あるいは必要のない下流サービスに生のトークンを転送する。

レビューチェックリスト

• 各 VTEX 統合で、適切なリクエスターの識別情報（購入者、Admin ユーザー、またはアプリ）が使用されていますか？
• ユーザーが実際に操作を行う場合、ctx.storeUserAuthToken と ctx.adminUserAuthToken が優先されていますか？
• ctx.authToken は、現在のユーザーに関連付けられていないアプリレベルの操作にのみ使用されていますか？
• 通常の IO アプリ統合に、ハードコードされた VTEX 認証情報が含まれていませんか？
• トークンの引き継ぎは、ハンドラーに散在させるのではなく、クライアント層に集約するか、authMethod を明示的に使用していますか？

関連スキル

• vtex-io-auth-and-policies - 主な判断事項が、選択した識別情報に付与すべき権限とポリシーである場合に使用します

参考資料

• 認証トークンを使用したアプリ認証 - AUTH_TOKEN、STORE_TOKEN、ADMIN_TOKEN に関する公式のトークンモデル
• VTEX IO クライアントの使用 - トークンの選択を補完するクライアントの使用パターン
• ポリシー - アプリトークンの権限と manifest で宣言されたポリシーの関連性