Creating a Power BI / Fabric service principal ================================================== Both the :doc:`fabric` and :doc:`powerbi` 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. .. TODO: screenshot of App registrations with "+ New registration" highlighted Note the **Directory (tenant) ID** and **Application (client) ID** from the registration's overview page — both go into the Airflow connection later. .. TODO: screenshot of the app registration overview showing tenant ID and client ID 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**. .. TODO: screenshot of Certificates & secrets with "+ New client secret" highlighted .. 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** (:doc:`fabric` 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** (:doc:`powerbi` connection): add the Power BI Service permission your organization grants for dataset refresh — see the screenshot below for exactly which one this org uses. .. TODO: screenshot of API permissions with the specific permission added (Power BI Service, application/delegated as applicable) Then grant admin consent: open **Enterprise applications**, select the app, go to **Permissions**, and click **Grant admin consent for **. Confirm every permission shows ``Granted`` under **Admin consent**. .. TODO: screenshot of the Permissions page with the "Grant admin consent" button and all permissions showing Granted 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. .. TODO: screenshot of the tenant setting with the security group added 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). .. TODO: screenshot of workspace Access with the security group added 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. .. TODO: screenshot of a dataset's URL with the workspace ID segment highlighted .. TODO: screenshot of a dataset's URL with the dataset ID segment highlighted 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 :doc:`../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. .. TODO: screenshot of the role assignment showing the custom role with this service principal listed as a member, scope Subscription (Inherited) or the capacity resource itself 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). .. TODO: screenshot of the Enterprise application's Permissions page showing no Application-type permissions 2. 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. 3. 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**. .. TODO: screenshot of the Admin API settings toggle enabled, scoped to the specific security group 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.