Creating a Power BI / Fabric service principal

Both the Fabric connection and Power BI connection connections authenticate as a Microsoft Entra ID service principal (app registration), and both need that service principal explicitly allow-listed for API access on the Power BI/Fabric admin side. An app registration and client secret alone isn’t enough for either product. This page covers that shared setup once; the two connection pages link back here and then cover only what’s specific to each (which Airflow connection fields to fill in).

1. Create the app registration

In the Azure portal, open App registrations → + New registration. Give it a descriptive name (e.g. airflow-fabric). Completing the registration automatically creates the matching Enterprise Application alongside it.

Note the Directory (tenant) ID and Application (client) ID from the registration’s overview page — both go into the Airflow connection later.

2. Add owners

Add the platform admins as Owners on both the App registration and its Enterprise Application (App registration → Owners, then the matching Enterprise Application → Owners). Otherwise only whoever created it can manage its credentials or permissions later.

3. Create a client secret

Open Certificates & secrets → + New client secret.

Warning

Copy the secret’s Value immediately after creating it — it’s only ever shown once. If you lose it, delete the secret and create a new one; there’s no way to retrieve an existing value later.

4. Add API permissions

Open the App registration → API permissions → + Add a permission:

  • Fabric (Fabric connection connection, i.e. FabricRunItemOperator): add these delegated Power BI Service permissions: Workspace.ReadWrite.All, Dataset.ReadWrite.All, Item.ReadWrite.All, Item.Execute.All. Leave the default Microsoft Graph User.Read permission in place.

  • Power BI (Power BI connection connection): add the Power BI Service permission your organization grants for dataset refresh — see the screenshot below for exactly which one this org uses.

Then grant admin consent: open Enterprise applications, select the app, go to Permissions, and click Grant admin consent for <tenant>. Confirm every permission shows Granted under Admin consent.

5. Add the service principal to a security group

Power BI and Fabric don’t grant API access to an individual service principal directly — they grant it to an Entra ID security group, and the service principal needs to be a member of one. Create (or reuse) a dedicated security group for this purpose and add the service principal as a member.

6. Allow-list the security group in the admin portal

In the Power BI/Fabric admin portal’s Tenant settings, under Developer settings, enable Allow service principals to use Power BI APIs (or the equivalent Fabric API setting) scoped to the security group from step 5 — not tenant-wide.

7. Grant workspace access

The security group also needs to be a member of every workspace whose datasets/items this service principal will touch — add it under the workspace’s Access (Contributor or Member, depending on whether it only refreshes vs. also needs to manage content).

8. Find workspace and dataset/item IDs

Operators take workspace and dataset/item IDs as arguments, not connection fields. Open the item in the Power BI/Fabric portal and read both IDs out of the browser URL.

Fabric Capacity role (if using fabric_capacity)

Suspend/resume/scale of a capacity is a separate ARM-level permission, not covered by steps 4–7 above. See Airflow administrator guide: managing connections → “Fabric Capacity access (one-time)” for creating the custom role, then assign it to this same service principal the same way as any other role assignment:

  1. Go to the Fabric Capacity resource → Access control (IAM) → Add role assignment.

  2. Select the custom role (Fabric Capacity (Smooth) Operator).

  3. Assign it to this service principal.

  4. Confirm the assignment.

Admin API access (if calling Fabric/Power BI admin APIs)

Steps 4–7 above only cover regular, workspace/item-scoped Fabric and Power BI APIs. Calling admin APIs (tenant-wide operations such as WorkspaceInfo scans, Get Activity Events, or Fabric’s Workspaces - Restore Workspace) needs a separate opt-in. See Enable service principal authentication for admin APIs.

Warning

For read-only admin APIs specifically, the app registration must have no admin-consent-required Application permissions on it at all — not “none relevant to Fabric”, literally none. If step 4 above added the Item.ReadWrite.All etc. Application-type permissions to this same app registration, read-only admin API calls will be rejected. Use a separate, dedicated app registration for read-only admin API access rather than reusing the one from steps 1–4.

  1. Check for admin-consent-required permissions: Azure portal → Microsoft Entra ID → Enterprise applications → this app → Permissions. Confirm there are no admin-consent-required permissions of type Application listed (only relevant to the read-only admin APIs toggle below).

  1. Create (or reuse) a dedicated Entra security group for admin API access and add this service principal as a member. Same mechanism as step 5 above, but keep it a distinct group from the one allow-listed in step 6: the two toggles are scoped independently, and a service principal that’s allowed to run item-level API calls shouldn’t automatically also be allowed to run tenant-wide admin API calls.

  2. In the Power BI/Fabric admin portal’s Tenant settings, under Admin API settings, enable the toggle for the type of admin API this service principal needs — Service principals can access read-only admin APIs or Service principals can access admin APIs used for updates — select Specific security groups, add the group from step 2, then click Apply.

A service principal can call admin APIs over REST with these settings, but still can’t open Fabric interactively with those credentials. Enabling either toggle requires Fabric admin rights on the account doing it — a platform admin, not this service principal.