metabase-embedding-sso-implementation

Execution contract

Follow the workflow steps in order — do not skip any step. Create the checklist first, then execute each step and explicitly mark it done with evidence. Each step's output feeds into the next, so skipping steps produces incorrect implementations.

If you cannot complete a step due to missing info or tool failure, you must:

1. record the step as ❌ blocked,
2. explain exactly what is missing / what failed,
3. stop (do not proceed to later steps).

Each workflow step must end with Status: ✅ complete or Status: ❌ blocked. Steps are sequential — do not start a step until the previous one is complete. Each step must include evidence (detected code patterns, file paths, diffs applied, pass/fail results).

Architectural conformance

Follow the app's existing architecture, template engine, layout/partial system, code style, and route patterns. Do not switch paradigms (e.g., templates to inline HTML or vice versa). If the app has middleware for shared template variables, prefer that over duplicating across route handlers.

The JWT SSO endpoint must integrate with the app's existing authentication system. The endpoint must only issue Metabase JWTs for users who are already authenticated in the host app. Never create an endpoint that issues tokens without verifying the user's session first.

SSO requests to the Metabase instance must be proxied through the app's backend (FE → BE → Metabase /auth/sso). This keeps the Metabase instance URL and JWT tokens off the client, avoids CORS issues, and ensures auth is always validated server-side. The JWT shared secret must never be exposed to the frontend.