Azure Service Principle

Permissions for the azure service principle

This document specifies the exact permissions required for each service principal PAA uses. Granting more than the listed permissions is unnecessary. Granting less will cause partial or complete scan failures.

1. Azure Service Principal

Purpose

Used by Health Checks, Cost Intelligence, Change Monitor (drift detection), and the RBAC Audit. PAA uses this service principal to query Azure Resource Graph and the Azure Cost Management API.

Where to Configure

Settings > Azure

Credential model — certificate, not a standing secret

PAA authenticates to Azure Resource Manager with a certificate, not a long-lived client secret.

During onboarding you provide a temporary client secret. PAA uses it once to provision a certificate, then discards it.
The certificate’s private key is generated inside, and never leaves, PAA’s Key Vault. Only the public key is written to your app registration.
PAA rotates the certificate automatically on a rolling schedule — there is no standing credential to expire, leak, or rotate by hand.
You can revoke PAA’s access at any time by removing the certificate from the app registration or deleting the app registration entirely.

Provisioning and rotating that certificate requires a single, self-scoped Microsoft Graph write permission — Application.ReadWrite.OwnedBy — granted to the Azure service principal and scoped to the app registration PAA owns: its own, and only its own. It cannot read or modify any other application in your tenant. The ARM RBAC roles below (Reader, Cost Management Reader) are read-only and unchanged — the certificate model affects only how PAA authenticates, not what it can read.

Defender for Cloud (CSPM) integration: if you enable the optional Defender CSPM connector (Settings > Attack Paths), its service principal follows the same certificate model — temporary bootstrap secret, PAA-managed self-rotating certificate, and the same self-scoped Application.ReadWrite.OwnedBy grant. No standing secret in steady state.

Required Microsoft Graph permission (for self-managed certificate)

Permission	Access	Used For
`Application.ReadWrite.OwnedBy`	Write — self-scoped	Lets PAA manage only its own certificate credential (provision + auto-rotate) on the Azure service principal’s app registration. Cannot touch any other app registration.

This is granted + admin-consented by the onboarding script, which also sets the service principal as an owner of its own app registration (required for self-scoped certificate management). It is the only write permission the Azure service principal holds; everything else is ARM read access via the RBAC roles below.

Required Azure RBAC Roles

Assign these roles to the service principal on each subscription you want PAA to scan.

Role	Scope	Required For
Reader	Per subscription	All Health Check scanning (Resource Graph queries, resource health, tag compliance, encryption, storage security, naming, resource locks, network security)
Cost Management Reader	Per subscription	Cost Intelligence (spend data, trends, budgets, recommendations)

Both roles must be assigned at the subscription level (not resource group level) for Resource Graph cross-subscription queries to work correctly.

Minimum viable configuration: Reader only. Cost Intelligence will be unavailable without Cost Management Reader.

How to onboard (recommended: onboarding script)

PAA ships an onboarding script (Setup-PaaOnboarding.ps1) that performs every step idempotently — create the app registration, assign the ARM RBAC roles below on your subscriptions, grant + admin-consent the self-scoped Application.ReadWrite.OwnedBy permission, set the service principal as owner of its own app registration, and generate a short-lived (7-day) bootstrap secret.

Run the onboarding script as a user with Global Administrator (for the Graph consent + self-ownership) and Owner/User Access Administrator on the target subscriptions (for the RBAC assignments). It outputs the Application (client) ID, the temporary client secret, and your Directory (tenant) ID.
In PAA Settings > Azure, enter the Tenant ID, Client ID, and the temporary secret, then click Test Connection.
On the first scan (or credential save), PAA provisions a certificate in its Key Vault, registers the public key on the app, verifies certificate authentication, and discards the bootstrap secret. From this point all scanning uses the certificate.

Manual alternative

In Azure Portal, open Microsoft Entra ID > App Registrations > New Registration
Name it (e.g., paa-scanner) and register
Under API Permissions, add Microsoft Graph > Application permissions > Application.ReadWrite.OwnedBy, then Grant Admin Consent
Set the service principal as an owner of its own app registration (Overview > Owners) — required for self-scoped certificate management
Under Certificates & Secrets, create a new Client Secret with a short expiry. Note the value immediately — it is only shown once
Note the Application (client) ID and Directory (tenant) ID from the Overview page
In each target subscription, open Access Control (IAM) > Add Role Assignment
Assign Reader to the service principal
Repeat for Cost Management Reader on the same subscriptions
In PAA Settings > Azure, enter the Tenant ID, Client ID, and Client Secret, then click Test Connection. PAA replaces that secret with a managed, self-rotating certificate on first connect.

What PAA Does with This Service Principal

Scan Area	API Used	Permission Required
Resource health, orphaned resources, tags, encryption, locks, naming, storage security	Azure Resource Graph	Reader
Network security groups, firewall rules	Azure Resource Graph	Reader
Diagnostic settings audit	Azure Resource Graph	Reader
RBAC role assignments and custom roles	Azure Resource Graph (`AuthorizationResources`)	Reader
Management group hierarchy	Azure Resource Manager	Reader
Azure Policy compliance	Azure Resource Graph	Reader
Cost trends, spend breakdown, budgets	Azure Cost Management API	Cost Management Reader
Cost-based optimization recommendations	Azure Cost Management API	Cost Management Reader

Notes

The service principal’s ARM access is read-only — PAA does not make changes to your Azure environment. The only write permission it holds is the self-scoped Application.ReadWrite.OwnedBy, which manages only PAA’s own certificate credential and cannot touch any other application.
The durable credential is a certificate that PAA generates in its Key Vault and rotates automatically; the bootstrap secret you supply is discarded after first connect. There is no standing secret in steady state.
If a subscription uses the Free or Dev/Test offer type, the Cost Management API may return 404 for that subscription. This is an Azure limitation — Reader is still needed for Resource Graph scanning on that subscription.
Management group queries work across all subscriptions the service principal can read. If you want to limit scanning to specific subscriptions, configure this under Settings > Azure > Subscriptions to Scan.

Platform Architecture Authority — Crimson Owl Technologies Last updated: June 2026