metabase embedding sso implementation

Engineering Community

Skill notes

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: record the step as ❌ blocked, explain exactly what is missing / what failed,

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.

Important performance notes

Maximize parallelism within each step. Use parallel Grep/Glob/Read calls in a single message wherever possible. Do not use sub-agents for project scanning — results need to stay in the main context for cross-referencing in later steps. Do not parse repo branches, commits, PRs, or issues.

Scope

This skill implements JWT SSO authentication for Metabase embedding. It supports all three embedding types that use SSO: Embedding type · Delivery mechanism · Frontend auth config Modular embedding (embed.js) · Web components (<metabase-dashboard>, etc.) · window.metabaseConfig — see fetched docs for available auth fields Modular embedding SDK (@metabase/embedding-sdk-react) · React components (<InteractiveDashboard>, etc.) · defineMetabaseAuthConfig() — see fetched docs for available auth fields

What this skill handles

Creating a JWT signing endpoint that maps the app's authenticated user to Metabase JWT fields (email, first_name, last_name, groups, exp) Configuring the frontend auth layer based on the detected embedding type Adding the METABASE_JWT_SHARED_SECRET environment variable Installing a JWT signing library if one is not already present Producing Metabase admin configuration instructions (JWT settings, group mappings, CORS)

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@metabase · no license declared
Token usage
Heavy
Setup complexity
Manual integration
External API key
Required · Vendor-specific
Operating systems
Docker
Runtime requirements
Node.js · Python · Docker
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
  • Env read
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Output preview metabase-embedding-sso-implementation.preview
# Step 6: Output summary

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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.