What it does

The plumbing behind a custom embedded application: a Microsoft Entra identity that talks to the Power BI REST APIs, an embed token that scopes what the browser is allowed to render, and the JavaScript client library that hosts the iframe and raises events back to your page.

Key facts

• Service principal auth uses a Microsoft Entra app's application ID plus either a certificate or a client secret. Microsoft recommends certificates over secrets for back-end services.
• A Microsoft Entra app created for a service principal needs no delegated or application permissions configured. Microsoft explicitly advises against adding them — they're never used and produce errors that are hard to diagnose.
• Two tenant settings gate the whole thing, both under Developer settings in the admin portal: Embed content in apps and Allow service principals to use Power BI APIs. Scope them to a security group rather than the whole organisation.
• The service principal, or a security group containing it, must be added to each workspace as Member or Admin. Nothing works until that's done.
• Service principals can't be used with My workspace, can't sign in to the Power BI portal, can't manage dataflows, and can't be used in embed-for-your-organisation applications.
• Row-level security in app-owns-data comes from the EffectiveIdentity object passed when generating the embed token. USERPRINCIPALNAME() and USERNAME() return the service principal's application ID or an empty string, so per-user dynamic RLS based on those functions doesn't filter anything.
• GenerateToken fails with an effective identity if the model doesn't support effective identity, or if username, role or DatasetId are missing. Check IsEffectiveIdentityRequired and IsEffectiveIdentityRolesRequired on the semantic model.
• Access tokens — both Entra tokens and embed tokens — expire. You have to monitor and refresh them from the client; there's no automatic renewal.
• A data source holds one set of credentials per master user. Different credentials against the same source means more master users.

When to use / skip

Use a service principal for any production app-owns-data solution. Master users exist because service principals didn't always work, and they carry a password, an MFA problem, a licence, and a person who eventually leaves. The only reasons to keep a master user are the documented gaps — dataflow management, or a data source that needs a real user context. For internal apps where everybody already signs in, don't build any of this: embed-for-organisation uses the user's own token and skips embed tokens entirely.

Configuration decisions

• Certificate or secret for the service principal, and where the secret or cert lives — Key Vault, managed identity, or somewhere you'll regret.
• Whether the tenant settings are scoped to a dedicated security group for embedding service principals, or opened to the organisation. Service principals get every tenant setting they're enabled for, so scope tightly.
• Whether workspace access is granted to the service principal directly or to a group containing it. The group is easier to maintain; the exception is Azure Analysis Services sources, where the principal itself needs the instance permission.
• Embed token lifetime and the client-side refresh strategy, including what the user sees while a token renews.
• How your application's own user identity maps onto EffectiveIdentity — username, roles, and CustomData if the model uses CUSTOMDATA().

Gotchas

• Adding API permissions to the Entra app is the classic self-inflicted wound. It looks like the responsible thing to do and it breaks scanning and admin API calls in ways the error messages don't explain.
• LoadReportFailed with "Fail to initialize - Couldn't resolve cluster" and a 403 usually means the token type doesn't match the embed type — an Entra token where an embed token was expected, or the reverse.
• A 401 in the user-owns-data scenario that resolves itself once the user visits powerbi.com is a permissions cache issue. Call RefreshUserPermissions in the app rather than telling users to go and log in somewhere else.
• Guest users need the tenant ID in authorityUri. The /common/v2.0 endpoint won't resolve a B2B guest correctly.
• Testing RLS in the service with Test as role doesn't simulate embedded auth at all. You have to test with a real embed token carrying EffectiveIdentity.
• Log the RequestId header from failed API responses. Microsoft support will ask for it, and without it you're describing symptoms.

Consultant notes

• The Entra app registration, the security group and the tenant setting changes all need someone with tenant-level rights. Get those three items on the client's change calendar in week one — they're the usual reason an embedded project slips.
• Push for certificate auth and a documented rotation process. A client secret with a two-year expiry is a production outage with a delivery date.
• Build the effective identity mapping as a deliberate piece of design with the client's security lead, and write down what happens when the mapping table has no row for a user. "They see nothing" is a valid answer; "they see everything" is a breach.
• Keep the embedded analytics playground bookmarked. Reproducing a rendering problem there is the fastest way to prove the issue is your app rather than Power BI.

---

Worth revisiting when the service principal limitation list changes, or if certificate-based auth becomes the default guidance rather than the recommendation.