Two permission layers
Azure and Power BI check permissions in two separate layers. Understanding the split explains almost every failed Power BI setup.
Power BI authorization has two independent layers, and the gap between them is the root cause of most failed setups.
Layer 1 authenticates. Layer 2 authorizes.
Think of it like entering an office building:
- Layer 1, Microsoft Entra ID (Azure AD) is the front desk. It checks your app's ID badge (client ID + secret) and issues a visitor pass (an access token). This is what Atlan's Test Authentication button checks, and only this.
- Layer 2, Power BI tenant settings are the locked doors inside. Even with a valid visitor pass, each API family has its own door, opened by a specific tenant setting scoped to a security group. This is what Atlan's preflight checks validate. One family, the Fabric API, also checks your role on the item behind the door: the setting opens the floor, the workspace role unlocks the office.
Atlan reads from three Microsoft API families. They fail independently, and your egress or private-link policy needs both hostnames:
| API family | Endpoint | Opened by | Atlan uses it for |
|---|---|---|---|
| Admin and scanner APIs | api.powerbi.com | "Service principals can access read-only admin APIs" (+ the two "Enhance admin APIs responses" settings) | Tenant-wide discovery, DAX and Power Query expressions |
| Power BI REST API | api.powerbi.com | "Service principals can call Fabric public APIs" | Workspace listing, report pages, dataset parameters |
| Fabric API | api.fabric.microsoft.com | The same setting, plus Contributor or higher on the workspace | Report definitions, the source of column and measure to page lineage |
A Viewer role passes every tenant-setting check and still produces no column and measure lineage, because only the Fabric API asks for more than the setting. See Configure tenant settings.
"Test Authentication succeeded, so credentials are fine," no. Test Authentication only proves the front desk issued a token (Layer 1). A 401 PowerBINotAuthorizedException right after a successful auth test means a Layer 2 door is closed: a tenant setting is off, or the service principal isn't in the security group the setting is scoped to.
Full path, drawn once
All traffic is outbound HTTPS from Atlan to Microsoft; no inbound connection is made to your network. Access is determined by the service principal's membership in the security group that scopes each Power BI tenant setting.
Security group is hinge
Every Power BI tenant setting is scoped to a security group, and workspace access is best granted to that same group. If the service principal isn't actually a member of the group, every setting can be ON and you still get 401s. Recurring gotchas:
- What you add to the group is the app registration's Enterprise Application object (that's what "service principal" means in Azure), a recurring point of confusion for Azure admins.
- Nested groups may not propagate, add the service principal to the scoped group directly.
- Setting and group changes take 15-30 minutes to propagate. Re-testing 30 seconds after a change proves nothing.
See also
The connectivity and identity terms used across these guides, such as app registration, service principal, client secret (Value vs Secret ID), tenant settings, admin APIs vs Fabric public APIs, and Scanner API mode, are defined in the network connectivity glossary.
Operational terms are explained where they're used:
- Preflight checks and crawler vs miner, in Crawl Microsoft Power BI.
- Circuit breaker, in Operating it day to day.