What you will be able to do
- Choose between basic (Databricks-authenticated) embedding and embedding for external users
- Generate iframe embed code from the Share dialog, including for a single widget
- Describe the service principal, permissions, and token flow behind embedding for external users
1.Two ways to embed, and the admin gate in front of both
Embedding puts a published AI/BI dashboard inside another website or application. Only published dashboards can be embedded. The dashboard's publishing mode still matters after embedding. With shared data permissions, queries run with the publisher's permissions. With individual data permissions, each viewer needs explicit access to the underlying data.
Databricks offers two embedding methods. The main difference is who signs in.
| Embedding method | How users authenticate | How permissions are evaluated | Typical use case | Ask Genie support |
|---|---|---|---|---|
| Databricks-authentication (basic) | Users sign in with Databricks account | Users’ own permissions are checked (and, if dashboard uses shared data permissions, publisher’s permissions are applied) | Users registered to the Databricks account | Supported |
| Embedding for external users | Application authenticates using a service principal and OAuth token | Service principal’s permissions control API access, but shared data permissions (if granted) still determine data access | External users, portals, or broad distribution | Not supported. Use the Genie Conversation API instead. |
Neither method works until a workspace admin allows it. Under Settings → Security → External access → Embed dashboards, the admin picks one of three policies: Allow (any domain), Allow approved domains (only sites on an approved list), or Deny (no embedding). If the admin picks approved domains, they maintain the list with Manage, adding each domain with Add domain.
Checkpoint 1 of 5· Match them up
Match each embedding situation to the method that fits it
Tap a term, then the definition that fits it.
Basic embedding requires a Databricks sign-in and supports Ask Genie. Embedding for external users authenticates the application with a service principal, so viewers do not need accounts, and it does not support Ask Genie.
“Embedding for external users allows you to integrate dashboards into external systems without requiring viewers to have Databricks accounts.”Source: docs.databricks.com
2.Basic embedding: an iframe from the Share dialog
Basic embedding is done entirely in the UI. Open the published dashboard, click Share, then click Embed dashboard in the Sharing dialog. A Copy embed code dialog opens. If an approved-domain list exists, it is shown there. Copy the snippet and paste it into any platform that can render iframe content. If your target domain is not on the list, ask a workspace admin to add it.
<iframe src="https://<databricks-instance-name>/embed/dashboardsv3/<dashboard-and-workspace-ID>" width="100%" height="600" frameborder="0"></iframe>The iframe is just a window onto the dashboard. Everything from the sharing model still applies: viewers must have been granted access. Viewers are asked to sign in to Databricks unless they already have an active session from a recent sign-in to the same workspace.
You can also embed a single widget. Open the published dashboard, open the widget's kebab menu, and choose View fullscreen or Copy link to widget. The URL contains a fullscreenWidget value made of the page name and the widget name, separated by a tilde. Append that parameter to the embed URL.
Checkpoint 2 of 5· Fill the gap
Which search parameter turns this dashboard embed URL into a single-widget embed?
src="https://<databricks-instance-name>/embed/dashboardsv3/<dashboard-and-workspace-ID>& ? =53eadf26~82f66691"The single-widget identifier is passed as fullscreenWidget=<page-name>~<widget-name>. displayName is the page name shown in the UI, not the name key the embed URL uses.
Source: docs.databricks.com3.Embedding for external users: service principal and scoped tokens
Embedding for external users is for viewers outside your organization, such as partners and customers, who you do not want to give Databricks accounts. Your application signs in on their behalf using a service principal. Setting it up takes a few steps, and you need at least CAN MANAGE on a published dashboard. A workspace admin creates the service principal under Settings → Identity and access and checks that the Databricks SQL access and Workspace access checkboxes are selected. The admin then generates an OAuth secret on the service principal's Secrets tab, with a lifetime in days, and copies it immediately because it cannot be viewed again. Next, in the dashboard's Sharing dialog, you add the service principal with CAN RUN. If the dashboard uses individual data permissions, the service principal also needs at least SELECT on the tables and views the dashboard references. It never needs compute permissions, because compute access always uses the publisher's credentials.
At runtime a token exchange takes place. The user signs in to your application, and your server uses the service principal's secret to get a broadly scoped OAuth token. With that token, the server calls /tokeninfo, passing an external_viewer_id and an external_value. The server then generates a tightly scoped, per-user token. The page passes that token to DatabricksDashboard from @databricks/aibi-client. The external_viewer_id is written to audit logs, so it must be unique per user and must not contain personally identifiable information. Dataset queries can filter on the external_value:
SELECT *
FROM sales
WHERE region = __aibi_external_valueCheckpoint 3 of 5· Put it in order
Put the external-embedding token flow in order
- 1.The page instantiates DatabricksDashboard with the user-scoped token
- 2.Your server generates a tightly scoped, user-specific token
- 3.Your server uses the service principal secret to get an OAuth token from Databricks
- 4.Your server calls /tokeninfo, passing external_viewer_id and external_value
- 5.The user signs in to your application, and the frontend asks your server for a dashboard token
The broad service-principal token is only used on the server to mint a narrow per-user token. The browser only ever gets the scoped token.
“Using the token obtained from the service principal, your server generates a new token scoped to the specific user who is accessing the dashboard.”Source: docs.databricks.com
The publishing mode decides whose data access is used. The service principal's data permissions only take effect if the dashboard is not published with shared data permissions. With shared data permissions, the publisher's credentials read the data. For that reason, Databricks recommends publishing externally embedded dashboards with individual data permissions and giving the service principal only the tables it needs. This matters because embedding tokens last one hour, and a token without proper scoping could reach any table added in a later dashboard version during that time. Two more limits: external embedding allows at most 20 dashboard loads starting per second, and Ask Genie is not available. Use the Genie Conversation API instead.
Checkpoint 4 of 5· Check yourself
An externally embedded dashboard is published with shared data permissions. The service principal has SELECT on only one table, but the publisher can read the whole schema. Whose access determines the data viewers see?
With shared data permissions, the publisher's credentials read the data. This is why Databricks recommends individual data permissions together with a narrowly scoped service principal.
“Its permissions apply only if the dashboard is not published with shared data permissions.”Source: docs.databricks.com
Checkpoint 5 of 5· Exam question
A dashboard owner copies a shareable link from the Share dialog and emails it to a recipient who has no workspace access and has never opened this dashboard before. What happens when that recipient clicks the link?
Correct answer: A — The recipient is prompted to authenticate through the identity provider or an email one-time passcode, then sees a dashboard-only, view-focused experience.
- A. Recipients without workspace access still need to authenticate, either through the account's identity provider or a one-time passcode sent by email, before landing in a simplified, dashboard-only view.
- B. Shareable links are not anonymous; a login step through the identity provider or a one-time passcode is required before the recipient can see the dashboard's contents.
- C. Shareable links are specifically designed to extend access to registered account members outside the workspace, so lacking workspace membership does not by itself result in denied access.
- D. Opening a shareable link authenticates the recipient as a registered account member for a view-only copy of the dashboard; it does not create or grant any workspace membership.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.In embedding for external users, the service principal's grants always decide what data viewers see.Why is that wrong?
If the dashboard is published with shared data permissions, the publisher's credentials read the data. The service principal's data permissions only apply with individual data permissions.
Covered in Embedding for external users: service principal and scoped tokens
2.Pasting the iframe embed code into a page grants access to anyone who can open that page.Why is that wrong?
Embedding keeps every existing sharing setting. Viewers must sign in to Databricks and must have been granted access to the dashboard.
3.Ask Genie works in every embedded dashboard.Why is that wrong?
Ask Genie is only available with basic embedding. For external users, integrate the Genie Conversation API instead.
Covered in Embedding for external users: service principal and scoped tokens
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Only published dashboards can be embedded into external applications.”
↩︎ Two ways to embed, and the admin gate in front of both“Users must sign in with their Databricks credentials to view the embedded dashboard.”
↩︎ Two ways to embed, and the admin gate in front of both“Viewers are prompted to sign in to Databricks unless they have an active session from a recent sign-in to the originating workspace.”
↩︎ Basic embedding: an iframe from the Share dialog“Tokens used for embedding for external users are valid for one hour.”
↩︎ Embedding for external users: service principal and scoped tokens“Databricks recommends publishing the embedded dashboard with individual data permissions and assigning required data permissions to the service principal associated with the application.”
↩︎ Exam trap 1“Embedding for external users allows you to integrate dashboards into external systems without requiring viewers to have Databricks accounts.”
↩︎ Checkpoint - 2.https://docs.databricks.com/aws/en/ai-bi/admin/embedOfficial docs
“Embedding a dashboard or Genie Agent requires that the external website be explicitly allowed.”
↩︎ Two ways to embed, and the admin gate in front of both“Allow approved domains: Dashboards and Genie Agents can only be embedded in sites that match the approved list.”
↩︎ Two ways to embed, and the admin gate in front of both - 3.
“Click Embed dashboard in the Sharing dialog.”
↩︎ Basic embedding: an iframe from the Share dialog“The identifier for a single widget is a combination of a page name value and a widget name value, separated by a tilda (~).”
↩︎ Basic embedding: an iframe from the Share dialog“Embedded dashboards offer a secure way for viewers to access dashboard data outside of Databricks. All existing sharing settings apply.”
↩︎ Exam trap 2“they receive an error that says the dashboard is unavailable.”
↩︎ Prediction - 4.
“Set the permission level to CAN RUN.”
↩︎ Embedding for external users: service principal and scoped tokens“the service principal must have at least SELECT privileges on the tables and views referenced in the dashboard.”
↩︎ Embedding for external users: service principal and scoped tokens“external_viewer_id is passed to your dashboard audit logs and must not include personally identifiable information.”
↩︎ Embedding for external users: service principal and scoped tokens“External embedding has a rate limit of 20 dashboard loads per second.”
↩︎ Embedding for external users: service principal and scoped tokens“The Ask Genie button is not supported in embedding for external users.”
↩︎ Exam trap 3“Using the token obtained from the service principal, your server generates a new token scoped to the specific user who is accessing the dashboard.”
↩︎ Checkpoint“Its permissions apply only if the dashboard is not published with shared data permissions.”
↩︎ Checkpoint