vtex-io-auth-and-policies について
VTEX IO アプリ開発者向けのポリシー設計スキルです。外部サービス、保護されたリソース、自アプリのルートに必要な権限を整理し、最小権限の宣言と関連動作を含めたレビューを促します。
主な機能
- 01License Manager、アプリ、アウトバウンドポリシーの識別
- 02保護された統合に必要な権限の宣言
- 03アウトバウンドのホストとパスの限定
- 04アプリのルートに対するサーバー側アクセス制御
- 05ポリシー変更と関連動作の同時レビュー
活用シーン
- 01外部 API 統合のアクセス権限の宣言
- 02保護リソースの権限エラーの調査
- 03既存統合の権限範囲の縮小
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/vtex-io-auth-and-policiesを入力して読み込まれたか確認します。
詳細
認可とポリシーの設計
このスキルを使用する場面
VTEX IO アプリで、外部サービスの呼び出し、VTEX リソースの利用、またはアクセス制御された動作の公開に明示的な権限が必要な場合に、このスキルを使用してください。
- 外部 API との連携を追加する
- 宣言された権限が必要な VTEX リソースを利用する
- ルートやクライアントにポリシーの変更が必要かどうかを確認する
- 既存の連携に対するアプリの権限を厳格化する
次の場合は、このスキルを使用しないでください。
- サービスのランタイム調整
- HTTP ハンドラーの構造
- フロントエンド UI の認可動作
- より広範な信頼境界や機密データのモデリング
AUTH_TOKEN、STORE_TOKEN、ADMIN_TOKENの選択
判断ルール
manifest.jsonのポリシーは、アプリがアクセスを許可されている対象を明示する宣言として扱ってください。- このスキルは、どのランタイムトークンの ID で呼び出すかではなく、アプリに何を実行する権限があるかを判断するために使用してください。
- 実際にアプリが使用する連携やリソースに必要なポリシーのみを追加してください。
- LM リソースキーで保護された VTEX プラットフォームリソースへのアクセスが必要な場合は、License Manager ポリシーを使用してください。
- アプリが別の VTEX IO アプリからロールベースのポリシーを通じて公開されたリソースや操作を利用する場合は、
"vendor.app-name:policy-name"のようなアプリポリシーを使用してください。 - License Manager ポリシーやアプリポリシーの対象外となる外部 HTTP サービスや URL の呼び出しが必要な場合は、
outbound-accessを使用してください。 - ワイルドカードのホストやパスより、対象を限定した
outbound-access宣言を優先してください。 - 独自のルートや操作を公開する場合は、利用側が自身のマニフェストで何かを宣言すると想定するのではなく、リソースベースのポリシー、ルート保護、または認証ディレクティブを通じてサーバー側でアクセスを定義してください。
- VRN（VTEX Resource Name）は、リソースと ID に対して VTEX が使用する内部識別子形式です。ロールベースのポリシーでは
resourcesに VRN を指定し、リソースベースのポリシーではprincipalsに VRN を指定します。 - 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"
]
}
]
}
}
}
これは、appkey ベースの契約を含め、特定の VTEX ID プリンシパルを通じて呼び出し元を識別する連携向けの高度なパターンです。呼び出し元が別の VTEX 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 ポリシーを使用する。
- より限定的な宣言で対応できるのに、ワイルドカードのホストやパスを使用する。
- 実際にはサーバー側のリソースベースのポリシーで適用されるリソースについて、利用側のアプリでもマニフェストポリシーの宣言が必要だと思い込む。
- 権限によって可能になるルートやクライアントの動作をレビューせずに、権限を追加する。
- ポリシーの失敗を、権限の問題ではなくコードのバグとして扱う。
- VRN リソースまたはプリンシパルを示す
403を、認可またはポリシーマッピングの問題ではなく、ハンドラーのバグとして扱う。
レビューチェックリスト
- 保護された統合それぞれに、明示的なポリシーがありますか？
- アクセスパターンに対して、ポリシーの種類は正しいですか？（License Manager、アプリポリシー、または outbound-access）
- outbound-access ルールの範囲は、実際の統合で必要な範囲に十分絞られていますか？
- アプリが保護されたルートまたは操作を公開する場合、サーバー側のアクセス制御も明示的に定義されていますか？
- ポリシーの変更は、それを必要とするルートまたはクライアントと合わせてレビューされていますか？
- 厳密に必要な場合を除き、ワイルドカードの権限は避けていますか？
参考資料
- ポリシー - ポリシーの種類とマニフェストでの宣言
- VTEX IO アプリ内からの外部リソースへのアクセス - アウトバウンドアクセスのポリシーに関するガイダンス
- License Manager のポリシー - License Manager のリソースキーとポリシーの使用方法
- アプリのリソースへのアクセス制御 - 独自のアプリリソースに対するロールベースおよびリソースベースのアクセス制御
- VTEX Resource Name（VRN） - VTEX がポリシー内でリソースとプリンシパルをどのように表現するか
- マニフェスト - アプリの契約と権限の宣言