Overview
A Service principal is an application registered in Microsoft Entra ID that Azure Documenter uses to authenticate and access your Azure subscriptions, resource groups, and resources.
Business value
- Connect Azure Documenter to your subscriptions securely, without sharing user credentials
- Get proactive notice before a client secret expires, avoiding unexpected access failures
- Automatically extend access to new subscriptions through scope automation rules
Prerequisites
Required permissions
The Azure subscription for which documentation is generated must grant Reader access to the Service principal object in Microsoft Entra ID. Some document types require additional Azure RBAC roles beyond Reader. For the full breakdown of permissions required per document type, see Prerequisites.
Within Turbo360, only the following roles can add, edit, or delete a Service principal:
| Role | Access |
|---|---|
| Account owner, Owner, Contributor | Full access to add, edit, and delete Service principals |
How it works
Client secret expiry
Turbo360 lets you set the same expiry date as the Azure portal and notifies users 7 days before the client secret expires. The expiry date is set when adding or editing a Service principal. If the secret expires before renewal, Azure Documenter cannot authenticate to any subscription linked to that Service principal. Document generation stops for all associated document groups until you update the secret.
Scope automation
Azure Documenter can automatically define scopes for document groups using automation rules based on subscription names. When a Service principal gains access to a matching subscription, Azure Documenter automatically adds it to the matching document groups. Automation runs daily at 12:00 AM UTC. New subscriptions added between runs don't appear until the next cycle. If you need immediate access before the next run, update the scope manually through the Access policy screen.
Steps
Use the following steps to add, edit, or remove a Service principal, and to configure scope automation. Start from the Service principals section in Azure Documenter.
Add a Service principal
Adding a Service principal connects a new set of Azure subscriptions to Azure Documenter for document generation.
- Click Add, then enter the required Service principal information.
- Once validation succeeds, click Next.
- Choose the access policy: grant full access to all resource groups within a subscription, or limit access to a specific resource group.
- Choose the document group to grant access to the selected subscriptions.
- Optionally, enable the subscription checkbox and click Bulk selection to grant access for multiple subscriptions to similar document groups at once.
- Click Save.
Edit a Service principal
Editing lets you rotate the client secret and update its expiration date without recreating the Service principal.
- Click the Context menu ( ⋮ ) next to the Service principal.
- Select Edit.
- Update the Client secret and Client secret expiration date as needed. You can also manage the access policy for document groups and the automation rule for Azure subscriptions here.
Configure scope automation
Scope automation removes the need to manually grant access every time a Service principal is connected to a new subscription.
- Go to Service principals and Add or Edit the Service principal to configure automation for.
- Validate the credentials and proceed to the Access policy screen.
- Enable Apply the access policy across all new and existing subscriptions within the service principal to automatically grant root-level access to newly added subscriptions.
- To scope automation more precisely, select Configure rule > Add rule, then define a condition. Any subscription matching the rule gains access to the configured scope.
- Click Save, then Update to finish setting up the automation rules.
Delete a Service principal
Deleting a Service principal removes it from Azure Documenter and revokes its access to all document groups it was linked to. Any document configurations relying on this Service principal will stop generating until a new one is added.
- Click the Context menu ( ⋮ ) next to the Service principal.
- Select Delete.
Example scenario
Your team provisions a new Azure subscription for a staging environment and needs to add it to Azure Documenter immediately. Edit the Service principal in the Service principals section, navigate to the Access policy screen, and add the subscription to the staging document group. To avoid repeating this for future subscriptions, configure a scope automation rule. Any subscription whose name contains staging is automatically added to the matching document group at the next daily run at 12:00 AM UTC.
Troubleshooting
-
Service principal validation fails when adding
Cause: the Application (client) ID, Directory (tenant) ID, or client secret value is incorrect, or the client secret has expired.
Fix: verify all three values in the Azure portal under Microsoft Entra ID > App registrations > [your app] > Certificates & secrets. Ensure the secret value (not the secret ID) is entered, and that the secret has not expired. -
Client secret expires unexpectedly
Cause: the expiration date was not set or was set to a shorter period than intended, and no notification was acknowledged.
Fix: edit the Service principal to update the Client secret expiration date. Turbo360 notifies users 7 days before expiry; ensure notification channels are configured. -
Scope automation is not adding new subscriptions automatically
Cause: the automation rule condition does not match the subscription name, or the daily automation job at 12:00 AM UTC has not yet run.
Fix: review the rule condition in the Access policy screen. Check that the subscription name matches the rule exactly. Wait for the next daily automation run or manually update access in the interim. -
Newly added subscription is missing from document group after bulk selection
Cause: the subscription was not selected during the bulk selection step, or it was added to the Service principal after the bulk assignment was saved.
Fix: edit the Service principal, return to the Access policy screen, and add the missing subscription to the relevant document group.