Ataccama ONE Agentic Cloud Portal ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
latest (17.0.0) 16.3.0 16.2.0 16.1.0 16.0.0 15.4.0 15.3.0 15.2.0 15.1.0 14.5.x 13.9.x 13.8.x 13.7.x 13.6.x 13.5.0 13.4.x 13.3.x 13.2.x
User Community Service Desk Downloads

Power BI Lineage Scanner

Scanned and supported objects

The scanner automatically generates lineage metadata for all currently supported sources and connections. However, lineage coverage might vary depending on system capabilities, dynamic transformations, or access permissions.

While we strive for comprehensive lineage capture, certain dataflows and transformations might be incomplete or unavailable due to technical constraints. We continuously work to expand coverage and accuracy.

For a detailed breakdown of supported features and known limitations, see Power BI Scanner Supported Features and Limitations.

Supported connectivity

  • Connector type: REST API.

  • Authentication method: OAuth 2.0 Client Credentials Flow (Service Principal).

Choosing your setup

The scanner supports two authentication options. Choose the one that best fits your organization’s security requirements.

Option 1: Admin-level access configuration: Use when the scanning identity can be granted a Global Admin or Fabric Admin role. This is a simpler setup with automatic access to all workspaces.

Option 2: Least-privilege setup: Use when the organization cannot or will not grant admin-level privileges. Requires per-workspace Contributor access but follows the principle of least privilege.

Admin-level access setup

Grant administrator rights

The identity used for scanning must have one of the following roles:

  • Microsoft 365 Global Administrator

  • Power BI Service Administrator (Fabric Administrator)

When running under service principal authentication, the service principal app must not have any admin-consent required permissions for Power BI set in the Azure portal.

For more details, see the official Microsoft documentation.

Enable tenant settings for metadata scanning

The following tenant settings need to be configured. Go to Admin portal > Tenant settings > Admin API settings.

  • Enhance admin APIs responses with detailed metadata: Turns on model caching and enhances API responses with low-level semantic model metadata (for example, name and description) for tables, columns, and measures.

    Enhance admin APIs responses with detailed metadata

  • Enhance admin APIs responses with DAX and mashup expressions: Allows the API response to include DAX expressions and Mashup queries. This setting can only be used if the first setting is also configured.

    Enhance admin APIs responses with DAX and mashup expressions

Workspace access

The scanning identity automatically has access to all workspaces when it holds an admin role. No additional workspace-level configuration is required.

Least-privilege setup

This option does not require granting any admin role to the service principal. Instead, the service principal obtains its effective permissions from tenant-level settings and workspace-level access grants.

This is Microsoft’s recommended approach for service principal access to Power BI APIs. A Microsoft Entra application created for a service principal does not require any delegated or application permissions configured in the Azure portal.

For details, see Microsoft’s service principal embedding guide.

Step 1: Register a Microsoft Entra application

  1. In the Azure portal, go to Microsoft Entra ID > App registrations > New registration.

  2. Enter a meaningful name (for example, Ataccama Power BI Scanner).

  3. Select Accounts in this organizational directory only as the supported account type.

  4. Leave the Redirect URI blank and select Register.

  5. Note the Application (client) ID. This is your clientId.

Client ID in Azure

Step 2: Create a client secret

  1. In the app registration, go to Certificates & secrets > Client secrets > New client secret.

  2. Enter a description and choose an expiration period.

  3. Copy the secret Value immediately; it is shown only once. This is your clientSecret.

Step 3: Configure API permissions

In addition to the default User.Read permission that is auto-added during app registration, add the following Delegated permissions for the Power BI Service. These permissions allow the scanner to read workspace metadata, reports, datasets, and dataflows.

  1. In the app registration, go to API permissions > Add a permission > Power BI Service.

  2. Select Delegated permissions and add each of the following:

Permission Type Admin consent required Purpose

Report.Read.All

Delegated

No

Read reports in accessible workspaces.

Dataset.Read.All

Delegated

No

Read datasets and semantic models.

Workspace.Read.All

Delegated

No

Read workspace metadata.

Dataflow.Read.All

Delegated

No

Read dataflows.

When adding these permissions in the Azure portal, pay attention to the following. Getting any of these wrong will cause the scanner to fail with a 401 Unauthorized error:

  • When selecting permissions, always choose Delegated permissions, not Application permissions. In the Azure portal, both options are displayed side by side.

  • After adding the permissions, do not select Grant admin consent for [your organization].

    The Status column should show "Not granted" with a user-consent checkmark. If it shows "Granted for [organization]", the service principal authentication will break.

  • If you find any existing permissions of type Application that have already been granted, remove them before running the scanner.

Step 4: Create an Entra ID security group

  1. In the Azure portal, go to Microsoft Entra ID > Groups > New group.

  2. Set the Group type to Security (not Microsoft 365).

  3. Enter a meaningful name (for example, Ataccama Power BI Scanners).

  4. Add the App Registration as a member; it appears as type Service Principal in the members list.

  5. Note the Object ID of the group. You will use it when configuring tenant settings and workspace access.

Step 5: Configure Power BI tenant settings

A Fabric Administrator must enable the following four settings in the Power BI Admin Portal. All four support scoping to a specific security group (recommended over "The entire organization").

Setting Section Purpose

Allow service principals to use Power BI APIs

Developer settings

Enables the service principal to call Power BI REST APIs.

Allow service principals to use read-only admin APIs

Admin API settings

Enables metadata scanning via admin scanner APIs.

Enhance admin APIs responses with detailed metadata

Admin API settings

Returns schema, table, and column-level detail in scan results.

Enhance admin APIs responses with DAX and mashup expressions

Admin API settings

Returns DAX measures and Power Query (M) expressions, which are essential for building lineage.

For each setting, select Specific security groups and enter the security group created in Step 4.

Enhance admin APIs responses with detailed metadata
Enhance admin APIs responses with DAX and mashup expressions

If the Download Reports setting in the Admin Portal is restricted to a subset of the organization, the security group must be included in that subset. The scanner downloads .pbix files to extract Power Query expressions used for lineage.

Changes to tenant settings can take 15–30 minutes to propagate. Wait before running your first scan after making changes.

Step 6: Grant Contributor access on target workspaces

The security group must have at least Contributor access on each Power BI workspace to be scanned. Contributor is the minimum role that allows the scanner to download reports and read workspace content.

To grant access manually:

  1. In Power BI, locate the workspace you want to scan.

    Locate workspace

  2. Select Manage access and add the security group with the Contributor role.

To grant access in bulk using PowerShell:

Add-PowerBIWorkspaceUser -Scope Organization -Id <WorkspaceId> `
  -Identifier <SecurityGroupObjectId> -AccessRight Contributor -PrincipalType Group

Scanner configuration

All fields marked with an asterisk (*) are mandatory.

Property Description

name*

Unique name for the scanner job.

sourceType*

Specifies the source type to be scanned. Must contain POWER_BI.

description*

A human-readable description of the scan.

oneConnections

List of Ataccama ONE connection names for future automatic pairing.

powerQueryParserPath*

Path to the PowerQueryParser execution file.

apiUrl*

URL of the Power BI REST API endpoint.

tokenUrl*

REST endpoint for Microsoft OAuth 2.0. The URL should contain the tenant ID of your organization.

See Tenant ID in Azure.

clientID*

Microsoft OAuth 2.0 credentials client ID.

See Client ID in Azure.

clientSecret*

Microsoft OAuth 2.0 credentials client secret.

workspaces_disabled

List of workspace IDs to be excluded from the scan.

workspaces

List of workspace IDs to be scanned. If left empty, the scanner scans everything.
Power BI scanner example configuration
{
   "scannerConfigs": [
      {
         "name": "Power BIJob1",
         "sourceType": "POWER_BI",
         "description": "Scan Power BI platform",
         "oneConnections": [],
         "inputDataCatalogFilePath": null,
         "powerQueryParserPath": "@@ref:env:[POWERQUERY_PARSER]",
         "tokenUrl": "https://login.microsoftonline.com/[tenantID]/oauth2/v2.0/token",
         "apiUrl": "https://api.powerbi.com/v1.0/myorg",
         "clientId": "your-client-id",
         "clientSecret": "@@ref:ata:[POWER_BI_CLIENT_SECRET]",
         "workspaces": [
             "workspace-id1-to-include",
             "workspace-id2-to-include"
         ]
      }
   ]
}

Tenant ID in Azure

To find your organization tenant ID, in your Azure portal (portal.azure.com), go to Azure Active Directory > Properties.

Tenant ID in Azure

Client ID in Azure

Register a Microsoft Entra application in Azure.

The Microsoft Entra app establishes permissions for Power BI REST resources and allows access to the Power BI REST APIs.

Client ID in Azure

Pre-scan validation checklist

Before running your first scan, verify the following:

  1. The App Registration has a valid client secret that has not expired.

  2. API permissions contain no Application-type entries and no admin-consented Power BI permissions.

  3. The admin account (Admin-level access setup) or security group (Least-privilege setup) is correctly configured.

  4. All four Power BI tenant settings are enabled and scoped to the correct security group.

  5. At least 15–30 minutes have passed since the last tenant setting change.

  6. The scanning identity has Contributor (or higher) access on every target workspace (Least-privilege setup), or holds an admin role (Admin-level access setup).

  7. The Download Reports tenant setting allows access for the scanning identity.

  8. The tokenUrl in the scanner configuration contains your correct tenant ID.

  9. The apiUrl is set to https://api.powerbi.com/v1.0/myorg.

Troubleshooting Power BI scanner

Application with identifier was not found

If you encounter an error such as "`AADSTS700016` — Application with identifier was not found", this typically indicates the client ID or tenant ID in the scanner configuration is incorrect.

Verify both values in the Azure portal under App registrations and Azure Active Directory > Properties.

HTTP 401 Unauthorized when calling admin APIs

The app registration has Application-type permissions or admin consent has been granted for Power BI permissions.

Open App registrations > API permissions and remove any Application-type entries or revoke admin consent.

Scan results empty or incomplete

If the scan completed but the results are empty or incorrect, the scanning identity does not have access to the target workspaces.

Verify that the security group has Contributor access on each workspace (Least-privilege setup), or that the admin role is correctly assigned (Admin-level access setup).

DAX measures or Power Query (M) expressions missing from results

This typically occurs when the tenant settings Enhance admin APIs responses with detailed metadata and Enhance admin APIs responses with DAX and mashup expressions are not enabled, or have not yet propagated.

Enable both settings and wait 15–30 minutes before re-running the scan.

Reports skipped or inaccessible

If you notice that some reports have been skipped or cannot be opened, it’s likely that reports with sensitivity labels applied were excluded from scan results. This is a known Microsoft limitation.

Verify that the affected reports have sensitivity labels and consider adjusting label policies if lineage coverage is required.

Scan fails when downloading pbix files

The Download Reports tenant setting is turned off or does not include the scanning identity.

Enable the setting in Admin portal > Tenant settings > Export and sharing settings and ensure the security group is included.

Was this page useful?