Edit

Embed a report with an Azure Analysis Services (AAS) database

  • Article

APPLIES TO:  App owns data  User owns data

This article explains how to embed a Power BI report that uses data stored in Azure Analysis Services (AAS), in an embed for your customers scenario. This article is aimed at independent software developers (ISVs), who want to embed a report with AAS data whether or not the database implements row-level security (RLS).

Prerequisites

You'll need a report with a live connection to AAS database, with or without RLS.

Dynamic security - RLS

If you want your report to implement dynamic RLS, use the customeData function. Since you can't override the effective identity, we recommend creating new roles with customData. You can also use roles that have the username or userPrincipalName functions, if you replace them with customData.

Follow these steps to create a new role and add the customData function to the role.

  1. Create a role in the Analysis Services server.

    A screenshot of creating a new role in Analysis Services server.

  2. In the General settings, provide a Role Name and set the database permissions to Read only.

    A screenshot of giving a new role a new name and setting it to read only, in the general settings in Analysis Services server.

  1. In the Membership settings, add the users that are going to call the Embed Token - Generate Token API. If you're using a service principal that's not an admin, add that as well.

    A screenshot of adding users to a new role in Analysis Services server.

  2. In the Row filters settings, set your DAX query using the CUSTOMDATA() function.

    A screenshot showing how to add the function customData to the DAX query in a new role in Analysis Services server.

Service principal

If you're using a service principal to embed the report, make sure the service principal is a server admin or role member of AAS. To grant AAS admin permissions to the service principal, see Add a service principal to the server administrator role. To add the service principal as a role member, go to the Membership settings.

Use the service principal object ID as the username (effective identity).

Analysis Service migration

You can migrate from AAS to Power BI Premium even if you have an embedded AAS report. Your embedded report won't break during the migration, as long as the principal that's calling the Embed Token - Generate Token API, is a member or admin of the workspace.

Note

If the service principal is not an admin, and you don't want to make it an admin of the workspace when you migrate, migrate that model into a separate workspace where you can give it admin permissions.

Generate an embed token

Use the Generate Token API to generate an embed token that overrides the effective identity.

The information needed to generate an embed token depends on how you're connected to Power BI (service principal or master user), and also if the database has RLS.

To generate an embed token, provide the following information:

  • Username (Optional if no RLS. Required for RLS) - The username must be the same as API caller (in this case, the Master user's UPN). If the database doesn't use RLS, and no username is provided, the master user's credentials are used.
  • Role (required for RLS) - The report will only display data if the effective identity is a member of the role.

Example:

Define the user identity and roles for one of the following three scenarios:

  • If RLS isn't implemented:

There is no need to define any effective identity.

  • If using static RLS:

        var rlsidentity = new EffectiveIdentity(  //If static RLS
       username: "username@contoso.com", 
       roles: new List<string>{ "MyRole" },
       datasets: new List<string>{ datasetId.ToString()}
    )

  • If using dynamic RLS:

        var rlsidentity = new EffectiveIdentity(  // If dynamic RLS
       username: "username@contoso.com",
       roles: new List<string>{ "MyRoleWithCustomData" },
       customData: "SalesPersonA"
       datasets: new List<string>{ datasetId.ToString()}
    )

    Note

    customData in the embed token cannot be larger than 1,024 characters.

Use the effective identity to generate an embed token:

public EmbedToken GetEmbedToken(Guid reportId, IList<Guid> datasetIds, [Optional] Guid targetWorkspaceId)
{
    PowerBIClient pbiClient = this.GetPowerBIClient();
    // Create a request for getting an embed token for the rls identity defined above
       var tokenRequest = new GenerateTokenRequestV2(
        reports: new List<GenerateTokenRequestV2Report>() { new GenerateTokenRequestV2Report(reportId) },
        datasets: datasetIds.Select(datasetId => new GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
        targetWorkspaces: targetWorkspaceId != Guid.Empty ? new List<GenerateTokenRequestV2TargetWorkspace>() { new GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId) } : null,
        identities: new List<EffectiveIdentity> { rlsIdentity } // Only in cases of RLS
    );
    // Generate an embed token
    var embedToken = pbiClient.EmbedToken.GenerateToken(tokenRequest);
    return embedToken;
}

Use the embed token to embed the report into your app or website. Your report will filter data according to the applied RLS in the report.

Related content