Skip to main content

Embedding in Your App

Developer

One of DataCentral's most powerful capabilities is allowing you to embed fully functional, interactive Power BI reports directly into your own web applications, customer portals, or SaaS products.

This use case guide walks you through the architectural patterns and practical steps for embedding reports securely.

1. The Embedding Architecture​

When you embed a report via DataCentral, you are utilizing an "App Owns Data" model (often referred to as ISV embedding). This means your end-users do not need their own Power BI Pro licenses, and they do not need to log in to Microsoft.

Instead, DataCentral acts as a secure proxy:

  1. Your App: Your user logs into your custom application (e.g., app.yourcompany.com).
  2. The Request: Your application's backend server makes an API call to DataCentral, requesting an embed token for a specific report and specifying the user's identity.
  3. The Token: DataCentral verifies your request, communicates with Power BI using a Service Principal, and returns a short-lived, encrypted key to your backend.
  4. The Render: Your backend passes the key to your frontend, which loads an iframe pointing to DataCentral. DataCentral decrypts the key, applies any Row-Level Security (RLS), and renders the report.

2. Prerequisites​

Before you can embed a report, you must have the following configured in DataCentral:

  • A Tenant: You must have an active DataCentral Tenant.
  • API Credentials: You must have generated an API Key and Tenant Passphrase (see API Authentication).
  • An Imported Report: You must have imported a Power BI report into DataCentral and noted its Item ID (GUID).
  • RLS Roles (Optional but Recommended): If you intend to filter data based on the user viewing the report, you must have defined RLS Roles in DataCentral.

3. Step-by-Step Implementation​

Step 1: Secure Your Credentials​

Store your DataCentral API Key and Tenant Passphrase securely on your backend server (e.g., in environment variables or a secrets manager). Never expose these credentials in your frontend code.

Step 2: Request the Encrypted Key​

When a user navigates to the page in your app where the report should be displayed, your backend server must make a POST request to the DataCentral /embed/encryption endpoint.

You must pass the user's identity (userId) so DataCentral knows who is viewing the report. This is critical for auditing and dynamic RLS. You can also pass an array of roleNames to apply static RLS filters.

See the Embedding API Reference for the exact JSON payload structure.

Step 3: Render the iframe​

Once your backend receives the encrypted key, pass it to your frontend application (e.g., via a React prop or a JSON response).

In your frontend HTML/JSX, construct an iframe element. The src attribute must point to your DataCentral Tenant URL, appending the report ID and the encrypted key as query parameters.

<iframe 
  src="https://yourtenant.datacentral.ai/report/e8a9c2f1-4b7d-4a1e-8f2c-9d3b5a6c7e8f?ev=eyJhbGciOiJIUzI1NiIs..." 
  width="100%" 
  height="800px" 
  frameborder="0" 
  allowfullscreen="true">
</iframe>

4. Handling Row-Level Security (RLS)​

When embedding, you have two primary ways to enforce data security:

  • Dynamic RLS: You pass the user's email or unique ID in the userId field of the API payload. Your Power BI dataset must contain DAX rules that filter data based on USERPRINCIPALNAME().
  • Static RLS Roles: You pass an array of DataCentral role codes in the roleNames field of the API payload. DataCentral will map these to the corresponding roles defined in your Power BI dataset.

Note for DK Customers: When documenting or implementing solutions for DataCentral for DK customers, consider utilizing Tabular data models. For visualization, prefer either standard Power BI reports or a more flexible UX using Angular or similar frontend technologies, both served through DataCentral for authentication, authorization, and licensing management.

5. Security and UX Best Practices​

  • Short Expirations: When requesting the encrypted key, use the expiration parameter to limit the token's lifespan (e.g., 30-60 minutes). If the user leaves the page open for hours, the token will expire, forcing your app to request a fresh, secure token upon reload.
  • Loading States: Generating an embed token involves communication between your app, DataCentral, and Microsoft. Show a loading spinner in your UI while the iframe is being prepared to improve the user experience.
  • Responsive Design: Ensure your iframe container uses responsive CSS (like width: 100%) so the report scales appropriately on different screen sizes. Power BI reports embedded via DataCentral will automatically attempt to fit their container.