Power BI Service Principal Setup: Complete Guide with Troubleshooting (2026)
If you're embedding Power BI reports in a production web application, storing a username and password is a security nightmare. The industry‑standard solution is a Service Principal (Microsoft Entra application). However, the setup often ends with a dreaded 403 Forbidden error—because 90% of failures happen in Entra ID or Power BI configuration, not in your C# code.
In this article, I'll walk you through every step: from App Registration and security groups to workspace permissions and REST API calls. More importantly, I'll address the real‑world issues that confuse developers: why doesn't my security group show up in Power BI?, why isn't my app under “Owned Applications”?, and how to fix the 403 Forbidden error once and for all.
Architecture Overview
Your application uses a Service Principal to authenticate against Microsoft Entra ID, obtain an access token, and call the Power BI REST API to generate an embed token. The browser then uses that embed token to render the report.
User Browser
│
▼
ASP.NET Core MVC (your app)
│
▼
Microsoft Entra ID (token endpoint)
│
▼
Service Principal (Client ID + Secret)
│
▼
Power BI REST API
│
▼
Power BI Workspace → Report / Dataset
Prerequisites
- An Azure subscription (even a free one works for testing).
- Access to Microsoft Entra ID (formerly Azure AD) with permissions to create App Registrations.
- Power BI Pro or Premium Per User license (or a Premium capacity workspace).
- Visual Studio or any IDE for the .NET code sample.
Step 1: Create the App Registration
- Go to Azure Portal → Microsoft Entra ID → App registrations.
- Click New registration.
- Name:
PowerBI-ERP - Supported account types: Accounts in this organizational directory only (Single tenant)
- Redirect URI: Leave blank (not needed for service principal auth).
- Name:
- Click Register.
Immediately copy the Application (client) ID and Directory (tenant) ID. Save them securely.
Step 2: Create a Client Secret
- Inside the App Registration, go to Certificates & secrets.
- Click New client secret, give it a description (e.g.,
ERP-Secret), and choose an expiration (24 months recommended). - Click Add and copy the Value immediately — it won't be shown again.
Step 3: Create a Security Group (Entra ID)
Many developers skip this step, but it's crucial for controlling which service principals can use Power BI APIs.
- In Microsoft Entra ID → Groups → New group.
- Group type: Security. Name:
PowerBI-SP-Group. - Click Create.
- Open the group → Members → Add members and search for
PowerBI-ERP(the name of your App Registration). Add it.
Step 4: Enable Service Principals in Power BI Admin Portal
- Open the Power BI Admin Portal.
- Go to Tenant settings → Developer settings → Allow service principals to use Power BI APIs.
- Toggle it to Enabled.
- Select Specific security groups and enter
PowerBI-SP-Group. - Click Apply.
Step 5: Add Service Principal to a Power BI Workspace
- In Power BI Service, open the target workspace (or create one, e.g.,
ERP Reports). - Go to Access → Add people or groups.
- Search for
PowerBI-ERP(the exact App Registration name). - Assign the role Admin or Member. (Contributor may not be enough for embedding in some scenarios.)
- Click Add.
❓ Why Doesn't My Security Group Show Up in Power BI?
This is the #1 question we get. If you can't find PowerBI-SP-Group in the tenant settings search, check these causes:
- It's not a Microsoft Entra ID security group. Distribution lists or Microsoft 365 groups won't work.
- Replication delay. New groups can take 5–30 minutes (sometimes longer) to appear. Wait and refresh.
- Searching by wrong name. Power BI uses the Display Name exactly. If you named the group "PowerBI SP Group" (with spaces) but search for "PowerBI-SP-Group", it won't find it.
- Tenant restrictions. Your admin might have limited which groups can be used in Power BI. Check the same tenant setting you enabled.
- You don't have permission to see the group. If you're not an owner or member of the group, it may not appear in search. Ask your Entra admin to verify.
❓ Why Doesn't My App Registration Appear Under “Owned Applications”?
This causes panic, but it's usually harmless.
- “Owned applications” shows only apps where you are listed as an owner. If someone else created the app, or ownership was removed, it won't appear there.
- It's still visible under “All applications”. That's perfectly normal. The app exists and works.
Fix: To make it appear under "Owned applications", go to Microsoft Entra ID → App registrations → (select your app) → Owners and add your account.
❓ Why Doesn't My App Registration Appear in Power BI Workspace Access?
Even after adding it via "Add people or groups", the name may not show up. Here's why:
- Service Principal not yet created. An App Registration automatically creates an Enterprise Application (service principal) in your tenant. If it's missing, verify you're in the correct tenant.
- Wrong tenant. A common mistake: you're logged into a different tenant in Azure Portal vs Power BI.
- Search indexing delay. Wait 10–15 minutes after creating the app registration and try again.
- Using a personal Power BI account. Service principals only work in organizational tenants, not personal workspaces.
Step 6: API Permissions – Do You Need to Configure Anything?
For service principal (client credentials) flow, you do not add delegated permissions; you use the .default scope. However, many developers mistakenly add Power BI API permissions and then panic about admin consent.
If you're using the client credentials grant (as we do later), the only scope required is https://analysis.windows.net/powerbi/api/.default. This implicitly grants all the Power BI permissions your app is allowed to have, based on the Application permissions configured in the API permissions tab. In most embedding scenarios, no explicit admin consent is needed because the tenant setting we enabled earlier handles it.
If you ever see an error like AADSTS65001 (consent missing), an admin must go to App registrations → API permissions → Grant admin consent for {tenant}.
Power BI REST API: Generate an Embed Token
Now we move to the code. In your .NET application, install these NuGet packages:
Install-Package Microsoft.PowerBI.Api Install-Package Microsoft.Identity.Client Install-Package Microsoft.Rest.ClientRuntime
Step 7: Acquire Access Token (Service Principal)
string tenantId = "YOUR_TENANT_ID";
string clientId = "YOUR_CLIENT_ID";
string clientSecret = "YOUR_CLIENT_SECRET";
var app = ConfidentialClientApplicationBuilder
.Create(clientId)
.WithClientSecret(clientSecret)
.WithAuthority($"https://login.microsoftonline.com/{tenantId}")
.Build();
var scopes = new[] { "https://analysis.windows.net/powerbi/api/.default" };
var authResult = await app.AcquireTokenForClient(scopes).ExecuteAsync();
string accessToken = authResult.AccessToken;Step 8: Create Power BI Client & Generate Embed Token
var tokenCredentials = new TokenCredentials(accessToken, "Bearer");
var client = new PowerBIClient(new Uri("https://api.powerbi.com/"), tokenCredentials);
// Get report details (optional)
var report = await client.Reports.GetReportInGroupAsync(workspaceId, reportId);
// Generate embed token
var tokenRequest = new GenerateTokenRequest(accessLevel: "View");
var embedToken = await client.Reports.GenerateTokenInGroupAsync(
workspaceId, reportId, tokenRequest);
// Return embed details to the frontend
return new
{
embedToken = embedToken.Token,
embedUrl = report.EmbedUrl,
reportId = report.Id,
expiration = embedToken.Expiration
};Step 9: Embed in JavaScript
const config = {
type: 'report',
tokenType: models.TokenType.Embed,
accessToken: embedToken,
embedUrl: embedUrl,
id: reportId,
permissions: models.Permissions.All,
viewMode: models.ViewMode.View
};
powerbi.embed(document.getElementById("reportContainer"), config);403 Forbidden – Ultimate Debugging Checklist
Before you even look at code, go through this table:
| Error | Likely Cause | Immediate Fix |
|---|---|---|
| 401 Unauthorized | Invalid/expired token | Re‑acquire token using correct client ID/secret |
| 403 Forbidden | Service Principal lacks workspace access | Add the SP (or its security group) to workspace as Admin/Member |
| 403 Forbidden | Tenant setting not enabled | Enable "Allow service principals to use Power BI APIs" |
| 404 Not Found | Wrong Workspace/Report ID | Verify GUIDs from Power BI URL |
| 400 Bad Request | Invalid embed token request | Check accessLevel (View/Edit) and dataset IDs |
Best Practices for Production
- Store Client Secret in Azure Key Vault or environment variables – never in source code.
- Rotate secrets before they expire and monitor expiry dates.
- Use least privilege: Assign the service principal only the roles it needs.
- Separate workspaces for Dev, UAT and Production.
- Log all REST API responses and correlation IDs for debugging.
- Implement token caching (MSAL handles this automatically).
Frequently Asked Questions
Q: Can I use a service principal with a free Power BI license?
No. Embedding for your organization requires either a Power BI Pro or Premium Per User (PPU) license, or the workspace must be backed by a Premium capacity.
Q: Do I need admin consent if I'm the global admin?
If you enabled the tenant setting for service principals, additional consent is usually not required for client credentials. However, if you added specific application permissions, you may need to click "Grant admin consent".
Q: How long does an embed token last?
By default, 1 hour. You can configure a different lifetime in the generate token request (up to embed token maximum allowed by your tenant).
Found this helpful? 🚀
Share this guide with your team. For more in‑depth tutorials on Power BI, Azure, and .NET, visit FreeLearning365.com and subscribe to our newsletter!
Happy embedding – and no more 403 nightmares!
0 Comments
thanks for your comments!