> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dqlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Prerequisites, authentication methods, and step-by-step instructions for connecting Microsoft Power BI to Prizm.

<script type="application/ld+json">
  {`{
            "@context": "https://schema.org",
            "@type": "TechArticle",
            "headline": "Power BI Setup",
            "description": "Prerequisites, authentication methods, and step-by-step instructions for connecting Microsoft Power BI to Prizm.",
            "url": "https://docs.dqlabs.ai/sources/powerbi/setup",
            "publisher": {
              "@type": "Organization",
              "name": "DQLabs Inc",
              "logo": "https://media.brand.dev/332adc35-5bc4-4d2b-bf78-256aa4a5e414.svg"
            }
            }`}
</script>

## Prerequisites

Before connecting, ensure the following are in place:

* The workspaces Prizm will scan are hosted on **Power BI Premium Per User (PPU), Premium capacity, or Microsoft Fabric capacity**. Prizm reads semantic model metadata (tables, columns, measures, relationships, calculated fields) over the **XMLA endpoint**, which is only available on these capacity tiers — a standard Pro license alone is not sufficient.
* The **XMLA endpoint** is enabled with **Read** access for metadata discovery (Power BI Admin portal → **Tenant settings → Integration settings**). Write access is not required.
* The Prizm service identity has been granted the required API permissions in Azure Active Directory (see below).
* **Admin API access** is enabled in the Power BI tenant settings: go to the Power BI admin portal → **Tenant settings → Admin API settings** and enable **Allow service principals to use read-only Power BI admin APIs**.
* **Fabric API access** is enabled for service principals: in the Fabric Admin portal, go to **Tenant settings → Developer settings** and enable **Service principals can call Fabric public APIs**.
* If you plan to use **OAuth 2.0** authentication, a **redirect URI** is registered on the Azure AD app registration: `https://<your-prizm-domain>/source/powerbi/callback`.

### Required API Permissions

Prizm accesses Power BI through the Power BI REST API and the Power BI Scanner API. The following delegated or application permissions are required in Azure AD, depending on your authentication method:

| Permission           | Purpose                                                 |
| :------------------- | :------------------------------------------------------ |
| `Dataset.Read.All`   | Read semantic model metadata, tables, columns, measures |
| `Dashboard.Read.All` | Read dashboard tiles and metadata                       |
| `Report.Read.All`    | Read report metadata and page structure                 |
| `Workspace.Read.All` | List and enumerate all workspaces                       |
| `Dataflow.Read.All`  | Read dataflow metadata and M-expressions                |

<Note>
  All permissions above are **read-only**. Prizm does not write to, modify, or trigger refreshes on your Power BI assets during catalog or observability runs.
</Note>

## Connector Setup

<Steps>
  <Step title="Open the connector wizard">
    Navigate to **Settings → Connectors** and click **Add**. Select **Power BI** from the source type grid.

    | Field               | Description                                        |
    | :------------------ | :------------------------------------------------- |
    | **Connection Name** | A label for this connection (e.g., `powerbi-prod`) |
    | **Description**     | Optional notes about what this connection covers   |
  </Step>

  <Step title="Choose an authentication method">
    Select your authentication method from the dropdown. The three supported methods are described below.

    <Tabs>
      <Tab title="Service Principal (Recommended)">
        Service Principal is the **recommended authentication method** for production deployments. It authenticates as a registered Azure AD application rather than a named user, which means:

        * Credentials are not tied to an individual's account or license
        * Permissions survive employee offboarding or license changes
        * Audit logs show a distinct service identity rather than a user account

        **Azure-side setup:**

        1. Go to **Azure Portal → Azure Active Directory → App registrations → New registration**. Give it a name (e.g., `prizm-powerbi-connector`).
        2. Under **Certificates & secrets**, create a **Client secret**. Copy the value immediately — it is shown only once.
        3. Under **API permissions**, add the five permissions listed in Prerequisites as **Application** permissions and grant admin consent.
        4. Note the **Application (client) ID** and **Directory (tenant) ID** from the app's overview page.
        5. In the **Power BI Admin portal → Tenant settings → Admin API settings**, add the service principal's security group (or the app itself) to the allowed list.

        Then enter the following in Prizm:

        | Field             | Description                                   |
        | :---------------- | :-------------------------------------------- |
        | **Tenant ID**     | Azure AD directory (tenant) ID                |
        | **Client ID**     | Application (client) ID of the registered app |
        | **Client Secret** | The secret value generated in step 2          |

        **Workspace access:** In addition to the Azure AD permissions above, the service principal must be added directly to each target Power BI workspace (workspace **Manage access** → add the app/service principal) with the **Member** or **Admin** role. It also needs **Build** permission on the semantic models Prizm will scan — this is required for XMLA metadata access.

        <Note>
          The same Entra ID app registration can be reused across Service Principal, Master User, or OAuth authentication, depending on which method you select for this connection.
        </Note>
      </Tab>

      <Tab title="Master User">
        Master User authenticates with a standard Power BI user account (username and password). The account must have a Power BI Pro or Premium Per User license and must be a member of all workspaces you want Prizm to access.

        <Warning>
          Master User authentication is not recommended for production. If the user's account is disabled, their password changes, or MFA enforcement changes, the connector will fail silently until credentials are updated. Use Service Principal for stable, long-running connections.
        </Warning>

        | Field        | Description                                |
        | :----------- | :----------------------------------------- |
        | **Username** | Email address of the Power BI user account |
        | **Password** | Account password                           |

        **Requirements:**

        * The account must **not** have MFA enforced (or must be excluded from MFA conditional access policies for service-account use).
        * The account must have at least Power BI Pro license.
        * Add the account as a **Member** or **Admin** in each workspace you want Prizm to catalog.
      </Tab>

      <Tab title="OAuth 2.0">
        OAuth 2.0 uses the delegated authorization flow to connect Prizm as the authenticated user who grants access. This is suited for single-user or evaluation setups where a Service Principal is not yet available.

        Before authorizing, make sure the Azure AD app registration has the following **redirect URI** configured: `https://<your-prizm-domain>/source/powerbi/callback`.

        Click **Authorize with Microsoft** in the Prizm connector form. You will be redirected to Microsoft's login page to grant the required permissions. Once you approve, Prizm stores the refresh token and renews access automatically.

        **Limitations:**

        * Access is bound to the authorizing user's account and workspace memberships.
        * If the user's account changes (password reset, license change, MFA), the token may be invalidated.
        * Not recommended for shared or production environments — use Service Principal instead.
      </Tab>
    </Tabs>

    <Tip>
      For production deployments, always use **Service Principal**. It avoids credential decay, works with tenant-level admin API access, and produces a clean audit trail.
    </Tip>
  </Step>

  <Step title="Configure extraction scope">
    After authentication is verified, select which workspaces to include:

    | Setting               | Description                                                                                                      |
    | :-------------------- | :--------------------------------------------------------------------------------------------------------------- |
    | **Workspaces**        | Select specific workspaces by name, or leave blank to include all workspaces the service principal has access to |
    | **Extract Dataflows** | Toggle on to include Power Query dataflows in the catalog and lineage graph. Disabled by default.                |

    <Note>
      Enabling **Extract Dataflows** increases catalog job duration proportionally to the number of dataflows in scope. Enable it only for workspaces where dataflows are part of the lineage you want to trace.
    </Note>
  </Step>

  <Step title="Review job schedules">
    For Power BI connections with semantic models in scope, Prizm creates the following background jobs automatically. You can adjust their schedules from the connector detail page after saving:

    | Job                           | Default Cadence                                          | What it collects                                                                                                                                                                                                               |
    | :---------------------------- | :------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Technical**                 | Daily — first job in the pipeline                        | Workspace metadata and semantic model schema (tables, columns, measures, calculated columns, relationships, hierarchies) via the XMLA endpoint, plus reports, dashboards, dataflows, and data sources via the REST/Scanner API |
    | **Operational**               | Hourly                                                   | Volume, freshness, and schema-change signals on semantic models, including refresh history and success/failure status                                                                                                          |
    | **Performance**               | Daily                                                    | Refresh duration trends and capacity/query performance signals for semantic models                                                                                                                                             |
    | **Profile Recommendation**    | Runs in parallel after Operational completes             | Determines which semantic model columns to profile, at what frequency, based on criticality and scope. The Profile job will not run until this job produces its output.                                                        |
    | **Profile**                   | Runs on the schedule generated by Profile Recommendation | Column-level statistical profiling on semantic model columns — null rate, distinct count, min/max, mean, pattern conformance, and related metrics                                                                              |
    | **Structural Recommendation** | Runs in parallel after Operational completes             | Recommends structural quality metrics (Essential or Advanced) for each semantic model column, based on data type and criticality. The Structural job executes against this output.                                             |
    | **Structural**                | Triggered after Structural Recommendation completes      | Distribution, frequency, pattern, and statistics metrics at the column level for in-scope semantic model columns                                                                                                               |

    <Note>
      This job set applies to Power BI connections where semantic models are in scope. Governance, Usage Summary, Compute Metric, and Lineage jobs are not part of the current Power BI job pipeline. Operational, Technical, and Performance job execution has been verified directly against a live Power BI connector.
    </Note>

    **Manual re-sync:** Trigger a manual catalog run at any time from **Settings → Connectors → \[your connection] → Run Now**. Manual runs execute immediately without disrupting the configured schedule.
  </Step>

  <Step title="Save and verify">
    Click **Save** to create the connection. Prizm runs an initial full catalog scan immediately. Assets appear in the catalog within a few minutes depending on workspace size.

    Navigate to **Settings → Connectors → Logs** to monitor scan progress and review any errors from the initial run.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="What We Collect" icon="database" href="/sources/powerbi/what-we-collect">
    See the full field-level breakdown of every metadata object Prizm extracts from Power BI.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/sources/powerbi/faq">
    Common questions about authentication, scoping, and permissions.
  </Card>
</CardGroup>