Set Up Power BI Service Credentials

Overview

Soterre PBI Analyzer uses a Service Principal (service account) to access the Power BI REST API. This is a secure way to automate access without using personal credentials.

What You’ll Need

• Administrator access to Azure Portal (portal.azure.com)
• Administrator access to Power BI Admin Portal (app.powerbi.com/admin-portal)
• Permissions to create applications in Azure AD
• Fabric / Power BI Premium capacity (for the Capacity module)

---

Prerequisites

Required Roles

Portal	Minimum Role
Azure AD	Application Administrator or Global Administrator
Power BI	Fabric Administrator or Power BI Administrator

Licenses

• For basic functionality: Power BI Pro
• For Capacity module: Fabric Capacity (F SKU) or Power BI Premium (P SKU)

---

Step 1: Create Azure AD Application

1.1 Open Azure Portal

1. Go to https://portal.azure.com
2. Sign in with an administrator account

1.2 Navigate to Azure Active Directory

1. In the search bar, type “Azure Active Directory”
2. Select “Microsoft Entra ID” from the results

1.3 Create a New Application

1. In the left menu, select “App registrations”
2. Click ”+ New registration”

1.4 Fill in the Registration Form

Field	Value
Name	PBI-Analyzer (or any descriptive name)
Supported account types	Accounts in this organizational directory only
Redirect URI	Leave blank

3. Click “Register”

1.5 Save Important Identifiers

After creating the application, you’ll see the Overview page. Copy and save:

Application (client) ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  ← This is your CLIENT_ID
Directory (tenant) ID:   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  ← This is your TENANT_ID

IMPORTANT: Save these values — you’ll need them later!

---

Step 2: Configure API Permissions

2.1 Open API Permissions Section

1. In the left menu of your application, select “API permissions”
2. Click ”+ Add a permission”

2.2 Add Power BI Service Permissions

1. Select “Power BI Service”
2. Select “Application permissions” (NOT Delegated!)
3. Check the following permissions under Tenant:
   • Tenant.Read.All — View all content in tenant
   • Tenant.ReadWrite.All — Read and write all content in tenant
4. Click “Add permissions”

Then click Power BI Service again and add Application permissions for:

Category	Permission	Description
Capacity	Capacity.Read.All	View all capacities
Workspace	Workspace.Read.All	View all workspaces
Dataset	Dataset.Read.All	View all datasets
Report	Report.Read.All	Read reports

Select Read.All for every category listed above.

2.3 Grant Admin Consent

IMPORTANT: Without this step, the application won’t work.

1. Click the “Grant admin consent for [Your organization]” button
2. Confirm by clicking “Yes”

After successful consent, all permissions should show a green checkmark.

---

Step 3: Create Client Secret

3.1 Open Certificates & Secrets Section

1. In the left menu of your application, select “Certificates & secrets”
2. Go to the “Client secrets” tab
3. Click ”+ New client secret”

3.2 Create the Secret

Field	Recommended Value
Description	PBI-Analyzer-Secret
Expires	24 months (or per your organization’s policy)

3. Click “Add”

3.3 Copy the Secret Immediately

CRITICAL: After creating the secret, its value is shown ONLY ONCE. If you leave the page without copying it, you’ll need to create a new secret.

Copy the value from the “Value” column (NOT “Secret ID”).

---

Step 4: Create Security Group

A security group is needed to control which service principals can access the Power BI Admin APIs. This is a security best practice.

4.1 Create the Security Group in Azure

1. Go to Azure Portal (portal.azure.com)
2. Navigate to Microsoft Entra ID > Groups
3. Click ”+ New group”

4.2 Fill in Group Details

Field	Value
Group type	Security
Group name	PBI-Analyzer (or any descriptive name)
Group description	Security group for Soterre PBI Analyzer service principal
Membership type	Assigned

4.3 Add the Service Principal as a Member

1. Under “Members”, click “No members selected”
2. Search for “PBI-Analyzer” (the app name you registered in Step 1)
3. Select it and click “Select”
4. Click “Create”

Note: If you can’t find the service principal by app name, try searching by the Application (client) ID. You may also need to look under “Enterprise applications” in Entra ID first to ensure the service principal exists.

---

Step 5: Configure Power BI Admin Portal

5.1 Open Power BI Admin Portal

1. Go to https://app.powerbi.com
2. Click the gear icon in the top right corner
3. Select “Admin portal”

5.2 Enable Service Principal API Access

1. In the left menu, select “Tenant settings”
2. Scroll down to the “Admin API Settings” section
3. Find “Service principals can access read-only admin APIs”

5.3 Configure the Permission

1. Toggle the switch to Enable
2. Under “Apply to:”, select “Specific security groups”
3. Add the PBI-Analyzer security group (created in Step 4)
4. Click “Apply”

5.4 Also Enable These Settings (Same Process)

Repeat the same for these additional tenant settings:

Setting	Status	Apply to
Service principals can access read-only admin APIs	Enabled	PBI-Analyzer security group
Service principals can access admin APIs used for updates	Enabled	PBI-Analyzer security group
Enhance admin APIs responses with detailed metadata	Enabled	Entire organization
Allow service principals to use Power BI APIs	Enabled	PBI-Analyzer security group

Note: After changing tenant settings, it may take up to 15 minutes for the changes to take effect.

---

Step 6: Install Fabric Capacity Metrics App

This step is required for the Capacity module to show real CU (Compute Unit) consumption data.

6.1 Install the Application

1. Go to https://app.powerbi.com
2. Navigate to Apps (left sidebar)
3. Click “Get apps” (top right)
4. Search for “Microsoft Fabric Capacity Metrics”
5. Click “Get it now”

6.2 Connect to Your Capacity

1. After installation, open the app
2. It will prompt you to connect to a capacity — select your capacity from the dropdown
3. Click “Connect”
4. Wait for the data to refresh (this may take a few minutes)

6.3 Get the Workspace ID and Dataset ID

You need these two IDs to enter in Soterre PBI Analyzer:

From the URL:

1. Open the Fabric Capacity Metrics app in Power BI
2. Look at the browser URL bar. It will look like:

   https://app.powerbi.com/groups/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/...

3. The GUID after /groups/ is your Metrics Workspace ID
4. Navigate to the workspace containing the metrics dataset
5. Click on the dataset (semantic model) named “Fabric Capacity Metrics”
6. The URL will show:

   https://app.powerbi.com/groups/.../datasets/YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY/...

7. The GUID after /datasets/ is your Metrics Dataset ID

---

Step 7: Add Service Principal to Workspaces

This is a critical step! The Soterre PBI Analyzer service principal needs workspace-level access to read your data.

7.1 Why Is This Needed?

Soterre PBI Analyzer uses the Power BI REST API (GET /groups) to list workspaces. This API only returns workspaces where the service principal has been explicitly added as a member. Without adding the service principal to a workspace, the analyzer cannot see it.

7.2 Which Workspaces Need Access?

Workspace	Required?	Purpose
Your business workspaces	Yes — for each workspace you want to analyze	Scan reports, datasets, refresh history
Microsoft Fabric Capacity Metrics	Yes — required for CU chart	Run DAX queries for capacity metrics

7.3 How to Add the Service Principal

For each workspace you want to analyze:

1. Open Power BI (app.powerbi.com)
2. Navigate to the workspace (e.g., “BI_Test”)
3. Click “Manage access” (or click ”…” > “Workspace access”)
4. Click ”+ Add people or groups”
5. Search for “PBI-Analyzer” (your service principal name)
6. Set the role:
   • Member — sufficient for reading data (recommended)
   • Admin — full access (also works)
7. Click “Add”

7.4 Important: Add to Fabric Capacity Metrics Workspace

The service principal MUST also be added to the “Microsoft Fabric Capacity Metrics” workspace. Without this, the CU utilization chart will not work because the app runs DAX queries against the capacity metrics dataset.

1. Find the “Microsoft Fabric Capacity Metrics” workspace in your workspace list
2. Click ”…” > “Workspace access”
3. Add “PBI-Analyzer” with Member or Admin role

Note: Viewer role is NOT sufficient for the Fabric Capacity Metrics workspace because the service principal needs to execute DAX queries (which requires at least Contributor/Member access).

---

Step 8: Add Tenant to Soterre PBI Analyzer

Now that your service principal is fully configured, add it to the app. See the step-by-step instructions on the Add a New Tenant page.

---

Troubleshooting

Problem	Possible Cause	Solution
”Unauthorized” error when scanning	Admin consent not granted	Go to Step 2.3 and grant admin consent again
Service principal not found when adding to workspace	Enterprise application not created automatically	Go to Entra ID > Enterprise applications and verify the app exists
No workspaces returned by the API	Service principal not added to any workspace	Complete Step 7 — add the service principal to each workspace
CU utilization chart is empty	Metrics Workspace ID / Dataset ID not set, or service principal not added to the Metrics workspace	Complete Steps 6.3 and 7.4
Tenant settings not taking effect	Propagation delay	Wait up to 15 minutes after changing tenant settings
Client secret expired	Secret exceeded its configured expiration	Create a new client secret (Step 3) and update Soterre PBI Analyzer