Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Service principal profiles are an optional solution for Power BI Embedded multitenancy applications. They provide lightweight customer profiles and support large numbers of customer workspaces without requiring a separate Microsoft Entra application registration for each customer.
For new multitenancy solutions, we recommend dedicated customer service principals, authenticated through managed identity and federated identity credentials where the hosting and trust requirements are met.
Profiles remain a valid alternative for new and existing applications whose requirements fit their capabilities. They aren't deprecated. Existing applications that are satisfied with profiles can continue using them. This article explains their advantages, limitations, and high-level configuration. For API examples, see the detailed profile guide.
Where service principal profiles fit
Consider profiles when your application uses their supported interfaces, benefits from their scaling and administration model, and can accept their identity and operational limitations. A customer is a logical customer of your application, not necessarily a separate Microsoft Entra tenant.
| Advantage | What it means for your solution |
|---|---|
| Lightweight customer contexts | Create profiles under one parent without a separate application registration and service principal for each customer. |
| Supported workspace scale | A parent can create up to 100,000 profiles, each with access to up to 1,000 workspaces. Evaluate the applicable resource and capacity limits as well. |
| Automated lifecycle | Create and manage profiles and provision customer content through supported REST APIs. |
| Customer-scoped content administration | Use the customer profile to manage workspace permissions, semantic model ownership, and data-source credentials. Correct application routing and permissions remain essential. |
Profiles can reduce per-customer directory provisioning but still require application lifecycle automation. A small application might not need their scale model. If your application already uses dedicated principals and meets its requirements, there's no need to switch to profiles.
Limitations and trade-offs
Evaluate these constraints alongside the advantages:
- Profiles aren't independent Microsoft Entra identities and don't produce independent per-customer Entra sign-in records.
- Profiles can't receive workload identity Conditional Access policies or downstream-service permissions as independent Entra identities.
- Profiles don't support Fabric REST APIs. Check the supported interfaces and scale limits.
- Profiles remain bound to their creating parent and have API-only administration.
- The parent can act through any of its profiles. Profiles don't create cryptographic customer isolation.
For the full restrictions, see Identity and API limitations. Dedicated principals also require directory capacity planning and lifecycle management; neither identity model replaces resource permissions or secure customer routing.
Separate customer workspaces and semantic models can improve capacity management in either identity model. Those benefits don't require profiles. If an existing profile-based application needs capabilities outside the profile model, see Replace service principal profiles with service principals.
How the profile model works
The application's parent service principal creates a profile for each customer authorization boundary. The application maps an authenticated customer to the correct profile and its permitted workspaces and content.
For profile-scoped REST calls, use the parent's Microsoft Entra access token and the X-PowerBI-Profile-Id header. The profile selects the customer context; it isn't a separate Entra access token. See Profile permissions.
Prerequisites
After selecting the profile model, review the detailed configuration guide.
You also need to do the following steps:
- Configure the parent service principal's authentication and required tenant settings. See service principal setup or the managed identity parent option. Protect and rotate any stored secrets or certificates used by your chosen authentication method.
- From a Power BI tenant admin account, enable creating profiles in the tenant.
Configure a profile-based solution
If you choose profiles, configure the customer context, resources, and application requests:
- Create customer profiles.
- Organize customer workspaces and content.
- Configure profile-aware application requests.
- Validate customer access and operations.
Create customer profiles
Use the Profiles REST API with the parent service principal to create a profile for each customer authorization boundary.
Store the customer-to-profile mapping in trusted server-side configuration. Validate customer membership before selecting a profile or resource; don't accept arbitrary profile IDs from the client.
Organize your workspaces
The easiest way to manage your data is by maintaining one workspace per customer. If your app already uses this model, you don't need to create new workspaces. However, you still have to provide each profile with Admin access to the corresponding workspace using the Add Group User API.
If you don't have one workspace per customer, use the corresponding profile to call the Create Group API to create a new workspace for each customer.
Organize items in workspaces
After creating or assigning customer workspaces, import reports and semantic models where needed. Keep existing content where the chosen design supports it. Choose the semantic model and data-source design for your requirements:
If your app uses a separate semantic model for each customer, the semantic model design can work as it is.
If your design benefits from separate models, configure a semantic model for each customer. Evaluate capacity, refresh, and administration costs rather than assuming that profiles alone improve every application's scalability.
If your design uses row-level security (RLS), validate the effective identity and roles supplied during embed-token generation, including the expected
UserName()result for dynamic RLS and role selection for static RLS. You can use RLS within a customer's semantic model to separate access among its users.
Once the items are ready, import them into the relevant workspaces. To automate the process, consider using the Import API.
For an existing semantic model that the customer profile needs to administer through owner-only operations, ensure that the profile owns the model. Where supported, use the Take Over In Group API as that profile to transfer ownership. Configure the required connection identities and data-source credentials before switching those operations to the profile. Workspace Admin access alone doesn't transfer ownership or configure those settings.
Profile-aware application requests
Use the mapped customer profile consistently for supported customer operations:
- Authentication and profile selection: Obtain the parent's access token through its configured authentication method. Select the customer profile by using the profile header or SDK profile configuration. A profile uses the parent's token; don't treat a profile ID as an Entra principal ID.
- Customer provisioning: Create a customer profile and use it to create and administer the customer's workspace and content. Automate imports, connection configuration, and lifecycle changes where required.
- Embed-token generation: Use the intended customer profile context to call the GenerateToken API. Scope the request to the customer's permitted content and provide the required RLS effective identity and roles where applicable. The parent can act through its profiles; a profile isn't an independent security boundary.
Validate customer access
Test the chosen configuration before production use:
- Verify that each authenticated customer selects only its assigned profile and permitted resources. Test denied cross-customer requests as well as successful requests.
- Verify customer workspace access, embed-token scope, report rendering, and applicable RLS behavior.
- Verify semantic model ownership, connection identities, data-source credentials, parameter updates, and scheduled refresh.
- Review resource activity logs and parent-identity sign-in monitoring. Profiles don't create independent per-customer Entra sign-ins.
- Automate customer offboarding and check for jobs or content that still depend on a profile before removing its access or deleting it.
Note
If you reconfigure an existing application, keep the previous code path and required permissions available during a pilot rollout and rollback period. Existing broad permissions can mask incorrect customer routing even when reports render successfully. Record and test restoration of changed ownership, connections, credentials, and permissions before retiring the old configuration. Remove obsolete code, workspaces, and grants only after checking dependencies.