auth0-v0-integration

Auth0 Vercel ネイティブ連携

ネイティブ連携では、Vercel プロジェクト用に新しい Auth0 テナント環境とアプリケーションをプロビジョニングし、Auth0 の設定を Vercel に事前登録します。既存の Auth0 アカウントには接続しません。既存のテナントを使用する場合は、この連携をインストールするのではなく、標準の Auth0 アプリケーション設定を使用してください。

インストール以外の作業には Auth0 スキル全体を取得してください

Auth0 の設定に関する最適なガイダンスを得るため、Auth0 スキル全体を必ずインストールしてください。このファイルで扱うのは、Vercel Marketplace 連携、つまりプロビジョニング、認証情報の取り扱い、v0 のプレビューに関するトラブルシューティングのみです。Auth0 SDK 自体の連携（Next.js のルート、ミドルウェア、セッション処理）、コールバック URL やログアウト URL 以外のテナント設定、Universal Login のブランディング、その他の Auth0 機能については、スキルをインストールし、ルーターにタスクに必要な内容を読み込ませてください。

npx skills add auth0/agent-skills

問題が起きてから最後の手段として行うのではなく、早い段階で実施してください。以下のテナント設定やブランディングに関するセクションでは、意図的に CLI コマンドを示して先に進みます。完全版スキルの tooling-cli リファレンスには、コマンド一式、フラグのリファレンス、エージェントモードの出力規約が記載されています。

プロビジョニング前に確認する

インストールする前に、実施内容を説明し、確認を得てください。

• 新しい Auth0 アカウント／テナント環境とアプリケーションが作成されます。
• 連携によって、選択した Vercel プロジェクトと環境に接続されます。
• Auth0 の認証情報が Vercel の環境変数に設定されます。値を表示、コミット、またはソース管理にコピーしないでください。
• 連携を削除すると、接続された Auth0 アカウントも削除され、インストールは Vercel の Free プランにダウングレードされます。
• セットアップ時にインストールプランを選択します。有料プランは、連携の Settings ページから Vercel 経由で請求されます。選択したプランと請求への影響を伝えてください。

Vercel のチーム、プロジェクト、環境、アプリケーション名、選択したインストールプラン、任意の環境変数プレフィックスを確認してください。開発者が既存の Auth0 テナントを希望する場合は、このワークフローを中止し、通常のテナント／アプリケーション設定の手順を使用してください。

前提条件

• Vercel アカウントと、アクティブな Vercel プロジェクト。
• 現行の @auth0/nextjs-auth0 SDK を使用する Next.js アプリケーション。
• 対象の Vercel チームに連携をインストールし、接続する Auth0 アカウントを作成する権限。
• インストール後に iframe の埋め込みを有効にし、Vercel が必要とする iframe 内で Universal Login または Classic Login を読み込めるようにすること。これにより Universal Login のデフォルトのフレーム保護が緩和されるため、この連携に限って有効にし、開発者がこのトレードオフを受け入れることを確認してください。

ルーターは SDK の実装に関する Next.js リファレンスも同時に読み込みます。Auth0 のルート、ミドルウェア／プロキシ、セッション処理、環境変数の規約を、マーケットプレイス固有の形式に置き換えないでください。

アプリがレンダリングされても完了ではありません

ログインボタンがレンダリングされても、ログインフローが機能しているとは限りません。URL の登録、iframe の埋め込み、ブランディング（以下の「Deploy and verify」を参照）は、ビルドと同じ作業中に済ませる必要があります。後からユーザーがエラーを報告してから修正するのではありません。「レンダリングされるか」だけを確認してそこで止めるのは、このフローが壊れたままリリースされる最も一般的な原因です。既知の 2 つの失敗を防ぐための情報は、どちらもこのスキルにすでにありますが、そこにたどり着く前に作業を止めてしまいがちです。

タスクを完了する前に

• プレビューのオリジンと localhost の /auth/callback URL がテナントに登録されていることを、auth0 apps show <client-id> で確認します。「CLI コマンドを実行した」だけでは不十分です。
• 同じオリジンのログアウト URL が登録されていることを確認します。Web オリジンが対象に含まれていることも確認します（Auth0 のデフォルトのコールバック URL からの設定、または明示的な --web-origins エントリー）。
• 実際にログインを試し、コールバックの不一致エラーではなく、Universal Login にリダイレクト（302）されることを確認します。
• アプリにカスタムブランディングがある場合は、実際にホストされているログインページを開き（アプリを読み込むだけでなく、ログインリンクに移動し）、アプリと照らし合わせて見た目を確認する必要があります。ページの背景色／プライマリーカラー、アプリ名または見出しの文言、ロゴがすべて一致していることを確認します。「ブランディング API 呼び出しが 200 を返した」ことや「アプリのログインボタンが表示された」ことだけでは不十分です。

デプロイと検証

次の5つを毎回、順番どおりに、一度に行います。

1. 同時に読み込まれた Next.js のリファレンスに従って @auth0/nextjs-auth0 をインストールし、Auth0Client を設定して、プロキシ／ミドルウェアとログイン／ログアウト UI を追加します。

2. APP_BASE_URL を固定します（下記の「生成された設定を安全に使用する」を参照）。公開のたびに変わる、デプロイごとにハッシュ化された URL は使用しないでください。そのうえで、同じ作業中に、今すぐ Auth0 アプリケーションに対応するコールバック URL とログアウト URL を登録します。「コールバック URL とログアウト URL を登録する」を参照してください。最初のログイン試行が失敗するまで待たないでください。インテグレーションは最初に localhost とコールバック URL を設定します。正規ドメインまたはコールバックパスが変わったら、CLI で更新します。

   auth0 apps update <client-id> \
     --callbacks "https://<canonical-domain>/auth/callback" \
     --logout-urls "https://<canonical-domain>"
   

3. アプリが Vercel の埋め込みプレビューで動作する場合は、対象のオリジンで iframe への埋め込みを今すぐ有効にします。テナント設定、オリジンのスコープ設定、ダッシュボードのパス（まだ CLI フラグはありません）については、「Auth0 in the v0 preview」の「ログインページがフレームに表示されない」を参照してください。フレーム内のログインが失敗するまで待たず、手順2のコールバック URL／ログアウト URL とあわせて設定します。

4. アプリにカスタムデザインがある場合は、今すぐ Universal Login のブランディングを適用します。これは任意の仕上げでも、ユーザーからの苦情への対応でもありません。手順1〜3と同じビルド作業の一部です。アプリの一部に見えるべきログインページに、Auth0 のデフォルトのブランディングを残さないでください。最低限、アプリのテーマ／CSS から値を取得し、推測ではなく、プライマリカラー／ページ背景色とボタン／入力欄の角丸をアプリに合わせて設定します。正確な CLI／Management API 呼び出しについては、auth0 スキルのブランディングに関するガイダンスを使用します（auth0 branding ...、または PATCH /api/v2/branding と PUT /api/v2/branding/themes/default）。下記の「チャットのシェルに AUTH0_* を設定する」を参照してください。プロジェクトのリンクが実際に不可能な場合に限り、ダッシュボードを使用します。

   logo_url は、永続的で誰でも取得できる URL を参照する必要があります。Auth0 はサーバー側で取得します。到達できるように見える次の2つのオリジンは、実際には使用できません。

   • v0 プレビューのオリジンにはセッションによる制限があるため、logo_url に指定しても何も起きません。logo_url を設定したリクエスト自体は 200 を返しても、Auth0 は画像を取得できません。
   • デプロイ後であっても、アプリの public/ パスも安全ではありません。v0 プレビューのオリジンは public/ のアセットを配信する代わりにリダイレクト（302）を返すため、そのパスを参照したロゴは読み込まれませんが、Auth0 側のブランディングチェックはすべて成功します。

   代わりに、Vercel Blob（access: 'public' を指定して作成）などの永続的な公開 CDN URL でロゴをホストするか、プレビューではロゴを省略し、公開された本番 URL にデプロイしてから設定します。ロゴが「表示されない」場合は、ヘッドレスのスクリーンショットよりも、実際の DOM の img.src とその URL への curl を信用してください。スクリーンショットでは古い表示やプレースホルダー表示がキャッシュされ、壊れた logo_url が問題なく見えることがあります。テナントを再接続した後は、すべてのブランディングを再確認してください。トラブルシューティングの「インテグレーション再接続後にコールバックが不一致になる／ログインに失敗する」を参照してください。

5. 選択した Vercel Production 環境にデプロイし、ページが表示されることだけでなく、実際にログインを試して検証します。デプロイした URL で、ログイン、コールバック、セッション、保護されたルート、ログアウトを確認します。アプリにカスタムブランディングがある場合は、実際のブラウザーセッションでログインリンクを開き（Playwright MCP ツール、または手動でのクリック操作など）、表示されたホスト型ログインページをアプリと視覚的に比較します。ページ／プライマリカラー、アプリ名または見出しの文言、ロゴを確認してください。Management API の 200 応答や設定ファイルの差分だけでは確認できません。実際に表示されたページだけが確認の根拠になります。（ロゴだけが表示されない場合は、スクリーンショットではなく、実際の img.src に対する curl を優先してください。手順4を参照してください。ヘッドレスのスクリーンショットでは古い表示がキャッシュされ、壊れた logo_url が見えなくなることがあります。）完了とする前に、上記の完了前チェックリストを実施します。

ネイティブ連携をインストールする

Vercel Marketplace

1. Vercel で Integrations → Browse Marketplace を開き、Native Integrations の中から Auth0 を探します。
2. Install を選択し、インストールプランを選んで続行します。
3. Auth0 アプリケーションに名前を付けて作成します。Vercel が専用の Auth0 テナント環境とアプリケーションを作成します。完了するまで待ちます。
4. Connect Project を選択し、Vercel プロジェクトと対象の 環境を選びます。プロジェクトで必要な場合に限り、変数のプレフィックスを入力して接続します。
5. 連携の Getting Started ページを開き、生成されたクイックスタートに従います。

Vercel CLI を使うと、プロジェクトディレクトリから同じプロビジョニングフローを開始できます。 プロビジョニング後に CLI が vercel env pull を自動実行しないよう、--no-env-pull を渡してください。シークレットの取得は別途、意図的に行う手順です。以下の手順は .env.local が無視されることを確認してから実行してください。

vc i auth0 --no-env-pull

vc i auth0 を読み取り専用コマンドとして扱わないでください。 リソースをプロビジョニングするため、対象のチームとプロジェクトについて開発者の確認を得てから実行してください。

Auth0 CLI でテナントを設定する

テナント設定に手を加える前に、次の点を確認してください。 実行中のアプリのログイン時の redirect_uri をデコードし、どのテナント／クライアントを使用しているか確認します → client_id が手元の認証情報と一致することを確認します →（以下の手順で）Management API トークンを発行し、M2M 認証情報が実際に機能することを確認します → その後で初めて変更を加えます。 この確認を省略して誤ったテナントを設定すること、または設定は正しいものの実際には機能しない M2M 認証情報（プレースホルダーの値、誤った環境）を使うことが、ここで最もよくある失敗の原因です。

失敗が直接再現されたのではなく、ユーザーから報告された場合（公開済みアプリでログインが拒否される場合）は、自分のリクエストから redirect_uri をデコードできません。代わりに、テナントのログを取得し （GET /api/v2/logs?q=type:f — type:f はログイン失敗イベントの種別です）、該当する失敗イベントの redirect_uri を確認してください。これにより、変更を加える前に、実際に失敗している環境／テナントも確認できます。

連携を再接続すると、以前のテナント設定は破棄されます。新しいテナントとアプリケーションクライアントがプロビジョニングされるため、再接続は「設定を再開する」のではなく、「テナント設定をやり直す」ものとして扱ってください。

連携が完了すると、M2M グラントを使って、変更のたびに Auth0 ダッシュボードを経由せず、プロビジョニングされたテナントを直接設定できます。テナント設定には CLI を優先してください。コールバック／ログアウト URL、iframe の埋め込み、アプリケーション設定などを CLI で設定し、以下で指定する場合に限りダッシュボードを使用してください。

auth0 login --domain <tenant>.auth0.com --client-id "$AUTH0_MANAGEMENT_API_CLIENT_ID" --client-secret "$AUTH0_MANAGEMENT_API_CLIENT_SECRET"

連携でプロビジョニングされた M2M のクライアント ID／シークレットを使用してください（シークレットを表示したり、ログに記録したりしないでください）。これは、CLI があらゆる非対話型環境で使用するものと同じマシンログインの方法です。すべてのコマンドとフラグについては、auth0 スキルの tooling-cli リファレンスを参照してください。

vercel env pull で AUTH0_* の値が取得されない場合、M2M グラントが利用できないと判断する前に、プロジェクトのリンクを確認してください。詳しくは、以下の「チャットのシェルで AUTH0_* を利用する」を参照してください。グラントがないのではなく、ほとんどの場合、Vercel のプロジェクトが間違っています。M2M グラントがまだ利用できない場合は、次に auth0 login（対話型のデバイスコード認証）を試してください。最後の手段として、M2M、CLI、または正しいプロジェクトのリンクを v0 VM／プレビューで試しても機能しない場合に限り、Auth0 ダッシュボードで手動で登録／設定してください。詳しくは、以下の「コールバック URL とログアウト URL を登録する」を参照してください。

M2M 認証情報の名前は Management API にちなんでいます

このインテグレーションは Management API の M2M クライアントをプロビジョニングし、次の正確な Vercel 環境変数名で公開します。

• AUTH0_MANAGEMENT_API_CLIENT_ID
• AUTH0_MANAGEMENT_API_CLIENT_SECRET

これらをそのまま使用してください。AUTH0_CLIENT_M2M_ID／ AUTH0_CLIENT_M2M_SECRET を作り出したり、存在すると想定したりしないでください。これらの名前はインテグレーションでプロビジョニングされるものには存在しません。推測して設定すると、env pull で値が取得されていないことを確認するために余計なやり取りが発生します。他の作業に進む前に、トークンが実際に発行されることを確認してください。オーディエンスには、テナント独自の Management API を指定する必要があります。

curl -s --request POST \
  --url "https://$AUTH0_DOMAIN/oauth/token" \
  --data grant_type=client_credentials \
  --data "client_id=$AUTH0_MANAGEMENT_API_CLIENT_ID" \
  --data "client_secret=$AUTH0_MANAGEMENT_API_CLIENT_SECRET" \
  --data "audience=https://$AUTH0_DOMAIN/api/v2/"

成功すると、レスポンスに access_token が含まれます。それ以外の場合（access_denied など）は、認証情報、オーディエンス、または認証情報を取得した環境に問題があります。シークレットが間違っていると決めつける前に、次の 2 つのセクションを確認してください。

チャットのシェルで AUTH0_* を使うには、厳しい制限ではなくプロジェクトのリンクを確認します

コールバック／ログアウト URL、ブランディング、テナント／クライアント設定などの管理タスクは、シェルで auth0 CLI を使って実施できますし、そうするべきです。vercel env pull の結果が VERCEL_OIDC_TOKEN だけで AUTH0_* の値が含まれていない場合、シェルが誤った Vercel プロジェクトにリンクされている可能性があります。

正常に動作することを確認済みの手順（Development 環境）：

1. プルする前に、.env.local が Git の追跡対象外として設定され、追跡もされていないことを確認します（そうでなければ処理を中止します。上記の確認を参照してください）。
2. サンドボックスに auth0 CLI がまだない場合はインストールします（デフォルトではインストールされていません）。
3. vercel link でインテグレーションの実際のプロジェクトにリンクします。名前だけでなく、プロジェクト ID（prj_...）で確認してください。よく似た名前のプロジェクトが 2〜3 個ある場合があります。
4. vercel env pull .env.local --environment=development を実行し、値をシェルに読み込みます（source／export）。
5. 必要に応じて、上記のトークン発行用 curl で確認します。
6. auth0 login --domain "$AUTH0_DOMAIN" --client-id "$AUTH0_MANAGEMENT_API_CLIENT_ID" --client-secret "$AUTH0_MANAGEMENT_API_CLIENT_SECRET" を実行します。CLI は独自にクライアント認証情報の交換を行うため、事前に発行したトークンを渡さないでください。auth0 tenants list で確認します。

注意点：

• ログイン時の「Could not store to keyring」／dbus-launch not found 警告は、ヘッドレスサンドボックスでは無害です。トークンはセッション中保持されます。期限が切れたら再ログインしてください。
• .env.local には実際のクライアントシークレットが保存されます。Git の追跡対象外として維持し、シークレットを保存したままにしたくない場合は、管理セッションの終了後に削除してください。
• 新しく追加した環境変数を実行中のアプリの process.env で使うには、開発サーバーの再起動が必要です。また、正しいプロジェクトと正しい環境の両方に存在している必要があります（Production 専用の変数は Development のプレビューでは使えません）。

この CLI を使う方法を基本としてください。vercel link でインテグレーションのプロジェクトにどうしてもアクセスできない場合（「env pull の結果が空に見えた」だけでは不十分です。まずプロジェクト ID を確認してください）の最終手段は、アプリのコードではなくダッシュボードを使うことです。手動での手順は「コールバック URL とログアウト URL の登録」を参照してください。

M2M 認証情報が機能するのは Development 環境のみです

Vercel の各環境（Production／Preview／Development）には、それぞれ独自の Auth0 テナントとアプリケーションのクライアントが割り当てられます。Development にはさらに、Management API 用の実際に認可された M2M クライアントが割り当てられます。Production と Staging に割り当てられるのは、プレースホルダーの AUTH0_MANAGEMENT_API_CLIENT_ID／_SECRET の値だけです。これらはダミー文字列であり、プロビジョニング済みだが未認可のクライアントではありません。どちらの場合も決めつけず、必ず上記のトークン発行用 curl で確認してください。

実行中の v0 プレビューに対して CLI または Management API を使う場合は、Development 環境の値を取得し（vercel env pull .env.local --environment=development）、トークンが発行されることを確認してから、Development が参照するテナント／アプリケーションのクライアントを設定してください。v0 プレビューが実際に接続しているのはそのクライアントです。

Production または Staging の CLI／Management API アクセスが必要な場合

トークンの発行チェックに失敗した場合、修正方法を推測せず、その環境用の実際の M2M クライアントを作成して接続する手順を進めてください。

1. Auth0 ダッシュボードで、Production／Staging テナントに切り替えます（左上のテナント切り替えメニュー）。
2. Applications → Applications → Create Application に移動し、Machine to Machine Applications を選択して、名前を付けます（例：v0-management-prod）。必要なスコープ（最低でも read:clients、update:clients、read:branding、update:branding）を指定して、Auth0 Management API に対する認可を設定します。
3. 新しいアプリケーションの Settings タブを開き、Client ID と Client Secret をコピーします。
4. その2つの値を、Vercel プロジェクトで環境を指定して AUTH0_MANAGEMENT_API_CLIENT_ID と AUTH0_MANAGEMENT_API_CLIENT_SECRET に設定し、プレースホルダーの値を置き換えます。これは Production／Staging の Management API アクセスをエージェントに委ねることになるため、開発者の判断に従ってください。推測で進めず、必ず確認してください。設定方法は次のいずれかです。
   • Vercel プロジェクトの環境変数設定で直接設定する、または
   • 開発者がエージェントへのアクセス許可に同意する場合は、Client ID／Secret を v0 チャットに貼り付けてもらい、エージェント自身のツールを使って、その環境の環境変数として保存します。保存後にエージェントがシークレットを表示、ログ出力、またはエコーしないようにしてください。
5. その環境に対してトークン発行の curl を再実行し、依存する前に確認します。

生成された設定を安全に使用する

この統合では、Vercel プロジェクトに Auth0 の認証情報が事前に読み込まれます。クイックスタートでは AUTH0_CLIENT_ID、AUTH0_CLIENT_SECRET、AUTH0_DOMAIN、AUTH0_SECRET などの値を利用できます。ダッシュボードからシークレットをコピーしたり、.env.local ファイルをコミットしたりせず、Vercel 経由で取得してください。

プロジェクトの接続時に変数のプレフィックスを設定した場合、Vercel は管理対象の値を [prefix]_AUTH0_DOMAIN、[prefix]_AUTH0_CLIENT_ID などの名前にします。しかし、@auth0/nextjs-auth0 SDK が読み取るのは、プレフィックスのないデフォルト名だけです。プレフィックスなしで接続することを推奨します。プレフィックスが必要な場合は、Auth0Client を構築する前に、アプリ内でプレフィックス付きの値を標準名に割り当て直すか、コンストラクターに明示的に渡してください。

まず、.env.local が Git の追跡対象外であり、かつ Git の無視対象になっていることを確認してください。これにより、プル時に実際のクライアントシークレットが追跡対象ファイルに書き込まれるのを防ぎます。いずれかの確認に失敗した場合は、処理を中止してください。その後、チェックアウトをリンクして値をプルします。

# BEFORE pulling any secrets: fail if .env.local is tracked or not ignored.
if git ls-files --error-unmatch -- .env.local >/dev/null 2>&1 \
   || ! git check-ignore --no-index --quiet -- .env.local; then
  echo ".env.local must be untracked and git-ignored before pulling secrets"
  exit 1
fi

# Link the local checkout to the intended Vercel project, then pull local-only values.
vercel link
# For the v0 preview, pull DEVELOPMENT (see "Only the development environment
# has working M2M credentials" above). For a deployed Production app, pull
# --environment=production.
vercel env pull .env.local --environment=development

v0 のプレビューランタイムは、プロジェクトの Vercel 環境変数を自動的に注入しません。開発サーバーが参照するのは .env.local だけです。リクエスト時に process.env.AUTH0_DOMAIN が未定義の場合、SDK はヘッダーベースのドメインリゾルバーにフォールバックし、すべてのルートで DomainResolutionError がスローされます。vercel env ls に変数が表示されても、ランタイムで使えることの証明にはなりません。実際に process.env を読み取るリクエストだけが、その証明になります。

チャットが実際にどの Vercel プロジェクトで動作しているかを確認してください。名前の異なるプロジェクトや、似た名前の兄弟プロジェクトが、「変数は存在するのにアプリから見えない」問題の最も一般的な原因である理由については、下記の「チャットのシェルに AUTH0_* を渡す」を参照してください。

ローカル開発では、現在の Next.js SDK に APP_BASE_URL も必要です。.env.local でローカル URL（例：http://localhost:3000）に設定し、デプロイ環境には正規の本番 URL を設定してください。

v0 のプレビューでは、appBaseUrl を明示的に V0_RUNTIME_URL に設定してください。SDK にリクエストから推測させてはいけません。 プレビューのプロキシの背後では、受信リクエストのホストヘッダーは公開プレビューのオリジンではなく、内部の開発サーバーのホストを示します。そのため、ヘッダーから推測すると、テナントに登録されたものと一致しない redirect_uri が生成されます。これは "redirect_uri is not in the list of allowed callback URLs" の最大の原因です。

const auth0 = new Auth0Client({
  appBaseUrl: process.env.V0_RUNTIME_URL ?? process.env.APP_BASE_URL,
});

V0_RUNTIME_URL は v0 プレビュー内でのみ設定され、本番環境には存在しません。そこでも SDK の推測が安全だと思い込まないでください。実際のデプロイにおける Vercel の推測ホストは、デプロイごとに変わるハッシュ付き URL（例：myapp-qrfarr7z6-team.vercel.app）であり、テナントに登録した状態を維持できません。代わりに、安定した本番エイリアス（VERCEL_PROJECT_PRODUCTION_URL、またはカスタムドメインを設定している場合はそのドメイン）を APP_BASE_URL に明示的に固定してください。安定したエイリアスを確認し → Production 環境の APP_BASE_URL に設定し → 再デプロイし → その安定した URL を登録します（「デプロイと検証」の手順 2 を参照）。これにより、デプロイのたびに変わるのではなく、redirect_uri を公開を通じて一定に保てます。ページがコンパイルされることだけでなく、ログインリダイレクト上の実際の redirect_uri を調べて検証してください。localhost へのフォールバックによる失敗モードで同じ確認を行う方法については、下記の「リダイレクト先が localhost になる」を参照してください。

ネイティブ統合のクイックスタートにある手順では、Production 環境のみが設定されます。Preview と Development も自動的にプロビジョニングされますが、テストの前に Auth0 以外の変数を追加したり、スコープを手動で設定したりする必要がある場合があります。

インテグレーションを管理する

M2M グラントが利用可能になったら、アプリケーションレベルの変更（コールバック URL、ログアウト URL、グラントタイプ、メタデータ）には CLI を使用します。auth0 apps update --help を参照してください。

CLI ではアクセスできない Vercel 側の操作（Vercel が注入する認証情報のローテーション、Vercel が別途管理する localhost／コールバックのパラメーターの編集、許可する環境の設定、インストールプランの変更、インテグレーションの削除）には、Vercel プロジェクトの Integrations タブ → Auth0 → Manage を使用します。Universal Login のカスタマイズなど、CLI でサポートされていない操作には Auth0 Dashboard を使用してください。

シークレットをローテーションしたり、コールバック URL を変更したりする前に、影響を受ける変数を使用しているすべてのデプロイを特定し、再デプロイを計画してください。ローテーション後は、意図した Vercel 環境に新しい変数が存在し、ログインが機能することを確認してから、依存するシステムから古いシークレットを削除してください。

トラブルシューティング

症状	確認事項	解決方法
マーケットプレイスのフローで、想定とは異なるテナントが作成される	ネイティブ統合の動作	想定どおりの動作です。専用の新しい Auth0 テナント環境が作成されます。既存のテナントを使う場合は、標準の Auth0 セットアップを使用してください。
ローカルアプリで Auth0 の変数が不足している、または vercel env pull で VERCEL_OIDC_TOKEN しか取得できない	Vercel プロジェクトのリンクと環境の選択	名前が似た別のプロジェクトやデフォルトの v0 プロジェクトではなく、統合専用のプロジェクトに ID（prj_...）でリンクされていることを確認してください。そのプロジェクトに対して vercel link を実行し、続けて vercel env pull .env.local --environment=development を実行してください。このファイルを Git に含めないでください。「チャットのシェルに AUTH0_* を取り込む」を参照してください。
Production では動作するが、Preview では失敗する	変数のスコープ	Auth0 以外の必須変数を慎重に追加するか、スコープを設定してください。生成されたクイックスタートの手順では Production の設定しか説明されていませんが、Preview と Development の環境もそれぞれ自動的にプロビジョニングされます。
「アプリのレンダリングはゴールではありません」の手順に従ったのに、ログイン／コールバックが失敗する、または画面に表示されない	このワークフローによって防げるはずです。新たなバグではなく、診断上の不足として扱ってください	テナントのログイン失敗ログを取得し（「Auth0 CLI でテナントを設定する」を参照）、実際に拒否された redirect_uri と理由を確認してから、「デプロイと検証」の手順 2～3 に従って修正してください。
統合を削除するとアカウントに予期しない影響がある	削除に関する警告	作業を中断して、削除することを確認してください。統合を削除すると、接続された Auth0 アカウントが削除され、Vercel のインストールがダウングレードされます。
M2M グラントがまだ利用できない	統合のプロビジョニング段階、または誤った Vercel プロジェクトへのリンク	まずプロジェクトのリンクを確認してください。「チャットのシェルに AUTH0_* を取り込む」を参照してください。実際にグラントがない場合は、次に auth0 login（対話形式）を試してください。最後の手段としてのみダッシュボードを手動で編集してください。「コールバック URL とログアウト URL を登録する」を参照してください。
すべてのルートで DomainResolutionError が発生する	リクエスト時に process.env.AUTH0_DOMAIN が存在しない	プレビューのランタイムではプロジェクトの環境変数は自動的に挿入されません。Development 環境の変数を .env.local に取り込み、値が存在することを確認してください。設定がない場合に Auth0 の処理をスキップするよう middleware.ts を強化し、500 エラーではなく機能が制限された状態でサイトが動作するようにしてください。
Management API のトークンリクエストで access_denied が返される（またはトークンを発行できない）	実際のクライアントではない Production／Staging のプレースホルダー M2M 値を使用している	プレビューでの作業には Development 環境の M2M 認証情報を使用するか、その環境用に実際の M2M クライアントを作成し、そのクライアント ID／シークレットを設定してください（「Production または Staging で CLI／Management API を使う必要がある場合」を参照）。シークレットの誤りだと決めつけず、まずトークン発行リクエストで確認してください。
ログイン／サインアップをクリックしても何も起こらず、サーバーログには GET / しか記録されない	認証ボタンが window.open() を使用しており、サンドボックス化された iframe にブロックされている	base-ui の render プロパティを使って、実際の <a target="_blank"> アンカーを使用してください（asChild は使用しないでください）。
統合の再接続後にコールバックの不一致／ログイン失敗が発生する	再接続によって新しいテナントとアプリケーションのクライアントがプロビジョニングされた	現在のクライアントにコールバック URL、ログアウト URL、Web オリジン URL を再登録し、ブランディングを再適用してください。実際に使用されているクライアントを確認するため、実際のログインの redirect_uri と client_id をデコードしてください。
Auth0 とは無関係に、すべてのルートがコンソール出力なしで空の 200 レスポンスを返す	急速なファイル書き込みが続き、開発サーバーが停止した	これ以上デバッグする前に開発サーバーを再起動してください。これはコードのバグではなくプロセスの停止であり、セットアップ中に急速な編集を続けた直後によく発生します。

v0 プレビューでの Auth0

v0 のプレビューでは、localhost でも VERCEL_URL でもない HTTPS オリジン上の クロスサイト iframe 内でアプリが実行されます。よくある 3 つの認証エラーはすべて、 この点が原因です。これを念頭に置けば、フローは最初から正しく動作します。

1. リダイレクト先が localhost になる（「localhost refused to connect」）

SDK は、デフォルトで localhost に設定されているベース URL の設定から、ログイン／コールバックのリダイレクト先を組み立てます。プレビューでは VERCEL_URL と VERCEL_PROJECT_PRODUCTION_URL が設定されていないため、これらに依存する処理はすべて localhost にフォールバックします。appBaseUrl を明示的に V0_RUNTIME_URL に設定してください。推論に頼るのがここでは危険な理由と正確なスニペットについては、上記の「生成された設定を安全に使用する」を参照してください。ページがコンパイルできることだけでなく、ログインリダイレクトの実際の redirect_uri を確認してください。

2. State Cookie が破棄される（「The state parameter is invalid」）

SDK はリダイレクト時に有効期間の短いトランザクション／state Cookie を保存し、コールバック時に読み取ります。デフォルトの SameSite=Lax Cookie は、iframe 内でのクロスサイトコールバックでは送信されないため、検証に失敗します。フレーム内のプレビューで認証状態を維持する必要がある場合は、セッション Cookie を SameSite=None; Secure に設定してください。トップレベルのコールバックでは、トランザクション Cookie を SameSite=Lax のままにしてください。トランザクション Cookie に SameSite=None; Secure を使用するのは、コールバックが iframe または form_post を使用する場合に限ります。クロスサイトセッション Cookie に対する独立した CSRF 保護についても記載してください。Secure Cookie は HTTP 経由では設定できないため、通常の localhost HTTP では安全なデフォルト設定のままにしてください。

3. ログインページがフレーム内に表示されない（「This content is blocked」）

ホストされたログインページでは、iframe への埋め込みが有効になっていない場合、フレームを無効化するヘッダーが送信されることがあります。まず許可する iframe のオリジンを意図した Vercel URL に限定し、その後設定を有効にしてください。この設定はテナントフラグであり、CLI フラグとしてはまだ公開されていません：Auth0 Dashboard → Settings → Advanced → Allow Cross-Origin Authentication。これを有効にするとクリックジャッキング保護が緩和されるため、先にオリジンを限定してください。埋め込みが適切でない場合は、トップレベルコンテキストで認証を開いてください。

実際のアンカーを使用してログイン（およびログアウト）のナビゲーションを iframe の外に移動し、プログラムによる window.open(...) は使用しないでください。v0 のプレビュー iframe はサンドボックス化されているため、スクリプトから呼び出した window.open はポップアップブロッカーによって黙って破棄されます。クリックしても何も起きず、サーバーログには GET / だけが表示され、/auth/* リクエストは一切届きません。実際の <a target="_blank"> のクリックはユーザーが開始したナビゲーションなので、サンドボックスとポップアップブロッカーを通過できます：

<a href="/auth/login" target="_blank" rel="noopener noreferrer">Log in</a>
<a href="/auth/logout" target="_blank" rel="noopener noreferrer">Log out</a>

v0 のデフォルトの Button は base-ui であり、Radix の asChild ではなく render prop を使って構成します。asChild を渡すと "React does not recognize the asChild prop" がスローされます：

<Button render={<a href="/auth/login" target="_blank" rel="noopener noreferrer" />}>Log in</Button>

トップレベルコンテキストでログインが完了した後、新しいセッション Cookie を反映するには、フレーム内のプレビューを更新する必要があります。

コールバック URL とログアウト URL を登録する

コールバック URL とログアウト URL はテナントで設定する必須のアプリケーション設定であり、 アプリ内で設定するものではありません。適切に設定する必要があります。M2M グラントが利用可能になったら、CLI を使用します。

auth0 apps update <client-id> \
  --callbacks "https://<project>.v0.build/auth/callback,http://localhost:3000/auth/callback" \
  --logout-urls "https://<project>.v0.build" \
  --web-origins "https://<project>.v0.build,http://localhost:3000"

Vercel 以外のオリジンは自動同期されないため、明示的に登録してください。プレビューを動作させるために登録するのは、アプリの安定した v0 プレビュー URL （V0_RUNTIME_URL、例：https://<project>.v0.build）です。再ビルドしても変わらないため、一度登録すればプレビューでログインできるようになります。（デプロイごとに変わる Vercel の URL を手動で登録する必要はありません。）ローカル開発用に localhost も登録してください。

デフォルトでは、Auth0 は登録済みのすべてのコールバック URL を Web オリジンとしても許可するため、--web-origins は --callbacks と重複することがよくあります。ただし、コールバックパスではないオリジンに CORS／クロスオリジン認証のアクセスが必要な場合（または、デフォルトに頼らず明示しておきたい場合）は、--web-origins も指定してください。上記のチェックリストを参照してください。

**まだ M2M グラントを利用できない、またはチャットのシェルで CLI を使用できない場合：**ダッシュボードを操作する前に、上記の「チャットのシェルへの AUTH0_* の設定」を確認してください。多くの場合、グラントの不足ではなく、プロジェクトのリンクが原因です。それを確認して除外できた場合に限り、ダッシュボードで手動編集してください。その場合も、デフォルトの方法ではなく、最後の手段として扱ってください。

1. Auth0 ダッシュボードで、アプリの環境変数が参照するテナントを選択します（左上のテナント切り替えメニューを使用します。Development／Staging／Production でテナントが分かれている場合があります）。
2. Applications → Applications に移動し、アプリのクライアントを開きます（連携ツールでは「Created By Vercel」という名前が付いています。不明な場合は Client ID で照合してください）。
3. Settings タブで、カンマ区切りのリストに追加します（安定した v0 プレビューのオリジンを使用してください）。
   • Allowed Callback URLs：コールバックパス全体。例：https://<project>.v0.build/auth/callback（ローカル開発用に http://localhost:3000/auth/callback も追加してください）。
   • Allowed Logout URLs：ユーザーのリダイレクト先のオリジン。例：https://<project>.v0.build。
   • Allowed Web Origins：通常は不要です。Auth0 はデフォルトですべての登録済みコールバック URL を Web オリジンとして許可します。コールバックパスではないオリジンに CORS／クロスオリジン認証のアクセスが必要な場合に限り、ここにオリジンを明示的に追加してください。
4. ページ下部の Save Changes をクリックします。正確なオリジンを指定してください。Auth0 は URL を完全一致で照合するため、項目が抜けているとコールバックやログアウトが拒否されます。

どの方法で URL を登録した場合も、連携の再接続や再同期の後には必ず再確認してください。Vercel Auth0 連携は、実際の Vercel デプロイドメインを自動同期し、AUTH0_* 環境変数を管理するため、手動またはスクリプトで編集したコールバックリストを警告なしに上書きすることがあります。以前の登録が引き続き有効だと思い込まず、auth0 apps show <client-id> またはダッシュボードで確認してください。