Michael Tall — Header
Engineer initiating a secure Fabric token request

Service Principals in Fabric: Stop 30 Day Token Failures for Engineers

Use a Microsoft Entra service principal when you need non-interactive, programmatic access to Microsoft Fabric APIs and data. Service principals are the identity of choice for CI/CD pipelines, backend services, scheduled jobs, data agents and Warehouse or SQL analytics endpoints. Getting one working reliably means four things: Entra app credentials, a tenant setting switched on, the right workspace or item permissions, and automated token renewal.

TL;DR:

  • Affirm that enabling tenant toggle and configuring scope to a security group are essential first steps for safe, scalable service principal deployment.
  • Confirm that app registration must include a client secret or certificate stored securely in Azure Key Vault, and avoid embedding secrets in code or config files.
  • Grant item-level permissions for production environments, and avoid broad workspace roles when restricting access to specific APIs or data sources.
  • Perform an explicit bootstrap API call, such as listing workspace items, to generate the control-plane token before using the service principal for dependent tasks.
  • Regularly renew tokens, rotate secrets via Key Vault, and implement monitoring and access reviews to maintain security and prevent silent failures.
Datataal
Build More Reliable Fabric Foundations
Datataal designs scalable Microsoft Fabric architectures that simplify reporting, strengthen governance, and support real-time business insights.

Explore Datataal

Table of Contents

Prerequisites before you start

Before touching Entra, confirm the tenant is ready. A Fabric tenant administrator must enable ‘Service principals can use Fabric APIs’ under Admin portal, Tenant settings, Developer settings, and this toggle can be scoped to a security group rather than the whole organisation. If your automation needs to call admin APIs, a second toggle for read-only or update admin APIs must be enabled separately, and support varies by endpoint, so check the individual API documentation before you build against it.

You will also need permission to register an application in Microsoft Entra, or a working relationship with whoever holds that permission.

  • Enable the Fabric API tenant toggle and scope it to a dedicated security group where possible.
  • Enable admin API access separately if your automation reads tenant-wide metadata.
  • Confirm capacity assignment and workspace model. Personal ‘My workspace’ areas are not supported for service-principal automation.
  • Line up Entra app registration rights or a named contact who can create the registration for you.

Register the app and secure its credentials

Once the tenant setting is live, move to Entra ID.

  1. Create a new app registration and give it a name that identifies its purpose, such as an automation account or pipeline name.
  2. Skip redirect URIs. Service principals never sign in interactively, so there is nothing for a redirect to catch.
  3. Generate a client secret or, better, a certificate, and copy the secret value immediately since it is shown only once.
  4. Record the Tenant ID and Application (client) ID alongside the secret or certificate thumbprint.
  5. Store all three values in Azure Key Vault rather than in code, configuration files or pipeline variables.

Certificates outlast secrets and pair well with app-management policies that enforce secret standards, which can cap certificate lifetimes at a fixed number of days for every app created after a set date.

Pro Tip: Name your Key Vault secrets after the service principal, not the project, so rotation scripts can find and refresh them without a lookup table.

Automated service principal secret rotation flow

Grant the right level of Fabric access

Registering the app gets you an identity. It does not get you access to anything in Fabric, and this is where most implementations either overshoot on risk or undershoot on function.

  • Workspace roles (Administrator, Member, Contributor) are the fastest route for development and testing, granting broad rights across everything in that workspace.
  • Item-level Execute permissions are the recommended production pattern for APIs such as GraphQL, since they limit the service principal to specific items rather than the whole workspace.
  • Warehouse and SQL analytics endpoints support service-principal authentication through either workspace roles or item permissions, and Microsoft recommends this pattern wherever no human is available to authenticate. Grant only the T-SQL data-plane rights the job actually needs.
  • Embedded and multitenant scenarios should use service-principal profiles mapped to individual customer workspaces, passed via the X-PowerBI-Profile-Id header rather than one shared identity across tenants.
  • Data agents need explicit access to every underlying data source they query. Sharing the agent itself with a service principal is not enough: the SPN must also hold rights on the source data, and skipping this step is a common cause of silent failures.

Workspace access and underlying data-source access are two separate permission layers, and both must be granted.

Getting a token and bootstrapping Fabric access

Authentication for a service principal follows the OAuth 2.0 client credentials flow, using the Fabric API scope rather than a delegated user scope, which is a common pattern explained in System Integration & API Development Zürich | Ampersand. In most SDKs, ClientSecretCredential (or its certificate equivalent) handles this exchange cleanly, passing tenant ID, client ID and secret to request an access token.

There is one-step teams routinely miss. The first public Fabric API call a service principal makes is what actually creates its Fabric control-plane token, and skipping this bootstrap leaves a correctly permissioned SPN failing against Warehouse or OneLake operations for no obvious reason. Automate an explicit bootstrap call, such as listing workspace items, before any dependent job runs.

  • Acquire a token with the client credentials grant against the Fabric API scope.
  • Make one lightweight, idempotent API call (a list-items call works well) to bootstrap the control-plane token.
  • Call your target endpoint, whether that is a GraphQL query, a Warehouse connection or an admin API read.
  • Renew the token well ahead of expiry and build in tolerance for clock skew between systems.

Fabric control-plane tokens carry a 30-day lifetime, so schedule renewal on a shorter cycle than that, rather than waiting for a failure to trigger it. Note that this is separate from OneLake user-delegation SAS tokens, which have a maximum lifetime of one hour and need their own tracking logic.

Running service principals safely in production

A working service principal is not the same as a safe one. Production operations need a handful of controls layered on top of the basic setup.

  • Store every secret in Azure Key Vault and automate rotation rather than relying on manual renewal.
  • Apply Entra appManagement policies to cap certificate and secret lifetimes, for example limiting certificates to 180 days.
  • Assign Conditional Access policies directly to the service principal, since group-scoped Conditional Access is not enforced for workload identities, and use these to restrict sign-in location or block detected risk.
  • Keep service principals in dedicated security groups rather than mixed with human accounts, so a single compromised credential has a contained blast radius.
  • Run automated authorisation tests and review sign-in logs periodically to catch permission drift before it causes an outage.

Pro Tip: Treat a service principal’s permission set as code. Review it in the same pull request as the pipeline that depends on it.

Quick fixes for common service principal failures

Most service-principal issues in Fabric trace back to one of four causes, and each has a fast diagnostic.

  1. Bootstrap never ran. If the SPN has correct permissions but Warehouse or OneLake calls still fail, run a simple list-items call first to initialise the control-plane token.
  2. Workspace access exists, data-source access does not. Check the underlying source, not just the workspace or agent, since these are separate permission layers.
  3. Admin API calls fail silently. Confirm the admin API tenant toggle is on and that the app has no permissions requiring admin consent.
  4. Interactive sign-in or notebook access fails. This is expected: service principals cannot open the Fabric portal, and some notebook and Git integration features remain unsupported for this identity type.

What most teams get wrong about service principal rollouts

Most Fabric service-principal problems are not authentication problems. They are permission-layering problems: teams grant workspace access, confirm the toggle is on, and assume the job is done, without realising that data-source access, admin API scope and the control-plane bootstrap are each separate gates requiring explicit setup.

A short rollout checklist covers most of it: enable the tenant toggle scoped to a security group, register the Entra app, wire secrets through Key Vault, run an explicit bootstrap call, grant least-privilege item permissions, then add monitoring. Where teams tend to need outside input is CI/CD workspace design, migrating multitenant embedding to profile-based service principals, integrating third-party engines with OneLake security, or a security review of Conditional Access coverage across existing SPNs. Our guide to CI/CD workspace strategy covers the first of these in more depth.

— Michael

How Datataal helps you put this into production

Setting the tenant toggle and registering an app is the easy part. Getting Warehouse permissions, token bootstrap and Conditional Access working together without breaking a CI/CD pipeline is where most teams lose time. Specialized consulting firms work directly with your team on Microsoft Fabric consulting, tenant-settings rollouts, workspace strategy and Azure Synapse to Fabric migration, with no junior staff or extra management layers between you and the person doing the work.

Datataal

If you are planning a service-principal rollout, a pilot implementation or a security review of your current setup, our Microsoft Fabric consulting services page covers scope and how engagements start.

Sources

FAQ

What is a service principal?

A service principal is a non-interactive Microsoft Entra identity that applications and scripts use to authenticate, instead of a human signing in. In Fabric, it is the standard identity for automation, backend services and scheduled jobs that call APIs without a person present.

Is Service Fabric deprecated?

Service Fabric is a separate Microsoft container orchestration platform and is not the same product as Microsoft Fabric, the analytics platform this article covers. The two share a name but nothing else, so deprecation status for one has no bearing on the other.

What is the difference between a service principal and an Entra ID?

Microsoft Entra ID is the identity platform itself, the directory that holds users, groups and applications. A service principal is one type of identity registered within Entra ID, specifically the non-human identity assigned to an application for automated access.

When should you use a service principal instead of a user account?

Use a service principal whenever a process runs without a person present, such as a CI/CD pipeline, a scheduled data refresh or a backend integration calling Fabric APIs. User accounts remain the right choice for interactive work inside the Fabric portal, since service principals cannot sign in there.

Microsoft Fabric blog