This guide shows you how to lock down Metabase so only authorized users can view your data, and how to securely embed dashboards in external apps without exposing your entire instance. You’ll learn to set up user permissions, enable secure embedding, and use signed tokens to control access.
What You’ll Need
- A Metabase instance where you have admin privileges (needed to change settings and manage permissions).
- Access to the Metabase administration panel (usually at
/admin). - For embedding, a web server or application that can generate HMAC-SHA256 signatures (most programming languages support this).
Step-by-Step
Part 1: Restrict Access to Metabase Itself
- Enable user authentication. Go to Admin settings > Authentication. If you haven’t already, set up password login or integrate with SSO (like SAML or LDAP). This ensures only people with accounts can log in.
- Create user groups. In Admin settings > People > Groups, create groups like “Marketing”, “Finance”, or “Viewers”. Assign users to these groups based on their role.
- Set data permissions per group. Go to Admin settings > Permissions. For each database, click the dropdown next to a group and choose:
- Unrestricted – full access to all schemas and tables.
- Granular – choose specific schemas and tables; you can also restrict access to specific columns (via data sandboxing) or rows (via advanced permissions).
- No self-service – the group can only view dashboards and questions that are shared with them, not create new ones.
- Blocked – no access at all.
For most read-only users, choose No self-service and then share specific dashboards with them.
- Restrict collection access. Under Permissions > Collections, set which groups can view or edit dashboards and questions. Keep sensitive collections visible only to specific groups.
- Disable public sharing if not needed. Go to Admin settings > Public sharing. If you don’t want anyone to share dashboards publicly, disable the toggle. If you need it for a few cases, you can revoke public links later.
Part 2: Protect Embedded Dashboards
- Enable embedding. Go to Admin settings > Embedding. Click Enable to turn on embedding for your instance.
- Create an embedding secret key. In the same section, you’ll see a generated Embedding secret key. Copy it and store it securely on your server (never expose it in client-side code). This key is used to sign tokens.
- Enable embedding for a specific dashboard. Open the dashboard you want to embed. Click the Share icon (the arrow) and select Embed. Toggle on Enable embedding.
- Choose embedding parameters. In the embed settings, you can add parameters to filter data (e.g., a user ID or date range). For each parameter, choose whether it’s required, and set a default value.
- Generate a signed URL. Use your backend to create a token with the following payload:
{ "resource": {"dashboard": 123}, "params": {}, "exp": 1700000000 }Sign it with HMAC-SHA256 using your embedding secret key. The token must be base64-encoded and included in the URL as
?token=.... Most languages have libraries for JWT or HMAC; Metabase accepts both raw JWT and custom HMAC tokens. - Set an expiration time. Always include an
expclaim (Unix timestamp) in your token. This prevents someone with a captured URL from using it indefinitely. A common practice is to set it to 1 hour or less. - Use the iframe. The final embed URL looks like:
https://your-metabase.com/embed/dashboard/123#token=YOUR_SIGNED_TOKEN. Put this in an iframe on your site. Metabase will validate the token and display the dashboard only if it’s valid and not expired.
Common Mistakes
- Leaving the embedding secret key in frontend code. Anyone can see it and forge tokens. Always sign tokens server-side.
- Not setting token expiration. Without
exp, a token works forever, which is a major security hole. - Using the same token for all users. If you embed a dashboard with user-specific data, you must generate a unique token per user, with their ID as a parameter. Otherwise, users can see each other’s data.
- Giving too broad database permissions. If you set a group to “Unrestricted” on a database, they can see all tables, even if you only wanted them to see one dashboard. Use “No self-service” and share only specific items.
- Forgetting to disable public sharing. If you leave public sharing on, anyone with the link can view the dashboard without a token.
Tips
- Use separate groups for admins and regular users. Only admins should have “Unrestricted” access. Everyone else should be on a need-to-know basis.
- Rotate your embedding secret key periodically. If you suspect a leak, regenerate the key in Admin settings. This will invalidate all existing tokens.
- Test with a short expiration first. Set
expto 60 seconds during testing to ensure your token generation is correct. - Use parameters to filter data per user. Pass the user’s ID as a parameter and add a filter in the dashboard that uses that parameter. This way, each user only sees their own data.
- Monitor access logs. Metabase logs requests; you can review them to see if any unauthorized attempts are being made.
Troubleshooting
- Dashboard doesn’t load in iframe. Check the browser console for errors. If you see a 401 or 403, your token is invalid or expired. Regenerate it and try again.
- “Invalid token” error. This usually means your secret key doesn’t match the one used to sign. Double-check that you’re using the correct key and that you haven’t regenerated it since.
- Users can see data they shouldn’t. Review the permissions for the group that owns the dashboard. Also, check if you’re passing the correct parameters in the token; if you forget to pass a user ID, the dashboard may show all data.
- Embedded dashboard shows a blank page. Make sure your Metabase instance is accessible from the URL you’re embedding. Also, check that the dashboard ID is correct.
- Token works but dashboard is slow. This is a performance issue, not security. Consider caching the dashboard or optimizing your queries.
Frequently Asked Questions
Can I embed a dashboard without a token?
Yes, if you enable “Public sharing” on the dashboard, you get a public link that doesn’t require a token. However, this is insecure for sensitive data because anyone with the link can view it. Use signed tokens for anything sensitive.
How long should my token be valid?
It depends on your use case. For a typical web app, 1 hour is a good balance. For a dashboard that’s embedded in a long-lived page, you might want 24 hours. Always set an expiration to avoid indefinite access.
Can I restrict which rows a user sees in an embedded dashboard?
Yes. Use parameters in the dashboard and pass the user’s ID or role in the token. Then add a filter to the dashboard’s SQL or GUI query that uses that parameter. This is called row-level security.
Do I need to be an admin to embed dashboards?
You need admin rights to enable embedding globally and to get the secret key. However, any user with edit access to a dashboard can enable embedding for that specific dashboard, as long as embedding is enabled globally.
What happens if I regenerate the embedding secret key?
All existing tokens become invalid immediately. You’ll need to update your backend to use the new key and regenerate tokens for all users. This is a good security practice if you suspect a leak.
Can I embed a question (not a dashboard)?
Yes. The process is the same, but the resource type is question instead of dashboard, and the resource ID is the question’s ID. In the embed URL, use /embed/question/ID.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Samsung Smart Speaker Rollable Display: Facts
- HP 9730e: Wide Prints, Not A3 Scans
- What 8888 Does When You Use It as DNS Server
- Credential Manager: Seamless Sign-In Explained
- API Governance for Public Data: What Growing Portfolios Need
- Enterprise AI Hidden Cost: Data Architecture ROI