Replace service principal profiles with service principals

If your solution uses service principal profiles (SPP) and their identity, governance, API, or operational limitations constrain your requirements, this guide helps you evaluate and implement a replacement based on dedicated Microsoft Entra service principals. If your existing profile-based solution meets your requirements, you can continue using it.

For customers choosing to migrate, this guide recommends managed identity and federated credentials where the hosting and trust requirements are met. Direct service principal authentication remains an alternative. Both paths provide dedicated customer identities for directory governance, independent sign-in monitoring, and access to supported services beyond profile-aware interfaces.

Why migrate from profiles

Consider replacing profiles when the following limitations constrain your solution:

• Profiles don't conform to Microsoft Entra ID best practices for governable workload identities. A profile has no representation in Microsoft Entra ID. It produces no independent sign-in logs, can't carry its own Conditional Access policy, and can't be governed by the tooling used for the rest of the identity estate.

For example, you can't configure a profile as the identity of a Direct Lake connection from a semantic model to a lakehouse or warehouse. Nor can you grant it access as an independent Microsoft Entra identity to other downstream services that the application or its workloads need to reach. A dedicated service principal can receive those permissions where the service supports it.

You can't use profiles with the Fabric REST APIs. Profiles are supported only by the profile-aware REST API, its .NET SDK, and supported XMLA/TOM interfaces. The Fabric REST APIs don't support profiles, and support isn't planned. Use a supported identity for those API calls instead of a profile. Creating a dedicated service principal addresses the identity requirement, but each API and operation must still support that identity and grant it the necessary permissions.

• Authentication remains tied to the parent identity. When the parent uses a secret or certificate, protect and rotate that credential. The recommended replacement pattern avoids stored customer application credentials. Profiles can also use a managed identity parent, so secretless authentication alone doesn't require replacing profiles. A managed identity parent doesn't give the profiles independent directory identities or broader API support.

Profiles solve a scale problem, not an independent-identity problem. One parent service principal can create up to 100,000 profiles, and each profile can access or create up to 1,000 workspaces. A service principal itself can belong to at most 1,000 workspaces in this model. Dedicated customer identities instead consume Microsoft Entra directory objects. Validate the applicable limits against your customer count before committing to the migration.

Other profile limitations to consider

The managed identity and federated credentials pattern

Use this pattern when you choose to replace profiles and your runtime meets the managed identity hosting requirements.

The pattern

Give each customer a real Microsoft Entra service principal and use the application's managed identity as an assertion source. This approach replaces both the shared application credential and the profile abstraction. You can log, govern, and consider each customer identity for workload identity Conditional Access, and it can call supported Fabric REST APIs.

This approach is the recommended migration path where its Azure hosting and trust requirements fit the solution. It removes stored customer application credentials and their rotation processes without changing where workspace and resource authorization is enforced.

The architecture shows the application's runtime operations, three customer application identities and trusts, and the one-to-one customer workspace relationships. It represents the default shared-runtime arrangement, not a new isolation boundary.

Figure 1. One application managed identity authenticates as dedicated customer service principals.

How it works

1. Application managed identity. Assign a user-assigned managed identity to the ISV application running on supported Azure compute, such as App Service, Container Apps, an appropriately configured AKS workload, or a virtual machine. Use one managed identity for the application, not one per customer. It has no customer workspace or target-service permissions of its own; its role here is only to provide an assertion.

2. Per-customer, user, or group service principals. For each existing customer or authorization boundary, create a Microsoft Entra application registration and service principal in the ISV's directory tenant. A logical customer doesn't necessarily mean a separate Microsoft Entra tenant, and an identity per end user isn't required unless the existing access design calls for it.

3. Federated identity credential. Configure a federated identity credential on each customer application registration to trust the application's managed identity. The runtime can then use its managed identity token as an assertion to obtain an access token for that customer application without a client secret or certificate.

4. Runtime token exchange. When user A or a customer-specific job invokes the application, resolve customer A through a trusted server-side mapping. Acquire the managed identity token with audience api://AzureADTokenExchange; exchange it for an access token as SP-A; then call the target APIs using SP-A's token to manage workspaces, perform resource operations, or request application-specific tokens where required.

   For the exchange in the preceding step, the .NET Azure Identity ClientAssertionCredential accepts the managed identity token as a client assertion. This is an Azure Identity credential type, not an MSAL class. The access token must target the resource API's audience, not the token-exchange audience.

5. Workspace access. Grant each service principal Member or Admin access only to its designated workspaces when those roles are needed, or the least-privileged supported role for the required operations. That grant scopes resource access. Because the application's managed identity can authenticate as every customer application that trusts it, treat it and its compute hosts as high-value identities and infrastructure.

Why this path is recommended

• Fewer long-lived credentials. You don't need to store, retrieve, or distribute any customer application secret or certificate private key to the runtime.

• Less rotation work. Azure manages the managed identity credentials and issues short-lived tokens. You don't need a separate secret or certificate renewal process for every customer application using this trust.

• Consistent onboarding. Provision a customer application and service principal, define the explicit trust, and grant customer resource access. New customers don't require new long-lived credentials.

These benefits don't remove the need for trust administration, customer authorization, audit monitoring, or directory capacity planning.

Alternative: Direct service principal authentication

If you don't want to use managed identity and federated credentials, create the same dedicated customer application registrations and service principals, but authenticate them directly with certificates or another supported application credential. Prefer certificates over client secrets where supported. Protect private keys and secrets, restrict access to them, and automate rotation.

Direct authentication retains directory visibility, per-principal sign-in logs, and access to supported APIs. It doesn't require the managed identity hosting or trust arrangement, but it doesn't eliminate stored customer credentials.

Key concepts

Distinguish the credential that establishes trust from the tokens used at runtime.

Federated identity credentials

Configure a federated identity credential (FIC) on the Microsoft Entra application registration that backs the customer service principal. It defines a trust relationship with a token issuer and specifies which assertion the application accepts instead of a client secret or certificate.

In this architecture, the target identity is the customer application and service principal; the application managed identity is the assertion source. This is why you configure the customer credential on the application registration rather than on the service principal object or the source managed identity.

When the application presents the managed identity token and requests an access token for the customer application, Microsoft Entra ID validates the assertion against the federated credential. The issuer, subject, and audience must match. If validation succeeds, it issues an access token representing the target customer service principal for the requested resource.

The managed identity and trusting application registration must be in the same Microsoft Entra tenant. The resource audience is a separate choice from the assertion audience. For Azure Identity, the global-cloud token-exchange scope is api://AzureADTokenExchange/.default; the target API scope is normally the resource identifier followed by /.default.

Token exchange flow: Client credentials with a federated assertion

This flow involves three participants and six steps. SP-A is customer A's application and service principal. The managed identity assertion token and the returned SP-A resource access token serve different purposes.

Figure 2. Client credentials token exchange backed by a managed identity assertion.

1. Request the managed identity token. The app on Azure requests a managed identity token with audience api://AzureADTokenExchange.

2. Return the assertion token. Microsoft Entra ID issues the managed identity token, which the app receives through its Azure hosting environment's managed identity mechanism.

3. Submit the customer token request. Send a request to the directory tenant's /oauth2/v2.0/token endpoint with grant_type=client_credentials, client_id=<SP-A-client-id>, client_assertion=<MI-token>, and scope=<target-resource>/.default. The complete OAuth request also supplies client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer; an identity library handles this parameter.

4. Validate the assertion. Microsoft Entra ID validates the managed identity token against the federated credential on SP-A's application registration.

5. Return the customer access token. Microsoft Entra ID returns an access token for SP-A with the target resource as its audience.

6. Call the target REST APIs. The app sends SP-A's access token to the target API. It doesn't use the assertion token as the resource bearer token and doesn't select a profile.

Architecture comparison

The replacement column covers dedicated service principals generally. Managed identity and federation are the recommended authentication method, but direct certificate or other supported credential authentication is also possible.

How to read this table: neither arrangement provides cryptographic isolation of customers. Resource grants enforce access, and the runtime might have indirect reach across customers. Profiles offer lightweight identity scale. Dedicated principals improve directory governance, sign-in visibility, and API compatibility. The recommended managed identity and federation path also removes stored customer application credentials.

Migration path

The following path replaces profiles with dedicated customer service principals. Keep migration and rollback decisions separate for each customer.

From profiles to managed identity and federated credentials

Use the following migration phases with a small pilot cohort and a per-customer rollout switch. Keep the profile route available until validation and the agreed rollback period are complete.

Phase 0: Create the application managed identity

• Create the user-assigned managed identity for the application and assign it to the compute resource. The implementation guide shows the creation and assignment commands.

• Record its principal (object) ID. Every customer application's federated credential uses this value as its subject. Also record the client ID, directory tenant ID, and Azure resource ID.

Use one managed identity for the application, not one per customer. A separate MI for every customer is unnecessary in this pattern: the customer identity is the service principal, and the MI supplies the assertion. For larger deployments or smaller compromise scope, partition customers across a small number of runtime identities, each trusted by only its assigned subset of customer applications.

Phase 1: Inventory

List all existing profiles through the profile-management API:

GET {profile-api-base}/v1.0/myorg/profiles

For each profile, record:

• Profile ID and display name, parent service principal, and customer mapping.

• Associated workspaces and role assignments.

• Associated semantic models or datasets, reports, and other resources.

• Connections, data-source credentials, ownership dependencies, background jobs, and API operations that depend on the profile.

Before changing a customer's configuration, record the existing workspace roles, semantic model ownership, connection identities, credential configuration, and customer-to-profile mapping needed for rollback. Record secure references to credentials, not secret values.

Record the total customer count and compare the required application and service principal objects with your Microsoft Entra directory-object quota before continuing. Validate the 1,000-workspace membership limit and any resource-specific limits as well. If the population exceeds a single directory's quota, plan a supported quota increase or deliberately managed multiple-directory design; it isn't solved automatically by this pattern.

Phase 2: Provision new identities

For each profile, or group of profiles belonging to the same customer authorization boundary:

1. Create an application registration and service principal. Record the application client ID, application object ID, and service principal object ID separately.

2. Configure a federated identity credential on the customer application registration that trusts the application MI created in Phase 0.

3. Grant the new service principal access to the same customer workspaces and resources. Use Member where the inventoried operations require it, or the least-privileged supported role. Grant Admin only when necessary.

Keep existing workspace and resource IDs wherever supported. A workspace grant doesn't automatically transfer resource ownership, connection identities, or data-source credentials. Complete those service-specific updates before cutover.

Phase 3: Update application code

• Replace the profile-selection header and SDK profile configuration with managed identity-backed token exchange for the selected customer application.

• Update the customer-to-identity mapping in your application database.

Customer IDs are logical identifiers of ISV customers, not necessarily Microsoft Entra tenant IDs. Validate the authenticated user's customer membership before selecting an identity. Key token caches by directory tenant, client ID, and resource or scope.

• Update application-specific token generation to use the customer service principal access token. If your solution embeds reports or other content, update that token generation as well; embedding is an existing workload to migrate, not a prerequisite for this guide.

• Update workspace management, downstream connections, provisioning, scheduled jobs, and every other entry point using the old profile configuration.

Phase 4: Validate

For each customer, verify:

• Workspace and resource access succeeds through the new service principal.

• Managed identity token acquisition and federated token exchange succeed for the intended customer application.

• Application-specific tokens are generated successfully where used, and existing reports or other embedded content render correctly where applicable.

• New service principal sign-ins appear in Microsoft Entra ID and can be correlated with application and resource audit logs.

• Cross-customer access is denied: a caller cannot select another customer's application identity or resource IDs.

Before production cutover, document and test the rollback procedure for a pilot customer. Include restoration of any semantic model ownership, connection identities, data-source credentials, and permissions changed during migration. Verify that the previous profile can perform its required operations after rollback, including refresh configuration and parameter updates.

Switch the customer's application route only after acceptance criteria pass. Monitor failures, performance, and permissions before expanding the rollout.

If validation fails, pause affected background jobs and restore the previous configuration by using the supported procedures for each service. Switching the application route back to the profile alone might not restore operations that depend on ownership or credentials. After restoring the required configuration, switch back to the profile-based route and verify resource access and dependent operations before resuming jobs. Retain the original profiles and required permissions throughout the rollback period.

Phase 5: Decommission profiles

• After the rollback period, remove obsolete original-parent and profile workspace grants, after confirming the dedicated customer service principals have the required access.

Delete each migrated profile through the profile-management API:

DELETE {profile-api-base}/v1.0/myorg/profiles/{profileId}

• Optionally delete the original shared application registration and service principal if no customer, job, or unrelated workload still uses them. Retire obsolete credentials and preserve migration mappings and audit records according to your retention requirements.

Implementation guide

This guide implements the recommended managed identity and federated credentials path. The direct-authentication alternative follows the same identity and permission setup and is described after the main steps. Azure CLI examples use Bash syntax; replace placeholders and sign in to the intended directory and subscription before running them.

Prerequisites

• An Azure subscription and permissions to create and assign managed identities for the recommended path.

• Permissions in Microsoft Entra ID to create application registrations and service principals and update application credentials. Azure resource permissions and directory permissions are separate.

• An application hosted on supported Azure compute such as App Service, Container Apps, an appropriately configured AKS workload, or a virtual machine. The MI-backed assertion source in this pattern depends on that Azure hosting configuration.

• Administrative permissions to grant customer workspace and resource access, configure required service settings, and grant API permissions or consent where the target service requires them.

• Azure CLI installed and signed in to the correct directory tenant. Confirm the subscription context before creating Azure resources.

Developer tenant settings

Review the relevant settings in your service's administration interface under tenant settings and developer settings. Scope service principal access to an allowed security group containing the customer service principals. For the exact labels and current behavior, see developer tenant settings.

For each group-scoped setting required by your solution, add every replacement customer service principal to an allowed security group before testing or cutover. Access granted to the original parent service principal doesn't automatically authorize the replacement principals. The public-API access setting applies to both the existing profile-aware REST APIs and the Fabric REST APIs; migrating only the identity doesn't remove this prerequisite.

The following public-API setting uses a product-neutral label; the administration interface might include the service's name.

Verify actual values instead of assuming defaults. New and existing tenants can differ, and administrators can change settings. Keep the profile setting until every dependent customer and job migrates. Don't enable embedding settings for a non-embedding workload.

Step 1: Create and assign the user-assigned managed identity

This managed identity represents the ISV application, not an individual customer. Use an existing resource group:

az identity create \
  --name "mi-customer-app" \
  --resource-group "<resource-group>" \
  --location "<azure-region>"

Record its client ID, principal (object) ID, directory tenant ID, and Azure resource ID. Assign it to the compute resource. For an existing App Service application:

az webapp identity assign \
  --resource-group "<resource-group>" \
  --name "<web-app-name>" \
  --identities "<managed-identity-resource-id>"

Use the corresponding identity assignment procedure for other compute services. Explicitly select this user-assigned identity in the runtime. Because the identity is independent of the host resource, redeploying a host doesn't need to replace every customer trust relationship.

Step 2: Create a service principal for each customer

For each customer, user, or group boundary that the existing profiles represent, create an application registration and its service principal. This example creates a single-tenant application in the ISV's directory:

APP_CLIENT_ID=$(az ad app create \
  --display-name "customer-a-application" \
  --sign-in-audience AzureADMyOrg \
  --query appId --output tsv)

az ad sp create --id "$APP_CLIENT_ID"

APP_OBJECT_ID=$(az ad app show \
  --id "$APP_CLIENT_ID" --query id --output tsv)

SP_OBJECT_ID=$(az ad sp show \
  --id "$APP_CLIENT_ID" --query id --output tsv)

Step 3: Configure federated identity credentials

Retrieve the managed identity principal ID and its directory tenant ID. Use the identity's tenant rather than assuming a different current subscription has the same tenant:

MI_PRINCIPAL_ID=$(az identity show \
  --name "mi-customer-app" \
  --resource-group "<resource-group>" \
  --query principalId --output tsv)

DIRECTORY_TENANT_ID=$(az identity show \
  --name "mi-customer-app" \
  --resource-group "<resource-group>" \
  --query tenantId --output tsv)

Add a federated identity credential to each customer application registration. The following global-cloud command uses the application object ID from Step 2 and the MI values just retrieved:

az ad app federated-credential create \
  --id "$APP_OBJECT_ID" \
  --parameters "{
    \"name\": \"trust-application-mi\",
    \"issuer\": \"https://login.microsoftonline.com/$DIRECTORY_TENANT_ID/v2.0\",
    \"subject\": \"$MI_PRINCIPAL_ID\",
    \"audiences\": [\"api://AzureADTokenExchange\"],
    \"description\": \"Trust the ISV application managed identity\"
  }"

Alternatively, save the same JSON with substituted values in a local credential.json file and pass --parameters credential.json. Repeat the trust on each customer application. Allow for configuration propagation before validating token exchange.

Step 4: Grant each service principal workspace access

Add the customer service principal as Member or Admin only to its designated workspaces where that role is required. Prefer a lower supported role if it meets the operation requirements. This grant is what actually scopes the customer's resource access.

Use the workspace administration interface or the workspace role-assignment REST operation. The following example uses configurable API and resource identifiers. It requires an authorized provisioning identity; the runtime MI itself isn't granted customer resource permissions for token exchange.

PROFILE_API_BASE="<existing-profile-aware-api-base-url>"
PROFILE_RESOURCE="<existing-api-resource-identifier>"
WORKSPACE_ID="<customer-workspace-id>"

TOKEN=$(az account get-access-token \
  --resource "$PROFILE_RESOURCE" \
  --query accessToken --output tsv)

curl --fail-with-body --request POST \
  "$PROFILE_API_BASE/v1.0/myorg/groups/$WORKSPACE_ID/users" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data "{
    \"identifier\": \"$SP_OBJECT_ID\",
    \"groupUserAccessRight\": \"Member\",
    \"principalType\": \"App\"
  }"

Use the endpoint and request shape documented for the service that owns the existing workspace. The displayed operation applies to the profile-aware workspace API; other APIs might use different role-assignment schemas. Don't substitute a client ID where the operation expects a service principal object ID. Avoid logging bearer tokens and allow for permission propagation.

Step 5: Authenticate and call APIs at runtime

1. Resolve the authenticated customer's application client ID and allowed resources from trusted server-side configuration.

2. Acquire an assertion token by using the selected user-assigned managed identity and the api://AzureADTokenExchange/.default scope in the global cloud.

3. Use the MI token as a client assertion for the customer application. Request an access token with the resource API's application scope, not the assertion audience.

4. Call the target API by using that customer application access token and without profile-selection configuration. Manage workspaces, request any required application-specific tokens, and perform other inventoried operations through the customer identity.

For .NET, use Azure Identity ClientAssertionCredential with the managed identity token as its assertion callback. The six-step flow and the official configuration examples show the exchange without requiring an embedding-specific application code sample.

Automate onboarding and offboarding

Wrap the four onboarding operations in your provisioning pipeline: create the application registration, create its service principal, configure its federated trust, and grant the workspace role. Build the matching offboarding path at the same time: remove resource grants, revoke obsolete trust or credentials, and delete application identities only after checking dependencies.

Alternative implementation: Authenticate service principals directly

If you don't want to use MI and federation, skip Steps 1 and 3. Complete Step 2 for each customer and configure a supported application credential instead of federated trust.

Use a certificate where supported and follow the application credential setup guidance. Upload the public certificate, protect the private key in an appropriate credential store, and automate renewal. If a client secret is necessary, protect it and renew it before expiry.

Complete Step 4 with the same least-privileged customer grants. In Step 5, use the customer client ID and its credential to request a client credentials access token directly. Keep the same customer routing, token cache separation, validation, and migration cleanup controls.

Security, limitations, and considerations

Apply the following controls to the authentication path you select, and plan for its operating limits.

Security recommendations

• Use a stable user-assigned managed identity. This avoids losing customer trust relationships merely because a compute resource is replaced. Do not use a system-assigned identity as the assertion source for this app-trust pattern.

• Treat the application MI as a highly privileged identity. It can authenticate as every customer application that trusts it. Restrict compute deployment rights, managed identity assignment, application owners, and credential administration. Partition runtime identities if needed to reduce compromise scope.

• Give the MI no customer service permissions of its own. It's an assertion source; customer service principals receive workspace and downstream service grants.

• Scope tenant settings with a security group. Include every relevant customer service principal in the allowed group instead of enabling service principal access for the entire organization.

• Monitor and alert on each service principal's sign-ins. Correlate with application and resource logs. Collecting logs without customer-specific investigation and alerting doesn't deliver the operational benefit.

• Automate onboarding and offboarding together. Removing workspace roles, retiring credentials or trusts, and deleting obsolete service principals must be as controlled and repeatable as provisioning them.

Keep customer mappings server-side, validate membership before selecting an identity, and reject arbitrary client-supplied identity or resource IDs. Token reuse means one sign-in record isn't a record of every API call. Don't log secrets, assertions, access tokens, or certificate private keys.

Limitations and operational requirements

Consult Microsoft Entra service limits and the target service's API identity support before finalizing capacity and permissions.

For current trust limits and propagation behavior, see federated identity credential considerations.

For current policy eligibility and licensing, see Conditional Access for workload identities.

Use the global-cloud token-exchange audience api://AzureADTokenExchange, the US Government audience api://AzureADTokenExchangeUSGov, or the China audience api://AzureADTokenExchangeChina, as appropriate. Match the authority endpoint to the cloud. The examples in this article use the global cloud.

Use supported identity libraries for token caching and refresh. Allow for trust and permission propagation, retry transient failures with bounded backoff, and investigate persistent issuer, subject, or audience mismatches. For direct authentication, rotate certificates and secrets with an overlap period and monitor expiry.

Don't assume that deleting a profile, removing a credential, or changing a trust instantly invalidates previously issued tokens. Account for token lifetime and each resource service's authorization and revocation behavior when planning cutover and offboarding.

Related content

Use these references for API-specific permissions, current identity restrictions, and existing workload configuration.

Profiles, service principals, and existing workloads

• Service principal profiles for multitenancy applications
• Configure an existing content application to use a service principal
• Developer tenant settings
• Existing analytics embedding overview
• Delegated-user Real-Time Dashboard embedding preview

Workload identity federation and managed identity

• Workload identity federation overview
• Important considerations and restrictions for federated identity credentials
• Configure an application to trust a managed identity
• Managed identities for Azure resources
• Federation configuration examples

SDKs, APIs, and service limits

• Azure Identity ClientAssertionCredential for .NET
• Application-specific token generation reference for existing embedding workloads
• Microsoft Entra service limits and restrictions
• Supported application identities for Fabric REST APIs
• Connection identity and Direct Lake security
• Conditional Access for workload identities
• Workspace role-assignment operation
• Profile-management API