Learn how to migrate from Power BI Embedded to the Power BI service and leverage advances for embedding in apps.

Microsoft recently announced Power BI Premium, a new capacity-based licensing model that increases flexibility for how users access, share and distribute content. The offering also delivers additional scalability and performance to the Power BI service.

With the introduction of Power BI Premium, Power BI Embedded and the Power BI service are converging to advance how Power BI content is embedded in apps. This means you will have one API surface, a consistent set of capabilities and access to the latest Power BI features – such as dashboards, gateways and app workspaces – when embedding your content. Moving forward you’ll be able to start with Power BI Desktop and move to deployment with Power BI Premium, which will be generally available late in the second quarter of 2017.

The current Power BI Embedded service will continue to be available for a limited time following general availability of the converged offering: customers under an Enterprise Agreement will have access to through the expiration of their existing agreements; customers that acquired Power BI Embedded through Direct or CSP channels will enjoy access for one year from General Availability of Power BI Premium. This article will provide some guidance for migrating from the Azure service to the Power BI service and what to expect for changes in your application.

Important:

While the migration will take a dependency on the Power BI service, there is not a dependecy on Power BI for the users of your application when using an embed token. They do not need to sign up for Power BI to view the embedded content in your application.

Prepare for the migration

There are a few things you need to do to prepare for migrating from Power BI Embedded Azure service over to the Power BI service. You will need a tenant available, along with a user that has a Power BI Pro license.

  1. Make sure you have access to an Azure Active Directory (Azure AD) tenant.

    Your organization may already have a tenant available that you are currently using Power BI with. If this is not available, you will need to create a new tenant. You can make use of an existing tenant for your organization. For more information you can see Create an Azure Active Directory tenant or How to get an Azure Active Directory tenant.

  2. Make sure your application "master" account has a Power BI Pro license.

Accounts within Azure AD

The following accounts will need to exist within your tenant.

Note:

These accounts will need to have Power BI Pro licenses in order to use App workspaces and to create content that makes use of Pro features such as the On-Premises Data Gateway.

  1. A tenant admin user.

    It is recommended that this user be a member of all App workspaces created for the purpose of embedding.

  2. Accounts for analysts that will create content.

    These users should be assigned to App workspaces as needed.

  3. An application master user account.

    The applications backend will store the credentials for this account and use it for acquiring an Azure AD token for use with the Power BI APIs. This account will be used to generate the embed token for the application. This account needs to be an admin of the App workspaces created for embedding.

    Note:

    This is just a regular user account in your organziation that will be used for the purposes of embedding.

App registration and permissions

You will need to register an application within Azure AD and grant certain permissions.

Register an application

Note:

You should register the application using the application master account.

You will need to register an application as a native Azure application witn your Azure AD tenant. You can either register your application from the Power BI app registration tool, or directly within the Azure AD portal. For more information, see Register a client app. Make sure that you select Native App for the App type.

Apply permissions to your application

You will need to enable additional permissions to your application in addition to what was provided in app registration page. You can accomplish this through the Azure AD portal, or programmatically.

Note:

It is recommended you perform these steps using the application master account. It should be able to modify the app permissions within the Azure portal without admin rights. It will be the owner of the app.

Using the Azure AD Portal

  1. Browse to the App registrations blade within the Azure portal and select the app that you are using for embedding.

  2. Select Required permissions under API Access.

  3. Select Windows Azure Active Directory and then make sure Access the directory as the signed-in user is selected. Select Save.

  4. Within Required permissions, select Power BI Service (Power BI).

  5. Select all permissions under Delegated Permissions. You will need to select them one by one in order to save the selections. Select Save when done.

  6. Within Required permissions, select Grant Permissions.

    This will give the app permissions on behalf of all users in the tenant/organization. If you don't want this, you will need to sign in internactively with your app ID to Azure AD at least once.

Applying permissions programmatically

  1. You will need to get the existing service principals (users) within your tenant. For information on how to do that, see Get servicePrincipal.

    Note:

    You can call the Get servicePrincipal api without {id} and it will get you all of the service principals within the tenant.

  2. Check for a service principal with you app client id as appId property.

  3. Create a new service plan if missing for your app.

    Post https://graph.microsoft.com/beta/servicePrincipals
    Authorization: Bearer ey..qw
    Content-Type: application/json
    {
    "accountEnabled" : true,
    "appId" : "{App_Client_ID}",
    "displayName" : "{App_DisplayName}"
    }
    
  4. Grant App Permission to PowerBI API

    Post https://graph.microsoft.com/beta/OAuth2PermissionGrants
    Authorization: Bearer ey..qw
    Content-Type: application/json
    { 
    "clientId":"{Service_Plan_ID}",
    "consentType":"AllPrincipals",
    "resourceId":"c78b2585-1df6-41de-95f7-dc5aeb7dc98e",
    "scope":"Dataset.ReadWrite.All Dashboard.Read.All Report.Read.All Group.Read Group.Read.All Content.Create Metadata.View_Any Dataset.Read.All Data.Alter_Any",
    "expiryTime":"2018-03-29T14:35:32.4943409+03:00",
    "startTime":"2017-03-29T14:35:32.4933413+03:00"
    }
    
  5. Grant App Permission to AAD

    Post https://graph.microsoft.com/beta/OAuth2PermissionGrants
    Authorization: Bearer ey..qw
    Content-Type: application/json
    { 
    "clientId":"{Service_Plan_ID}",
    "consentType":"AllPrincipals",
    "resourceId":"61e57743-d5cf-41ba-bd1a-2b381390a3f1",
    "scope":"User.Read Directory.AccessAsUser.All",
    "expiryTime":"2018-03-29T14:35:32.4943409+03:00",
    "startTime":"2017-03-29T14:35:32.4933413+03:00"
    }
    

Create App workspaces (Required)

You can take advantage of App workspaces to provide better isoliation if your application is servicing multiple customers. Dashboards and reports would be isolated between your customers. You could then use a Power BI account per App workspace to further isolate application experiences between your customers.

Important:

You cannot use a personal workspace to take advantage of embedding

You will need a user that has a Pro license in order to create an App workspace within Power BI. The Power BI user that creates the App workspace will be an admin of that workspace by default.

Note:

The application master account needs to be an admin of the workspace.

Create and upload your reports

You can create your reports and datasets using Power BI Desktop and then publish those reports to a Power BI workspace. It is recommended to publish your reports to an App workspace to provide better isolation if your application is servicing multiple customers.

Note:

We will have an import/export tool for you to accomplish this step to assist with moving content from the Power BI Embedded Azure service to the Power BI service. This tool is coming soon.

Rebuild your application

  1. You will need to modify your application to use the Power BI REST APIs and the report location inside powerbi.com.

  2. Rebuild your AuthN/AuthZ authentication using the master account for your application. You can take advantage of using an embed token to allow this user to act on behalf of other users.

    Note:

    More information regarding the embed token will be made available soon.

  3. Embed your reports from powerbi.com into your application.

Map your users to a Power BI user

Within your application, you will map users that you manage within the application to a master Power BI credential for the purposes of your application. The credentials for this Power BI master account will be stored within your application and be used to creating embed tokens.

What to do when you are ready for production

When you are ready to move to production, you will need to do the following.

  1. Purchase a capacity that fits your needs. We will have a calculator to estimate the required capacity size.

  2. Go to the Admin portal, within Power BI, and within Manage capacity section assign the workspace to the purchased capacity. This can be done with an admin account or a user with capacity assignment permissions.

    If you are using an App workspace to store your content, you can edit the App workspace and assign it to a Premium capacity under advanced.

  3. Deploy your updated application to production and begin embedding reports from the Power BI service.

After migration

You should do some cleanup within Azure.

  • Remove all workspaces off of the deployed solution within the Azure service of Power BI Embedded.
  • Delete any Workspace Collections that exist within Azure.

Next steps

Embedding with Power BI
Power BI Premium announcement
JavaScript API Git repo
Power BI C# Git repo
JavaScript embed sample
Power BI Premium whitepaper

More questions? Try asking the Power BI Community