Soterre PBI Analyzer

Appearance

Set Up Power BI Service Credentials ​

Step-by-step guide to configure Azure AD, Power BI permissions, and connect Soterre PBI Analyzer to your tenant.

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)

Who Can Do Each Step ​

Steps 1–5 are admin-only. If you are not an administrator, see What if you don't have admin rights? — you can send this page to your admin and continue from Step 6 once they're done.

StepWhatWho can do it
1–3Azure app registration, API permissions, client secretAzure admin (Application Administrator / Global Administrator)
4Security groupAzure admin
5Power BI Admin Portal settingsFabric Administrator / Power BI Administrator
6Install Capacity Metrics appAny user with capacity admin rights
7Add Service Principal to workspacesWorkspace Admin (no tenant admin needed)
8Add tenant in the analyzerAny user — just needs the credentials from steps 1–3

Prerequisites ​

Required Roles ​

PortalMinimum Role
Azure ADApplication Administrator or Global Administrator
Power BIFabric 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 ​

⚠️ Admin required (Steps 1–4). These steps happen in the Azure Portal and need the Application Administrator (or Global Administrator) role. Not an admin? Forward this page to your IT administrator — everything they need is written down step by step.

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 ​

FieldValue
NamePBI-Analyzer (or any descriptive name)
Supported account typesAccounts in this organizational directory only
Redirect URILeave blank
  1. Click "Register"

Register a new application in Azure AD

1.5 Save Important Identifiers ​

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

Application Overview page with the client ID and tenant ID

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"

Request API permissions — pick Power BI Service

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:

CategoryPermissionDescription
CapacityCapacity.Read.AllView all capacities
WorkspaceWorkspace.Read.AllView all workspaces
DatasetDataset.Read.AllView all datasets
ReportReport.Read.AllRead reports

Select Read.All for every category listed above.

Select the application permissions under Power BI Service

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"

Grant admin consent for the organization

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

All permissions granted with green checkmarks

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 ​

FieldRecommended Value
DescriptionPBI-Analyzer-Secret
Expires24 months (or per your organization's policy)
  1. 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").

New client secret — copy the Value column immediately

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 ​

FieldValue
Group typeSecurity
Group namePBI-Analyzer (or any descriptive name)
Group descriptionSecurity group for Soterre PBI Analyzer service principal
Membership typeAssigned

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"

Create the security group and add the service principal

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 ​

⚠️ Admin required. This step needs the Fabric Administrator (or Power BI Administrator) role — the Admin Portal is simply not visible to regular users. If the Settings → Admin portal menu item is missing for you, ask your admin to do this step.

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"

Admin API settings — enable for the PBI-Analyzer security group

5.4 Also Enable These Settings (Same Process) ​

Repeat the same for these additional tenant settings:

SettingStatusApply to
Service principals can access read-only admin APIsEnabledPBI-Analyzer security group
Service principals can access admin APIs used for updatesEnabledPBI-Analyzer security group
Enhance admin APIs responses with detailed metadataEnabledEntire organization
Allow service principals to use Power BI APIsEnabledPBI-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"

Install the Microsoft Fabric Capacity Metrics app

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

The dataset GUID in the browser URL is your Metrics Dataset ID

Step 7: Add Service Principal to Workspaces ​

✅ No tenant admin needed. Any workspace Admin can do this step for their own workspace.

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? ​

WorkspaceRequired?Purpose
Your business workspacesYes — for each workspace you want to analyzeScan reports, datasets, refresh history
Microsoft Fabric Capacity MetricsYes — required for CU chartRun 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"

Manage access panel — click Add people or groups

  1. Search for "PBI-Analyzer" (your service principal name)
  2. Set the role:
    • Member — sufficient for reading data (recommended)
    • Admin — full access (also works)
  3. Click "Add"

Choose the role for the service principal

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.

What if you don't have admin rights? ​

Most organizations split these roles, so it's normal that you can't do Steps 1–5 yourself. Three common situations:

1. You know who your admin is ​

Send them the link to this page with a short note — for example:

Hi! We want to connect Soterre PBI Analyzer (a Power BI QA / monitoring tool) to our tenant. It needs a standard Service Principal setup — an app registration in Azure plus two toggles in the Power BI Admin Portal. Steps 1–5 on this page are the admin part, it takes about 15 minutes: <link to this page>. Could you run through them and send me back the Tenant ID, Client ID and Client Secret?

Once you receive the three values, continue from Step 7 (workspace access) and Step 8 yourself.

2. You don't know who your admin is ​

  • Ask your IT helpdesk "who manages our Microsoft 365 / Azure tenant?"
  • Or check inside Power BI: if Settings (gear) → Admin portal is visible to you, you already have the admin role; if not, the person who manages your Microsoft licenses is the right contact.

3. Small team, no dedicated admin ​

Whoever originally set up your Microsoft 365 / Power BI subscription holds the Global Administrator role. That person can either:

  • run Steps 1–5 themselves, or
  • grant your account the needed roles in the Microsoft 365 admin center → Users → Active users → your user → Manage roles: add Application Administrator (for Steps 1–4) and Fabric Administrator (for Step 5). After that you can complete the whole guide yourself.

Troubleshooting ​

ProblemPossible CauseSolution
"Unauthorized" error when scanningAdmin consent not grantedGo to Step 2.3 and grant admin consent again
Service principal not found when adding to workspaceEnterprise application not created automaticallyGo to Entra ID > Enterprise applications and verify the app exists
No workspaces returned by the APIService principal not added to any workspaceComplete Step 7 — add the service principal to each workspace
CU utilization chart is emptyMetrics Workspace ID / Dataset ID not set, or service principal not added to the Metrics workspaceComplete Steps 6.3 and 7.4
Tenant settings not taking effectPropagation delayWait up to 15 minutes after changing tenant settings
Client secret expiredSecret exceeded its configured expirationCreate a new client secret (Step 3) and update Soterre PBI Analyzer