mcpField
A
access-protected-vercel-deployment

access-protected-vercel-deployment

github.com/vercelクラウド・DevOps3182.6k 回インストール2 日前に更新
リポジトリ

access-protected-vercel-deployment について

Deployment Protectionで保護されたVercelデプロイに、呼び出し元の既存認証を使ってアクセスするスキルです。HTTPリクエスト、短期OIDCトークンを使うブラウザー自動化、保護を無効化しないアクセスエラーの診断を扱います。

主な機能

  1. 01vercel curlによるデプロイへのアクセス
  2. 02ブラウザー用OIDCトークンヘッダーの設定
  3. 03認証情報とプロジェクト紐付けの確認
  4. 04Trusted Sourcesエラーの診断
  5. 05トークンとデプロイ設定の保護

活用シーン

  1. 01保護されたデプロイのヘルス確認
  2. 02保護されたデプロイ上のAPI呼び出し
  3. 03プレビュー環境でのブラウザー自動化
  4. 04保護された本番環境へのアクセス調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/vercel/vercel-plugin --skill access-protected-vercel-deployment

インストール後、Claude Code で/access-protected-vercel-deploymentを入力して読み込まれたか確認します。

同梱ファイル.vercel.approvers

詳細

保護された Vercel デプロイメントへのアクセス

呼び出し元がすでに使用している Vercel 認証を利用してください。Deployment Protection を無効にしたり、最初の解決策として有効期間の長いバイパスシークレットを求めたりしないでください。

アクセス方法を選択する

HTTP リクエスト：vercel curl を使用する

レスポンス本文、ヘッダー、ヘルスチェック、API 呼び出しには、生の curl を vercel curl（vc curl）に置き換えてください。ネイティブの curl オプションを受け付け、Vercel 認証を使用して保護されたプレビューおよび本番デプロイメントにアクセスします。

vc curl https://my-app.vercel.app/api/health
vc curl https://app.example.com/api/health
vc curl my-app.vercel.app/api/users -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada"}'
vc curl /api/health

パスのみを指定する形式では、リンクされたプロジェクトの本番デプロイメントが対象になります。特定のデプロイメントを指定する場合は、完全な URL を渡してください。

認証に失敗した場合は、保護設定を変更する前に、ローカルのアカウントとプロジェクトを確認してください。

vc whoami

.vercel/project.json を調べ、リンクされたプロジェクトとチームを確認してください。ディレクトリがリンクされていない場合、または誤ったプロジェクトにリンクされている場合にのみ vc link を実行してください。CLI が認証済みユーザーを利用できないと報告した場合にのみ vc login を実行してください。

ブラウザー自動化：開発用 OIDC トークンをヘッダーとして設定する

ブラウザーのリクエストには、有効期間の短いローカルトークンをリクエストヘッダーとして含める必要があります。

x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>

オリジンごとにリクエストヘッダーを設定できるブラウザーツールを使用してください。agent-browser では、トークンを表示したり永続化したりせずに開発用の環境変数を注入します。

vc env run -- sh -c \
  'test -n "$VERCEL_OIDC_TOKEN" && agent-browser open "$1" --headers "{\"x-vercel-trusted-oidc-idp-token\":\"$VERCEL_OIDC_TOKEN\"}"' \
  sh https://my-app.vercel.app

その後、同じセッションで通常のブラウザーワークフローを続けてください。Playwright または別のブラウザードライバーでは、最初のナビゲーションの前に、ブラウザーコンテキストの追加 HTTP ヘッダーで同じヘッダーを設定してください。

ローカル CLI のバージョンで vc env run を通じてトークンを取得できない場合は、次のコマンドでローカルの開発用認証情報を更新してください。

vc env pull .env.local --yes

プロジェクトで既存の dotenv の仕組みを使ってファイルを読み込んでください。トークンを表示したり、その値をソースコードに貼り付けたり、.env.local をコミットしたりしないでください。

Trusted Sources には x-vercel-trusted-oidc-idp-token を使用してください。x-vercel-oidc-token に置き換えないでください。このヘッダーは OIDC トークンを Vercel Function に渡すもので、目的が異なります。

Trusted Sources のルール

リンクされた Vercel プロジェクトのローカル開発用トークンは、デフォルトで同じプロジェクトのプレビューデプロイメントにアクセスできます。保護された本番デプロイメントには自動的にアクセスできません。保護された本番環境にアクセスするには、プロジェクト独自の Trusted Sources エントリーで development → production を許可する必要があります。

同じプロジェクトの通常のプレビューの場合、Trusted Sources の設定をユーザーに求めないでください。

次の場合は設定が必要です。

  • 対象が保護された本番デプロイメントで、呼び出し元がローカルの開発用トークンを使用している場合。
  • 呼び出し元が別の Vercel プロジェクトまたはチームに属している場合。
  • 対象プロジェクトのセルフアクセスルールがカスタマイズされている場合。
  • レスポンスが TRUSTED_SOURCES_ENVIRONMENT_MISMATCH の場合。

対象プロジェクトで Settings → Deployment Protection → Trusted Sources を開いてください。呼び出し元を追加または編集し、必要な from → to の環境ペアを許可してください。ローカルトークンの環境は development であるため、保護された本番環境へのアクセスには development → production が必要です。

これはアクセス制御の変更として扱ってください。必要な正確なルールを説明し、変更前に許可を得てください。関係のない環境ペアまで許可範囲を広げないでください。

レスポンスを診断する

  • Vercel のログイン、SSO、または Deployment Protection のページが表示される場合、リクエストで受け入れ可能な認証方法が使用されていません。
  • TRUSTED_SOURCES_ENVIRONMENT_MISMATCH は、トークンは有効ですが、呼び出し元の環境から対象環境へのアクセスが許可されていないことを意味します。
  • Vercel の保護を回避した後にアプリケーションが返す 401 または 403 は、アプリケーション独自の認証によるものなので、別途デバッグする必要があります。
  • "target": "production" とマークされたデプロイメントも保護されている場合があります。本番環境が公開されていると決めつけないでください。

避けること

  • 自動化を通すためにデプロイ保護を無効にしないでください。
  • 保護ページが表示された後に、認証なしの curl を繰り返し実行しないでください。
  • vc curl またはオリジン限定の OIDC ヘッダーでリクエストを認証できる場合は、SSO の対話型ブラウザーログインを開始しないでください。
  • VERCEL_OIDC_TOKEN をログ、スクリーンショット、コミット済みファイル、ユーザー向けの出力に露出させないでください。

関連スキル

  • Vercel CLI の一般的な使用方法：⤳ skill: vercel-cli
  • アプリケーションのエンドツーエンド検証：⤳ skill: verification

コメント

Markdown 対応