metabase-embedding-sso-implementation

実行契約

ワークフローの手順を順番どおりに実行し、どの手順も省略しないでください。まずチェックリストを作成し、次に各手順を実行して、証拠を添えて完了したことを明示してください。各手順の出力は次の手順に引き継がれるため、省略すると実装が正しく行われません。

情報不足やツールの失敗により手順を完了できない場合は、必ず次のようにしてください。

1. 手順を ❌ blocked と記録する。
2. 何が不足しているのか、何が失敗したのかを正確に説明する。
3. 停止する（後続の手順に進まない）。

各ワークフロー手順の末尾には、Status: ✅ complete または Status: ❌ blocked を記載してください。各手順は順番に進め、前の手順が完了するまでは次の手順を開始しないでください。各手順には証拠（検出したコードパターン、ファイルパス、適用した差分、合否結果）を含めてください。

アーキテクチャへの準拠

アプリの既存のアーキテクチャ、テンプレートエンジン、レイアウト／パーシャルの仕組み、コードスタイル、ルートのパターンに従ってください。方式を変更しないでください（例：テンプレートからインライン HTML に変更するなど）。共有テンプレート変数用のミドルウェアがある場合は、ルートハンドラーで重複して設定するのではなく、そちらを優先してください。

JWT SSO エンドポイントは、アプリの既存の認証システムと連携させる必要があります。このエンドポイントが Metabase JWT を発行するのは、ホストアプリですでに認証されているユーザーに限ってください。ユーザーのセッションを先に検証せずにトークンを発行するエンドポイントは、決して作成しないでください。

Metabase インスタンスへの SSO リクエストはアプリのバックエンド経由でプロキシしてください（FE → BE → Metabase /auth/sso）。これにより、Metabase インスタンスの URL と JWT トークンがクライアントに公開されるのを防ぎ、CORS の問題を回避し、認証を常にサーバー側で検証できます。JWT 共有シークレットをフロントエンドに公開してはいけません。

重要なパフォーマンス上の注意

• 各手順内の並列処理を最大限に活用してください。可能な限り、1 回のメッセージ内で Grep／Glob／Read の呼び出しを並列に行ってください。
• プロジェクトのスキャンにサブエージェントを使わないでください。後続の手順で相互参照できるよう、結果はメインコンテキスト内に保持する必要があります。
• リポジトリのブランチ、コミット、PR、issue を解析しないでください。

対象範囲

このスキルは、Metabase 埋め込み用の JWT SSO 認証を実装します。SSO を使用する次の 3 種類の埋め込みすべてに対応しています。

埋め込みの種類	配信方法	フロントエンドの認証設定
モジュラー埋め込み（embed.js）	Web コンポーネント（<metabase-dashboard> など）	window.metabaseConfig — 利用可能な認証フィールドについては、取得したドキュメントを参照
モジュラー埋め込み SDK（@metabase/embedding-sdk-react）	React コンポーネント（<InteractiveDashboard> など）	defineMetabaseAuthConfig() — 利用可能な認証フィールドについては、取得したドキュメントを参照
フルアプリ埋め込み	Metabase の UI 全体を表示する iframe	iframe の src から SSO エンドポイントを指定

SSO エンドポイントのレスポンス形式（JSON、リダイレクト、Metabase /auth/sso へのプロキシなど）は、埋め込みの種類と Metabase のバージョンによって異なります。取得したドキュメントを参照して、適切な動作を判断してください。

利用者のアプリは、どのバックエンド言語で書かれている場合もあります（Node.js、Python、Ruby、PHP、Java、Go、.NET など）。ステップ 1 で特定の言語が検出されない限り、言語に依存しない手順にしてください。

このスキルで対応する内容

• アプリの認証済みユーザーを Metabase JWT フィールド（email、first_name、last_name、groups、exp）にマッピングする、JWT 署名エンドポイントの作成
• 検出した埋め込みの種類に応じたフロントエンド認証レイヤーの設定
• METABASE_JWT_SHARED_SECRET 環境変数の追加
• JWT 署名ライブラリがまだ導入されていない場合のインストール
• Metabase 管理者向け設定手順（JWT 設定、グループのマッピング、CORS）の作成

このスキルでは対応しない内容

• 埋め込み自体（Web コンポーネント、SDK、iframe）のセットアップ — その場合は移行スキルを使用してください
• 埋め込みバージョンのアップグレード — metabase-modular-embedding-version-upgrade スキルを使用してください
• ゲスト埋め込みの認証（SSO ではなく、{resource, params} ペイロードと METABASE_SECRET_KEY を使用）
• SAML または LDAP 認証 — このスキルの対象は JWT SSO のみです

JWT ペイロードの構造（SSO）

METABASE_JWT_SHARED_SECRET で署名された JWT には、次のフィールドを含める必要があります。

フィールド	型	必須	説明
email	string	はい	ユーザーのメールアドレスです。Metabase はこれを一意の識別子として使用します。初回ログイン時にアカウントが自動作成されます。
first_name	string	はい	ユーザーの名です。ログインのたびに同期されます。
last_name	string	はい	ユーザーの姓です。ログインのたびに同期されます。
groups	string[]	はい	グループ名の配列です。グループ同期が有効な場合、Metabase はログインのたびにグループへの所属を同期します。
exp	number	はい	トークンの有効期限を Unix タイムスタンプで指定します。10 分を推奨します。例：Math.round(Date.now() / 1000) + 600。

追加のユーザー属性は、JWT の追加のキーと値のペアとして含めることができます。Metabase はこれらをユーザー属性として保存し、サンドボックス化やデータ権限に使用します。

許可されるドキュメントソース

次の URL を使用して、バージョン固有の llms-embedding-full.txt を取得します。

https://www.metabase.com/docs/v0.{VERSION}/llms-embedding-full.txt

URL のバージョンには v0.58 の形式を使用します（正規化：先頭の v または 0. を取り除き、パッチ番号を削除します。例：0.58.1 → 58 → URL では v0.58 を使用）。この単一ファイルには、そのバージョンのすべての埋め込みドキュメントが含まれており、LLM が利用しやすいように最適化されています。

その他の制約：

• GitHub の PR／Issue や npm のページは参照しないでください
• 変更履歴のリンクから GitHub に移動したり、URL を推測したりしないでください

AskUserQuestion の使用条件

次の場合は AskUserQuestion を使用し、回答があるまで処理を中断してください。

• プロジェクトで Metabase の埋め込みコードが検出されない（ユーザーが使用予定の埋め込みタイプを質問する）
• プロジェクトコードまたは環境変数から Metabase インスタンスの URL を特定できない
• プロジェクトコードから Metabase インスタンスのバージョンを特定できない
• アプリのユーザー認証方式を特定できない（ユーザーのログイン方法：セッション、Cookie、トークンなど）
• ユーザーモデル／スキーマを特定できない（メールアドレス、名前、グループ／ロールの保存場所）
• ユーザーのグループ／ロールモデルを Metabase のグループに明確に対応付けられない（ロールを Metabase のグループにどう対応付けるかユーザーに質問する）
• バックエンドの言語を特定できない

実装計画のチェックリスト

進捗を追跡するためのチェックリストを作成します。Claude Code では、TaskCreate／TaskUpdate ツールを使用します。

• ステップ 0：埋め込みタイプと Metabase のバージョンを検出する
• ステップ 1：プロジェクトをスキャンし、検出したバージョンのドキュメントを取得する
• ステップ 2：認証アーキテクチャを設計する
• ステップ 3：実装変更を計画する
• ステップ 4：コードを変更する
• ステップ 5：変更を検証する
• ステップ 6：最終的な概要を作成する

ワークフロー

ステップ 0：埋め込みタイプと Metabase のバージョンを検出する

0a：埋め込みタイプを検出する

プロジェクト内を並行して検索し、次のパターンから使用中の埋め込みタイプを特定します。

モジュラー埋め込み（embed.js）：

• HTML／テンプレートファイル内の embed.js または /app/embed.js
• window.metabaseConfig または defineMetabaseConfig
• 例：<metabase-dashboard、<metabase-question、<metabase-browser

モジュラー埋め込み SDK：

• package.json または import 文内の @metabase/embedding-sdk-react
• MetabaseProvider または defineMetabaseAuthConfig
• 例：InteractiveDashboard、InteractiveQuestion、CollectionBrowser など

フルアプリ埋め込み：

• Metabase の URL を含む <iframe（インスタンス URL、または /dashboard/、/question/、/auth/sso を検索）
• /auth/sso へのリダイレクト処理
• return_to パラメーターの構築

埋め込みコードが見つからない場合 → AskUserQuestion を使用し、ユーザーが使用予定の埋め込みタイプを質問します。

複数のタイプが検出された場合、SSO エンドポイントはすべてのタイプに対応する必要があります（ステップ 2 のデュアルモードエンドポイントを参照）。

検出した埋め込みタイプを記録します。これは実装全体を制御します。

0b: Metabase インスタンスのバージョンを検出する

Metabase のインスタンスバージョンによって、利用可能な認証設定フィールド、関数シグネチャ、SSO の動作が決まります。インスタンスバージョンについては、必ず AskUserQuestion を使用してください。Docker タグ、環境変数、package.json にバージョンが記載されている場合でも、ユーザーに確認してください。ドキュメント取得の際は、インスタンスバージョンを正として扱います。

SDK／インスタンスのバージョン不一致チェック：プロジェクトで @metabase/embedding-sdk-react（npm パッケージ）を使用している場合は、SDK パッケージのバージョンとインスタンスバージョンを比較してください。SDK パッケージのバージョンはインスタンスバージョンと一致している必要があります。たとえば、SDK v0.52.x にはインスタンス v0.52.x が必要です。一致しない場合は作業を中止し、SSO に進む前にバージョンを揃えるようユーザーに伝えてください。アップグレードには metabase-modular-embedding-version-upgrade スキルを使用するよう提案してください。

ステップ 1：プロジェクトをスキャンしてドキュメントを取得する

プロジェクトのスキャンとドキュメントの取得は独立しているため、並行して実行してください。依存関係がない場合は、1 つのメッセージ内で並列ツール呼び出しを使用してください。

1a：Metabase インスタンスのバージョンのドキュメントを取得する

ステップ 0b で確認したインスタンスバージョンの llms-embedding-full.txt を取得してください（URL 形式については「許可されているドキュメントソース」を参照）。関連する認証ドキュメントを見つけるため、ファイル内を fetchRequestToken、authProviderUri、jwtProviderUri、defineMetabaseAuthConfig、JWT、SSO で検索してください。

このドキュメントは、検出されたバージョンにおける認証設定オプション、関数シグネチャ、非推奨フィールド、エンドポイントのレスポンス形式に関する信頼できる情報源です。認証アーキテクチャの設計時に、ステップ 2 で使用してください。

以下のプロジェクトスキャン手順と並行して開始してください。

1b：バックエンドの言語とフレームワークを特定する

• 依存関係／ビルドファイル（package.json、requirements.txt、Gemfile、pom.xml、go.mod、composer.json など）を確認します。
• Web フレームワーク（Express、Fastify、Flask、Django、Rails、Spring、Gin、Laravel、ASP.NET など）を特定します。
• 言語、フレームワーク、およびミドルウェアのパターンを記録します。

1c：既存の認証コードを見つける

これは重要です。SSO エンドポイントは、アプリの既存の認証と統合する必要があります。以下を検索してください。

• セッションミドルウェア（express-session、cookie-session、flask-login、devise、Passport、next-auth など）
• 認証ミドルウェアのパターン（req.user、req.session、current_user、@login_required、[Authorize] など）
• ユーザーモデル／スキーマの定義（email、name、first_name、last_name、role、group などのフィールドを確認）
• ログインルート（/login、/auth、/signin、/api/auth など）
• トークン／Cookie ベースの認証（JWT 検証ミドルウェア、Cookie パーサーなど）

該当するファイルは、それぞれ全体を読み込んでください。

1d：既存の Metabase 埋め込みコードを見つける

ステップ 0a で特定したすべてのファイルを読み込んでください。以下を抽出します。

• Metabase インスタンスの URL（環境変数またはハードコードされた値）
• 現在の認証設定（ある場合。SSO の設定が一部すでに実装されている可能性があります）
• embed.js または metabaseConfig が設定されているレイアウト／head ファイル
• Metabase 用の既存 SSO／JWT エンドポイント
• Metabase 関連の環境変数（METABASE_、MB_）

1e：ユーザーモデルとグループ／ロールの構成を見つける

利用可能なフィールドを把握するため、ユーザーモデルを検索してください。

• ユーザーフィールドを含むデータベーススキーマファイル、ORM モデル、型定義
• グループ／ロールの定義（列挙型、データベーステーブル、定数）
• 現在のユーザーがリクエストにどのように紐付けられているか（例：req.user、セッションストア）

出力：構造化されたプロジェクトインベントリ

Backend: {language}, {framework}
Auth system: {mechanism} (e.g., express-session + Passport, next-auth, Django sessions)
User model: {file}:{line} — fields: {email, first_name, last_name, role, ...}
User on request: {how to access} (e.g., req.user, request.user, session[:user])
Groups/roles: {source} — values: {list of group/role names}
Embedding type: {modular | sdk | full-app | multiple}
Metabase URL: {env var or value}
Metabase version: {version}
Existing SSO endpoint: {file}:{line} or "none"
Existing auth config: {description} or "none"

ステップ 2：認証アーキテクチャを設計する（ステップ 1 ✅ の完了後のみ）

プロジェクトインベントリに基づいて、SSO の実装を設計してください。このステップでは設計のみを行い、コードはまだ変更しません。

2a：JWT エンドポイントの設計

SSO エンドポイントのルートを設計します。

• ルート：アプリの既存のパターンに合ったルートを選択します。一般的な選択肢：/sso/metabase、/api/auth/metabase、/auth/metabase-sso。アプリの既存のルート命名規則に従ってください。

• HTTP メソッド：GET（Metabase の SDK/embed.js は JWT プロバイダー URI に GET リクエストを送信します）

• 認証ガード：エンドポイントは、アプリの既存の認証ミドルウェアで保護する必要があります。認証済みのユーザーにのみ Metabase JWT を返します。Step 1c の調査結果に基づき、使用するミドルウェア／デコレーターを指定してください。

• ユーザーマッピング：リクエストからユーザーフィールドを抽出する方法を定義します。

  email       ← {source} (e.g., req.user.email)
  first_name  ← {source} (e.g., req.user.firstName or req.user.name.split(' ')[0])
  last_name   ← {source} (e.g., req.user.lastName or req.user.name.split(' ')[1])
  groups      ← {source} (e.g., [req.user.role] or req.user.groups)
  

• グループマッピング戦略：アプリのロール／グループが目的の Metabase グループと直接一致しない場合は、マッピングを定義します。

  App role "admin"    → Metabase group "Administrators"
  App role "analyst"  → Metabase group "Analysts"
  App role "viewer"   → Metabase group "Viewers"
  

  マッピングが不明な場合 → AskUserQuestion。

• トークンの有効期限：10 分（例：Math.round(Date.now() / 1000) + 600）。ただし、アプリに合わせるべき特定のセッションタイムアウトがある場合は、その値を使用します。

2b：エンドポイントのレスポンス動作

取得したドキュメントを参照し、検出された埋め込みタイプと Metabase のバージョンに応じて、SSO エンドポイントが返すべき内容を確認します。レスポンス形式（署名済み JWT を含む JSON、Metabase の /auth/sso へのリダイレクト、サーバーサイドのプロキシなど）はさまざまです。固定のパターンを前提にしないでください。ドキュメントには、検出されたバージョンで SDK/embed.js/iframe が認証トークンをどのように受け取るかが記載されています。

プロジェクトで複数の埋め込みタイプを使用している場合、エンドポイントは複数のレスポンスモード（クエリパラメーターによる区別など）に対応する必要がある可能性があります。各埋め込みタイプが JWT プロバイダーをどのように呼び出すか、ドキュメントで確認してください。

2c：フロントエンドの認証設定

埋め込みタイプに基づいて、フロントエンドの認証方法を決定します。検出されたバージョンで使用できる認証設定フィールド（フィールド名、シグネチャー、サポートされているオプションはバージョンによって異なります）を、Step 1a で取得したドキュメントを参照して確認してください。具体的なコードパターンは Step 3d で指定します。

2d：JWT ライブラリの選択

プロジェクトに JWT ライブラリがまだない場合は、次のいずれかを使用します。

言語	ライブラリ	インストールコマンド
Node.js	jsonwebtoken	npm install jsonwebtoken
Python	PyJWT	pip install PyJWT
Ruby	jwt	gem install jwt
PHP	firebase/php-jwt	composer require firebase/php-jwt
Java	io.jsonwebtoken:jjwt	Maven/Gradle に追加
Go	github.com/golang-jwt/jwt/v5	go get github.com/golang-jwt/jwt/v5
.NET	System.IdentityModel.Tokens.Jwt	dotnet add package System.IdentityModel.Tokens.Jwt

JWT ライブラリがすでにプロジェクトにある場合は、それを使用します。

Step 3：実装変更を計画する（Step 2 ✅ の完了後のみ）

ファイルごとの変更計画をすべて作成します。各変更について、対象ファイル、変更する場合は変更前のコード、変更後のコードを指定します。

3a：環境変数

• METABASE_JWT_SHARED_SECRET をプロジェクトの環境設定（.env、.env.example、docker-compose.yml、または他の Metabase 環境変数が定義されている場所）に追加します。
• 値：Metabase の管理画面で生成したキーと一致させる必要があることを説明するコメント付きのプレースホルダー文字列

3b：JWT ライブラリのインストール

• JWT ライブラリがない場合：インストールコマンドを指定します。
• すでにある場合：この手順は省略します。

3c: SSO エンドポイントの実装

新しいエンドポイントのコードを具体的に指定します。

• ファイル：ルートを追加する場所（既存のルートファイル、またはアプリで機能ごとにルートを分けている場合は新しいファイル）
• ルートに適用する認証ミドルウェア
• ユーザーフィールドの抽出（ステップ 2a のマッピングに基づく）
• METABASE_JWT_SHARED_SECRET を使用した JWT 署名
• ステップ 2b で取得したドキュメントに基づくレスポンス形式

エンドポイントの要件：

• 環境変数から METABASE_JWT_SHARED_SECRET を読み取る
• リクエストから認証済みユーザーを抽出する（アプリ既存の認証方式を使用）
• email、first_name、last_name、groups、exp を含む JWT ペイロードを作成する
• HS256 アルゴリズム（Metabase のデフォルト）を使用してトークンに署名する
• 埋め込み方式に応じたレスポンスを返す

エンドポイントで禁止すること：

• リクエストボディやクエリパラメーターからユーザー ID を受け取ること（セキュリティ上の脆弱性です。ユーザーが ID を偽装できてしまいます）
• 認証を確認せずにトークンを発行すること
• ユーザー情報をハードコードすること
• Metabase 管理画面で明示的に設定されていない限り、別の署名アルゴリズムを使用すること

3d: フロントエンドの認証設定

対象の Metabase バージョンに対応する認証設定フィールド、関数シグネチャ、非推奨オプションについては、ステップ 1a で取得したドキュメントを正式な情報源として使用してください。設定フィールド、パラメーターのシグネチャ、非推奨オプションはバージョンによって変わります。ドキュメントで確認せずに特定のフィールドが存在すると仮定しないでください。

モジュール型埋め込み（embed.js）：

• 検出されたバージョンで window.metabaseConfig がサポートする認証関連フィールドをドキュメントで確認します（例：jwtProviderUri が使用可能かどうか）。
• ドキュメントにフロントエンドの認証設定フィールドが記載されていない場合は、JWT Identity Provider URI を Metabase 管理画面でのみ設定する必要があります。

モジュール型埋め込み SDK：

• defineMetabaseAuthConfig のオプションと fetchRequestToken 関数のシグネチャをドキュメントで確認します。特に、パラメーターを受け取るかどうかを確認してください。
• ドキュメントに別の指定がない限り、エンドポイント URL は fetchRequestToken の本体にハードコードします。
• 既存コードで使用されている非推奨の認証設定フィールドがあれば削除します（例：authProviderUri は後のバージョンで削除されています）。検出されたバージョンのドキュメントを、有効なフィールドの正確な情報源としてください。

Full App 埋め込み：

• iframe の src を、SSO エンドポイント経由、または return_to パラメーターに URL エンコードされた遷移先パス（例：%2Fdashboard%2F1）を含む Metabase の /auth/sso パス経由に変更します。

3e: 開発専用および非推奨の認証設定を削除する（該当する場合）

検出されたバージョンのドキュメントに記載されていない認証設定フィールドを削除します。よくある例：

• apiKey — API キーはローカル開発専用であり、本番環境の SSO には使用しません
• useExistingUserSession — 管理者のブラウザーセッションを使用するため、本番環境向けではありません
• 既存コードに存在するものの、検出されたバージョンのドキュメントには記載されていないその他のフィールド（非推奨または削除された可能性があります）

3f: Metabase 管理画面の設定に関する注意事項（手動での手順）

以下を計画に記載してください。最終的なまとめに含めます。

1. JWT 認証を有効にする：Admin > Settings > Authentication > JWT > enable
2. JWT 署名キーを設定する：METABASE_JWT_SHARED_SECRET と同じ値を貼り付けます
3. JWT Identity Provider URI を設定する：SSO エンドポイントの完全な URL（例：http://localhost:9090/sso/metabase）。検出されたバージョンでこれが必須か任意か、取得したドキュメントで確認してください（フロントエンド設定が JWT プロバイダーフィールドをサポートするかどうかによって異なります）。
4. グループ同期を設定する：
   • 「Synchronize Group Memberships」を有効にする
   • Metabase に一致するグループを作成するか、グループ名が異なる場合はグループマッピングを設定する
5. CORS を設定する（モジュール型埋め込みのみ）：Admin > Embedding > Modular embedding > ホストアプリのドメインを追加
6. SameSite Cookie を設定する（クロスドメイン環境の場合）：Admin > Embedding > 「None」に設定（HTTPS が必要です）

Step 4: コード変更を適用する（Step 3 ✅ の完了後のみ）

Step 3 のすべての変更を、次の順序で適用します。

1. 環境変数を追加する（Step 3a）
2. 必要に応じて JWT ライブラリをインストールする（Step 3b）
3. SSO エンドポイントを作成する（Step 3c）— これが中心となる変更です
4. フロントエンドの認証を設定する（Step 3d）
5. 開発専用の認証があれば削除する（Step 3e）

制約事項：

• 既存ファイルへの変更には、すべて old_string / new_string を正確に指定して Edit ツールを使用します
• 新しいファイルにのみ Write ツールを使用します
• アプリの既存の認証システムは変更せず、その上に Metabase SSO レイヤーのみを追加します
• プロジェクトにすでに存在する環境変数名は変更しません
• ファイルに複数の編集が必要な場合は、オフセットの問題を避けるため、上から下の順に適用します

Step 5: 変更を検証する（Step 4 ✅ の完了後のみ）

以下のすべての確認を実施します。各確認について、明示的に合格または不合格を判定してください。

5a: SSO エンドポイントの存在と認証保護を確認する

SSO エンドポイントのファイルを読み取ります。以下を確認します。

• ルートが予定されたパスで存在する
• 認証ミドルウェアが適用されている（エンドポイントが保護されている）
• JWT ペイロードに必須フィールド email、first_name、last_name、groups、exp がすべて含まれている
• トークンが環境変数 METABASE_JWT_SHARED_SECRET を使用して署名されている
• レスポンス形式が、取得したドキュメントで指定された埋め込みタイプに合致している

合格条件：エンドポイントが完成しており、認証で保護されていること。

5b: フロントエンド認証の設定を確認する

フロントエンドの認証設定で、検出されたバージョンのドキュメントに記載されたフィールドのみが使われていることを確認します。非推奨または削除済みのフィールドが残っていてはいけません。

• embed.js：window.metabaseConfig の認証フィールドがドキュメントのサポート内容と一致している
• SDK：defineMetabaseAuthConfig のオプションと fetchRequestToken のシグネチャがドキュメントと一致している
• Full App：iframe の src が SSO 経由になっている

合格条件：フロントエンド認証が、埋め込みタイプと検出されたバージョンのドキュメントに合致していること。

5c: 開発専用または非推奨の認証が残っていないことを確認する

Grep を使用して、プロジェクト内のすべてのファイルで useExistingUserSession を検索します（node_modules と .git は除外）。また、metabaseConfig または defineMetabaseAuthConfig の近くにある apiKey も検索します。apiKey だけの検索は広すぎるため、無関係なコードにも一致します。また、非推奨の設定フィールドが残っていないことも確認します（検出されたバージョンのドキュメントと照合してください）。

合格条件：Metabase 固有の開発専用または非推奨の認証方法が残っていないこと。

5d: JWT ライブラリが利用可能であることを確認する

JWT ライブラリがプロジェクトの依存関係に含まれていることを確認します（例：package.json、requirements.txt）。

合格条件：ライブラリが記載されている、またはすでに存在していること。

5e: エンドポイントのコードを抜き取り確認する

エンドポイントが以下に該当しないことを確認します。

• リクエストボディまたはクエリパラメーターからユーザーの識別情報を受け取る
• 認証ミドルウェアなしでトークンを発行する
• ユーザー情報をハードコードする
• METABASE_JWT_SHARED_SECRET 以外の署名キーを使用する

合格条件：すべてのセキュリティ確認に合格していること。

確認に失敗した場合：

• 直ちに問題を修正します
• 該当する確認を再実行します
• 3 回試しても修正できない場合は、Step 5 を ❌ ブロックとし、失敗した確認項目とその理由を報告します

ステップ 6：出力の概要

最終出力を次のセクションに整理します。

1. 適用した変更：変更または作成したファイルをすべて列挙し、それぞれの変更内容を1行で説明します
2. SSO エンドポイント：ルートパス、HTTP メソッド、レスポンスの動作、保護に使用する認証ミドルウェア
3. JWT ペイロードのマッピング：アプリのユーザーフィールドが Metabase の JWT フィールドにどのように対応するかを示す表：

   | Metabase field | Source | Example value |
   |---|---|---|
   | email | req.user.email | "[email protected]" |
   | first_name | req.user.firstName | "Jane" |
   | last_name | req.user.lastName | "Doe" |
   | groups | [req.user.role] | ["Analyst"] |
   | exp | Date.now()/1000 + 600 | 1700000600 |
   

4. グループのマッピング：アプリのロール／グループが Metabase のグループにどのように対応するか
5. 必要な手動作業（ステップ 3f の Metabase 管理者設定）：
   • JWT 認証を有効にし、署名キーを設定する
   • JWT ID プロバイダー URI を設定する
   • グループ同期とマッピングを設定する
   • CORS を設定する（モジュール型埋め込みの場合）
   • SameSite Cookie を設定する（クロスドメインの場合）
6. セキュリティに関する注意事項：
   • エンドポイントは {middleware} によって保護されており、認証済みユーザーのみが Metabase JWT を取得できます
   • METABASE_JWT_SHARED_SECRET は秘密に保ち、Metabase 管理画面の値と一致させる必要があります
   • 各ユーザーには個別の Metabase アカウントが付与されます（初回ログイン時に自動作成）
   • トークンの有効期限は {N} 分に設定されています

再試行ポリシー

ドキュメントの取得：

• llms-embedding-full.txt の取得で 404 が返された場合は、Metabase のバージョン番号を確認して再試行します。それでも失敗する場合は、ステップ 1 を ❌ ブロック済みとしてマークします。

検証：

• AskUserQuestion に回答がない場合は、そのステップでブロック状態を維持し、推測や仮定に基づいて先へ進まないでください。
• ステップ 5 の検証チェックが修正を 3 回試みても失敗する場合は、ステップ 5 を ❌ ブロック済みとしてマークし、失敗したチェックとその理由を報告します。