Overview
Service principal permission errors occur when Azure Documenter cannot authenticate or retrieve data from Azure subscriptions due to misconfigured, expired, or insufficient Service principal credentials. These errors can surface during document configuration creation, on-demand generation, or on a scheduled generation run.
Business value
Service principal errors are among the most common causes of failed or incomplete document generation. A single expired or misconfigured Service principal can silently stop all configurations that use it. Resolving these errors quickly restores report continuity and prevents compliance or governance cycles from being broken by missing documents.
How it works
Azure Documenter uses a Service principal — an application registered in Microsoft Entra ID — to authenticate and retrieve data from your Azure subscriptions. The Service principal must hold the Reader role on each subscription it accesses. Errors occur when credentials are entered incorrectly, when the client secret expires, when the role assignment is removed, or when the Service principal is deleted or disabled in Microsoft Entra ID. Turbo360 notifies account owners 7 days before the client secret expires. Unacknowledged expiry warnings result in all configurations using that Service principal failing silently at their next scheduled run.
Troubleshooting
-
Service principal validation fails when adding it in Azure Documenter
Cause: the Application (client) ID, Directory (tenant) ID, or client secret value entered is incorrect. A common mistake is entering the secret ID instead of the secret value.
Fix: in the Azure portal, navigate to Microsoft Entra ID > App registrations > [your app] > Certificates & secrets. Copy the Value column (not the ID column) for the active secret and re-enter it in Azure Documenter. Confirm the Application (client) ID and Directory (tenant) ID are also taken from the app registration's Overview page. -
Document generation fails after a period of working correctly
Cause: the client secret for the Service principal used in the configuration has reached its expiry date. Once expired, Azure Documenter can no longer authenticate to retrieve subscription data, and all configurations that use that Service principal stop generating.
Fix: in Azure Documenter, navigate to Service principals, locate the affected Service principal, click the Context menu ( ⋮ ), and select Edit. Rotate the client secret in the Azure portal, then enter the new secret value and update the Client secret expiration date in Azure Documenter. See Managing service principals. -
Subscriptions do not appear in the Service principal step of the Add configuration wizard
Cause: the Service principal has not been granted the Reader role on the target subscription in the Azure portal, or the subscription belongs to a different tenant from the Service principal's app registration.
Fix: in the Azure portal, assign the Reader role to the Service principal at the subscription level. Allow a few minutes for the role assignment to propagate, then return to the Add configuration wizard and reselect the Service principal. See Prerequisites for the required role assignment steps. -
Generated document includes some subscriptions but is missing data for others
Cause: the Service principal holds Reader access on some subscriptions but not all subscriptions included in the configuration. Azure Documenter generates with the data it can access and silently omits subscriptions it cannot reach.
Fix: in the Azure portal, verify the Reader role assignment for the Service principal against every subscription included in the configuration. Add any missing role assignments, then regenerate the document. Compare the subscription list in the generation output against the list in the configuration's Service principal step to confirm coverage. -
All configurations using a Service principal stop generating simultaneously
Cause: the Service principal was deleted from Microsoft Entra ID, the associated app registration was removed, or the Service principal was disabled. Any configuration that references the removed Service principal cannot generate until a replacement is assigned.
Fix: register a new application in Microsoft Entra ID and add it to Azure Documenter as a new Service principal with Reader access on the required subscriptions. Edit each affected configuration, navigate to the Service principal step, and select the new Service principal. See Managing service principals. -
Microsoft 365 document types fail or return incomplete data
Cause: the document type being generated is one of License consumption, License optimizations, or Service plan matrix — these require additional Microsoft Entra ID application permissions beyond the standard Reader role. If Organization.Read.All or User.Read.All is missing, or if tenant-wide admin consent has not been granted, generation fails or produces empty output.
Fix: in the Azure portal, navigate to Microsoft Entra ID > App registrations > [your app] > API permissions. Add Organization.Read.All and User.Read.All as application permissions and have an administrator grant tenant-wide admin consent for both. Regenerate the document once consent is confirmed.