Overview
Access details - By subscription is a document type in Azure Documenter that reports the access granted within Azure Active Directory groups, users, and service principals, organized by subscription and optionally by resource group. It outlines their respective roles at the subscription and resource group levels.
Business value
Access details - By subscription gives administrators and security teams a consolidated, subscription-organized view of who has access to what across their Azure environment, reducing the manual effort needed for access reviews and compliance audits.
Prerequisites
To generate this document, the app registration must have the following Application permissions configured in Microsoft Entra ID:
User.Read.All— required to read user profiles and their role assignmentsGroup.Read.All— required to read Azure Active Directory group memberships and their role assignments
These must be granted as Application permissions (not delegated), and a tenant administrator must grant tenant-wide admin consent before they take effect. For the complete list of permissions required across all document types, see Managing service principals in Azure Documenter.
Required permissions
| Role | Permission level | Access |
|---|---|---|
| Account owner, Owner, Contributor | — | Full access to the Documentation section |
| Custom role | Read | View documents generated under Documentation |
| Custom role | Manage | View, generate, and manage documents under Documentation |
How it works
The Access details - By subscription document organizes identity and role information by subscription. For each subscription, it lists the users, AD groups, and service principals with their assigned roles. You can optionally include resource group-level breakdown to see role assignments at a finer scope. The document always includes an overall summary of the subscription(s) and their access at the AD group, service principal, and user level.
Steps
Use the following steps to generate an Access details - By subscription document. Navigate to Azure Documenter to get started.
- Click New configuration. The Configure your document wizard opens.
- In Step 1 — Basics, enter a configuration name. Under Choose document type, select Access details - By subscription. Configure the following options:
- Include resource groups — when enabled, includes resource group-level role assignments for each subscription
- Scope — filters the report to a specific scope: All, Subscription, Resource group, or Resource
- Role — filters the report to a specific role type: All, Built-in role, or Custom role
- In Step 2 — Service principal, select the service principal and configure the subscription scope. Click Next.
- Complete Steps 3–6 (Branding, Publish settings, Schedule, Notifications) as required. Click Next after each step.
- In Step 7 — Review, confirm your configuration and click Finish.
Once generation is complete, a URL is created for the document, and you can download it using the Download link.
Example scenario
Contoso's security team needs to review which users, AD groups, and service principals have access to their Production subscription ahead of a quarterly compliance audit. They generate an Access details - By subscription document, giving auditors a single report listing every identity and its role organized by subscription.
Troubleshooting
-
Access details document returns no data
Cause: no users, groups, or service principals have role assignments within the selected subscription scope, or the service principal lacks the required Microsoft Graph API permissions.
Fix: verify the service principal hasUser.Read.AllandGroup.Read.AllApplication permissions with tenant-wide admin consent, and that role assignments exist in the selected subscriptions. -
Document generation fails or returns incomplete data
Cause: the service principal is missing theUser.Read.AllorGroup.Read.AllApplication permission, or tenant-wide admin consent has not been granted.
Fix: grant both permissions to the app registration in Microsoft Entra ID and ensure a tenant administrator provides admin consent. See Managing service principals in Azure Documenter for the full permissions reference. -
Role filter returns fewer identities than expected
Cause: the Role filter is restricting the output to Built-in role or Custom role only.
Fix: set Role to All in Step 1 — Basics to include all role assignment types.
FAQs
-
Who can access the Documentation section by default?
Account owner, Owner, and Contributor roles have full access by default — no additional configuration is required. -
What's the difference between Read and Manage for Documentation?
Read lets a user view documents generated under Document Types. Manage lets a user view, generate, and manage them. -
Why does the service principal need Microsoft Graph API permissions for this document?
The Access details - By subscription document reads Active Directory group, user, and service principal role assignments, which requires theUser.Read.AllandGroup.Read.AllApplication permissions on the app registration.