Connect to and manage a Power BI tenant in Azure Purview

Article
11/04/2021
9 minutes to read

This article outlines how to register a Power BI tenant, and how to authenticate and interact with the tenant in Azure Purview. For more information about Azure Purview, read the introductory article.

Supported capabilities

Metadata Extraction	Full Scan	Incremental Scan	Scoped Scan	Classification	Access Policy	Lineage
Yes	Yes	No	No	No	No	Yes

Note

If the Purview instance and the Power BI tenant are in the same Azure tenant, you can only use managed identity (MSI) authentication to set up a scan of a Power BI tenant.

Known limitations

For cross-tenant scenario, no UX experience currently available to register and scan cross Power BI tenant.
By Editing the Power BI cross tenant registered with PowerShell using Purview Studio will tamper the data source registration with inconsistent scan behavior.
Review Power BI Metadata scanning limitations.

Prerequisites

An Azure account with an active subscription. Create an account for free.
An active Purview resource.
You will need to be a Data Source Administrator and Data Reader to register a source and manage it in the Purview Studio. See our Azure Purview Permissions page for details.

Register

This section describes how to register a Power BI tenant in Azure Purview in both same-tenant and cross-tenant scenarios.

Authentication for a same-tenant scenario

For both same-tenant and cross-tenant scenarios, to set up authentication, create a security group and add the Purview-managed identity to it.

In the Azure portal, search for Azure Active Directory.
Create a new security group in your Azure Active Directory, by following Create a basic group and add members using Azure Active Directory.

Tip

You can skip this step if you already have a security group you want to use.
Select Security as the Group Type.
Add your Purview-managed identity to this security group. Select Members, then select + Add members.
Search for your Purview-managed identity and select it.

You should see a success notification showing you that it was added.

Associate the security group with the tenant

Log into the Power BI admin portal.
Select the Tenant settings page.

Important

You need to be a Power BI Admin to see the tenant settings page.
Select Admin API settings > Allow service principals to use read-only Power BI admin APIs (Preview).
Select Specific security groups.
Select Admin API settings > Enhance admin APIs responses with detailed metadata > Enable the toggle to allow Purview Data Map automatically discover the detailed metadata of Power BI datasets as part of its scans.

Important

After you update the Admin API settings on your power bi tenant, wait around 15 minutes before registering a scan and test connection.

Caution

When you allow the security group you created (that has your Purview managed identity as a member) to use read-only Power BI admin APIs, you also allow it to access the metadata (e.g. dashboard and report names, owners, descriptions, etc.) for all of your Power BI artifacts in this tenant. Once the metadata has been pulled into the Azure Purview, Purview's permissions, not Power BI permissions, determine who can see that metadata.

Note

You can remove the security group from your developer settings, but the metadata previously extracted won't be removed from the Purview account. You can delete it separately, if you wish.

Steps to register in the same tenant

Now that you've given the Purview-Managed Identity permissions to connect to the Admin API of your Power BI tenant, you can set up your scan from the Azure Purview Studio.

Select the Data Map on the left navigation.
Then select Register.

Select Power BI as your data source.
Give your Power BI instance a friendly name.

The name must be between 3-63 characters long and must contain only letters, numbers, underscores, and hyphens. Spaces aren't allowed.

By default, the system will find the Power BI tenant that exists in the same Azure subscription.

Note

For Power BI, data source registration and scan is allowed for only one instance.

Steps to register cross-tenant

In a cross-tenant scenario, you can use PowerShell to register and scan your Power BI tenants. You can browse, and search assets of remote tenant using Azure Purview Studio through the UI experience.

Consider using this guide if the Azure AD tenant where Power BI tenant is located, is different than the Azure AD tenant where your Azure Purview account is being provisioned. Use the following steps to register and scan one or more Power BI tenants in Azure Purview in a cross-tenant scenario:

Download the Managed Scanning PowerShell Modules, and extract its contents to the location of your choice.
On your computer, enter PowerShell in the search box on the Windows taskbar. In the search list, select and hold (or right-click) Windows PowerShell, and then select Run as administrator.
Install and import module in your machine if it has not been installed yet.
```
 Install-Module -name az
 Import-Module -name az
 Login-AzAccount
```
Sign into your Azure environment using the Azure AD Administrator credential where your Power BI tenant is located.
```
 Login-AzAccount
```
In the PowerShell window, enter the following command, replacing <path-to-managed-scanning-powershell-modules> with the folder path of the extracted modules such as C:\Program Files\WindowsPowerShell\Modules\ManagedScanningPowerShell
```
dir -Path <path-to-managed-scanning-powershell-modules> -Recurse | Unblock-File
```

Enter the following command to install the PowerShell modules.

Import-Module 'C:\Program Files\WindowsPowerShell\Modules\ManagedScanningPowerShell\Microsoft.DataCatalog.Management.Commands.dll'

Use the same PowerShell session to set the following parameters. Update purview_tenant_id with Azure AD tenant ID where Azure Purview is deployed, powerbi_tenant_id with your Azure AD tenant where Power BI tenant is located, and purview_account_name is your existing Azure Purview account.
```
$azuretenantId = '<purview_tenant_id>'
$powerBITenantIdToScan = '<powerbi_tenant_id>'
$purviewaccount = '<purview_account_name>'
```
Create a cross-tenant Service Principal.
1. Create an App Registration in your Azure Active Directory tenant where Power BI is located. Make sure you update password field with a strong password and update app_display_name with a non-existent application name in your Azure AD tenant where Power BI tenant is hosted.
```
$SecureStringPassword = ConvertTo-SecureString -String <'password'> -AsPlainText -Force
$AppName = '<app_display_name>'
New-AzADApplication -DisplayName $AppName -Password $SecureStringPassword
```
2. From Azure Active Directory dashboard, select newly created application and then select App registration. Assign the application the following delegated permissions and grant admin consent for the tenant:
  - Power BI Service Tenant.Read.All
  - Microsoft Graph openid
3. From Azure Active Directory dashboard, select newly created application and then select Authentication. Under Supported account types select Accounts in any organizational directory (Any Azure AD directory - Multitenant).
4. Under Implicit grant and hybrid flows, ensure to select ID tokens (used for implicit and hybrid flows)
5. Construct tenant-specific sign-in URL for your service principal by running the following url in your web browser:
```
https://login.microsoftonline.com/<purview_tenant_id>/oauth2/v2.0/authorize?client_id=<client_id_to_delegate_the_pbi_admin>&scope=openid&response_type=id_token&response_mode=fragment&state=1234&nonce=67890
```
  Make sure you replace the parameters with correct information:
  - <purview_tenant_id> is the Azure Active Directory tenant ID (GUID) where Azure Purview account is provisioned.
  - <client_id_to_delegate_the_pbi_admin> is the application ID corresponding to your service principal
6. Sign-in using any non-admin account. This is required to provision your service principal in the foreign tenant.
7. When prompted, accept permission requested for View your basic profile and Maintain access to data you have given it access to.
Update client_id_to_delegate_the_pbi_admin with Application (client) ID of newly created application and run the following command in your PowerShell session:
```
$ServicePrincipalId = '<client_id_to_delegate_the_pbi_admin>'
```
Create a user account in Azure Active Directory tenant where Power BI tenant is located and assign Azure AD role, Power BI Administrator. Update pbi_admin_username and pbi_admin_password with corresponding information and execute the following lines in the PowerShell terminal:
```
$UserName = '<pbi_admin_username>'
$Password = '<pbi_admin_password>'
```
Note

If you create a user account in Azure Active Directory from the portal, the public client flow option is No by default. You need to toggle it to Yes:
In Azure Purview Studio, assign Data Source Admin to the Service Principal and the Power BI user at the root collection.

To register the cross-tenant Power BI tenant as a new data source inside Azure Purview account, update service_principal_key and execute the following cmdlets in the PowerShell session:

Set-AzDataCatalogSessionSettings -DataCatalogSession -TenantId $azuretenantId -ServicePrincipalAuthentication -ServicePrincipalApplicationId $ServicePrincipalId -ServicePrincipalKey '<service_principal_key>' -Environment Production -DataCatalogAccountName $purviewaccount

Set-AzDataCatalogDataSource -Name 'pbidatasource' -AccountType PowerBI -Tenant $powerBITenantIdToScan -Verbose

Scan

Follow the steps below to scan a Power BI tenant to automatically identify assets and classify your data. For more information about scanning in general, see our introduction to scans and ingestion

This guide covers both same-tenant and cross-tenant scanning scenarios.

Create and run scan for same-tenant Power BI

To create and run a new scan, do the following:

In the Purview Studio, navigate to the Data map in the left menu.
Navigate to Sources.
Select the registered Power BI source.
Select + New scan.
Give your scan a name. Then select the option to include or exclude the personal workspaces. Notice that the only authentication method supported is Managed Identity.

Note

Switching the configuration of a scan to include or exclude a personal workspace will trigger a full scan of PowerBI source.
Select Test Connection before continuing to next steps. If Test Connection failed, select View Report to see the detailed status and troubleshoot the problem
1. Access - Failed status means the user authentication failed. Scans using managed identity will always pass because no user authentication required.
2. Assets (+ lineage) - Failed status means the Purview - Power BI authorization has failed. Make sure the Purview-managed identity is added to the security group associated in Power BI admin portal.
3. Detailed metadata (Enhanced) - Failed status means the Power BI admin portal is disabled for the following setting - Enhance admin APIs responses with detailed metadata
Set up a scan trigger. Your options are Once, Every 7 days, and Every 30 days.
On Review new scan, select Save and Run to launch your scan.

Create and run scan for cross-tenant Power BI

To create and run a new scan inside Azure Purview execute the following cmdlets in the PowerShell session:

Set-AzDataCatalogScan -DataSourceName 'pbidatasource' -Name 'pbiscan' -AuthorizationType PowerBIDelegated -ServicePrincipalId $ServicePrincipalId -UserName $UserName -Password $Password -IncludePersonalWorkspaces $true -Verbose

Start-AzDataCatalogScan -DataSourceName 'pbidatasource' -Name 'pbiscan'

View your scans and scan runs

To view existing scans, do the following:

Go to the Purview Studio. Select the Data Map tab under the left pane.
Select the desired data source. You will see a list of existing scans on that data source under Recent scans, or can view all scans under the Scans tab.
Select the scan that has results you want to view.
This page will show you all of the previous scan runs along with the status and metrics for each scan run. It will also display whether your scan was scheduled or manual, how many assets had classifications applied, how many total assets were discovered, the start and end time of the scan, and the total scan duration.

Manage your scans - edit, delete, or cancel

To manage or delete a scan, do the following:

Go to the Purview Studio. Select the Data Map tab under the left pane.
Select the desired data source. You will see a list of existing scans on that data source under Recent scans, or can view all scans under the Scans tab.
Select the scan you would like to manage. You can edit the scan by selecting Edit scan.
You can cancel an in progress scan by selecting Cancel scan run.
You can delete your scan by selecting Delete scan.