Overview
Subscription scope strategy refers to how you assign Azure subscriptions to document configurations in Azure Documenter. The Service principal step of the Configure your document wizard determines which subscriptions each configuration covers and which Azure resources are included in the generated document.
Business value
A deliberate subscription scope strategy prevents reports from mixing unrelated environments, ensures each report has a clear owner and purpose, and keeps Service principal permissions to the minimum required. Well-scoped configurations are easier to audit, faster to generate, and more actionable for the teams that consume them.
How it works
Each document configuration uses a single Service principal to access one or more Azure subscriptions. The Service principal must have Reader access to every subscription you include. You select the Service principal and its associated subscriptions in the Service principal step of the Configure your document wizard.
Azure Documenter generates the report across all subscriptions included in a configuration. The scope you define here shapes the entire document — what resources appear, what costs are reported, and what compliance findings are surfaced.
Separate production and non-production environments
Create separate configurations for production and non-production subscriptions. Mixing environments in a single report makes it difficult to isolate findings and assign accountability. Separate configurations also let you apply different schedules, publish destinations, and notification recipients for each environment.
Recommended pattern:
Security compliance – Production— covers production subscriptions onlySecurity compliance – Dev/Test— covers development and test subscriptions only
Use a dedicated Service principal per environment tier
Use a Service principal scoped to production subscriptions for production configurations, and a separate Service principal for non-production configurations. This limits exposure if credentials are compromised and makes permission audits more straightforward.
For cross-environment reports — for example, a consolidated executive summary across all environments — use a dedicated Service principal with Reader access to all relevant subscriptions, and restrict it to that configuration only.
Include only the subscriptions relevant to the report's purpose
Include only the subscriptions relevant to the report's audience and purpose. A Billing details report for a single business unit should cover only that unit's subscriptions, not the entire organization's subscription estate.
Narrower scope produces faster generation times and a more focused document. Stakeholders are more likely to act on findings when the report reflects their area of responsibility.
Use Bulk scope selection for large subscription sets
When a configuration needs to cover many subscriptions, use the Bulk scope selection option in the Service principal step. Bulk scope selection applies filters across multiple subscriptions at once, which is more reliable than selecting subscriptions individually and reduces the risk of accidental inclusions or omissions.
Align configuration scope with reporting ownership
Each configuration should have a clear owner — a team or individual responsible for acting on the report's findings. Align the subscription scope with that owner's area of responsibility. A configuration scoped to subscriptions owned by the networking team should be delivered to and reviewed by the networking team.
Ownership alignment also simplifies notification routing. In the Notifications step, configure the recipient email to go directly to the team responsible for the subscriptions in scope, not a generic distribution list.
Validate Service principal access before creating a configuration
Confirm that the Service principal has Reader access to every subscription you plan to include before starting the Configure your document wizard. Subscriptions the Service principal cannot access will not appear in the Service principal step. Missing subscriptions produce a report that covers fewer resources than intended, without any explicit warning.
See Service principal setup for guidance on assigning the correct access level.