Skip to content

Azure Permissions Required

CertifyClouds requires specific Azure permissions to discover and scan Key Vaults across your subscriptions. This document outlines the minimum required permissions for secure operation.

Quick Summary

Minimum Required Role: Reader at the Subscription scope

What CertifyClouds Can Access:

  • List subscriptions
  • List Key Vaults
  • Read Key Vault configuration (network, policies, RBAC)
  • Read secret/key/certificate metadata (names, expiry dates)

What CertifyClouds CANNOT Access with the minimum (Discovery) role:

  • Secret values
  • Private key material
  • Certificate private keys
  • Modify any resources
  • Delete any resources

PRO Rotation and full-stack rotation add narrowly scoped write and certificate-read permissions, detailed below.

Automated Setup

Use the provided setup script to automatically configure Key Vault permissions:

Prerequisites

Run the setup script as an operator who is signed in with az login and holds Owner or User Access Administrator on the target subscriptions (required to assign roles). You do not need to pre-grant the managed identity any role; with --apply, the script grants Reader at the subscription scope (plus the Key Vault roles) to the managed identity for you.

First, get the managed identity's Principal ID to pass to the script:

# Get your Managed Identity's Principal ID
PRINCIPAL_ID=$(az vm show --resource-group <rg> --name <vm> --query identity.principalId -o tsv)

Using a user-assigned managed identity

If you deployed with --user-assigned-identity (see Installation), use that identity's Principal ID, not a system-assigned one, and get it from the identity resource:

PRINCIPAL_ID=$(az identity show --ids <identity-resource-id> --query principalId -o tsv)

A user-assigned identity must also hold AcrPull on your Container Registry so the deployment can pull the image. The deploy script attempts this grant, but if your identities are provisioned centrally, grant it ahead of time.

Least-privilege operators

If the operator running the script lacks role-assignment rights, the script warns and continues rather than failing, because it cannot grant Reader itself. In that case, have someone with Owner or User Access Administrator grant Reader to the managed identity on each subscription beforehand:

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Reader" \
  --scope /subscriptions/<subscription-id>

Run the Setup Script

# 1. Check current permissions (dry run)
./setup-certifyclouds-access.sh --principal-id $PRINCIPAL_ID

# 2. Apply read permissions for Discovery scanning
./setup-certifyclouds-access.sh --principal-id $PRINCIPAL_ID --apply

# 3. (Optional) Enable Rotation write permissions (PRO tier)
./setup-certifyclouds-access.sh --principal-id $PRINCIPAL_ID --apply --pro

# 4. (Optional) Add subnet to Key Vault firewalls
./setup-certifyclouds-access.sh --principal-id $PRINCIPAL_ID --apply --subnet-id /subscriptions/.../subnets/snet-certifyclouds

The script will:

  • Discover all subscriptions visible to your signed-in az session (narrow with --subscription <id>)
  • Find all Key Vaults across those subscriptions
  • Auto-detect whether each vault uses RBAC or Access Policies
  • Check existing permissions and report any gaps
  • Apply missing permissions when --apply is specified

Authentication Methods

Best for: Azure VMs, Container Instances, AKS, Container Apps

# Enable system-assigned managed identity on your VM
az vm identity assign \
  --resource-group rg-certifyclouds \
  --name vm-certifyclouds

# Get the identity principal ID
IDENTITY_ID=$(az vm show \
  --resource-group rg-certifyclouds \
  --name vm-certifyclouds \
  --query identity.principalId -o tsv)

# Assign Reader role at subscription scope
az role assignment create \
  --assignee $IDENTITY_ID \
  --role Reader \
  --scope /subscriptions/{subscription-id}

Configuration: 

AZURE_USE_MANAGED_IDENTITY=true

Benefits:

  • No credentials to manage or rotate
  • More secure than service principals
  • Automatic credential refresh
  • Audit trail in Azure Activity Log

2. Service Principal

Best for: On-premises deployment, non-Azure environments

# Create service principal
az ad sp create-for-rbac \
  --name "CertifyClouds Platform Workload (Production)" \
  --role Reader \
  --scopes /subscriptions/{subscription-id}

Configuration: 

AZURE_CLIENT_ID=12345678-1234-1234-1234-123456789abc
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=87654321-4321-4321-4321-cba987654321

Security Best Practice

  • Store client secret in Azure Key Vault (not in config files)
  • Rotate client secret every 90 days
  • Use certificate-based auth for production
  • Enable MFA for the service principal

Multi-Subscription Access

To scan multiple Azure subscriptions, grant the Reader role on each subscription:

Per-Subscription Assignment

# Assign to subscription 1
az role assignment create \
  --assignee $IDENTITY_ID \
  --role Reader \
  --scope /subscriptions/11111111-1111-1111-1111-111111111111

# Assign to subscription 2
az role assignment create \
  --assignee $IDENTITY_ID \
  --role Reader \
  --scope /subscriptions/22222222-2222-2222-2222-222222222222

Management Group Assignment (Enterprise)

For organizations with many subscriptions:

# Assign Reader at management group scope
az role assignment create \
  --assignee $IDENTITY_ID \
  --role Reader \
  --scope /providers/Microsoft.Management/managementGroups/{mg-id}

This grants access to all subscriptions under the management group.

Azure RBAC Permissions Detail

Core Permissions (All Tiers)

Microsoft.KeyVault/vaults/read
Microsoft.KeyVault/vaults/accessPolicies/read
Microsoft.Resources/subscriptions/read
Microsoft.Resources/subscriptions/resourceGroups/read
Microsoft.Network/privateEndpoints/read
Microsoft.Network/networkSecurityGroups/read
Microsoft.Insights/diagnosticSettings/read

Dependency Discovery (PRO Tier)

Microsoft.Web/sites/read                              # App Services, Function Apps
Microsoft.Web/sites/config/read                       # App settings, connection strings
Microsoft.Logic/workflows/read                        # Logic Apps
Microsoft.Sql/servers/read                            # SQL Servers
Microsoft.App/containerApps/read                      # Container Apps
Microsoft.ApiManagement/service/read                  # API Management
Microsoft.DataFactory/factories/read                  # Data Factory
Microsoft.DataFactory/factories/linkedservices/read   # Data Factory linked services
Microsoft.ContainerService/managedClusters/read       # AKS clusters
Microsoft.ServiceBus/namespaces/read                  # Service Bus
Microsoft.ServiceBus/namespaces/authorizationRules/read  # Service Bus auth rules
Microsoft.EventHub/namespaces/read                    # Event Hubs
Microsoft.EventHub/namespaces/authorizationRules/read # Event Hubs auth rules
Microsoft.Storage/storageAccounts/read                # Storage Accounts

Rotation Feature - Additional Permissions (PRO + ENTERPRISE)

The Rotation feature requires write access to rotate App Registration credentials and update secret values in Key Vaults.

Microsoft Graph API Permissions

Permission Tier Purpose Type
Application.Read.All STARTER Read-only - list App Registrations and their credential metadata for discovery / inventory views Application
Application.ReadWrite.All PRO Read App Registrations and add / remove their secrets + certificates during rotation Application

Grant one of the above according to your tier; Application.ReadWrite.All is a strict superset, so don't assign both. After assigning, grant admin consent in the Azure Portal so the permission takes effect.

Apply new permissions without a restart

Granted or changed a Microsoft Graph permission after CertifyClouds was already running? Open Settings → Azure Connection → Refresh Permissions. CertifyClouds re-acquires its Graph token on demand, so newly consented permissions take effect immediately; no container restart is needed.

Key Vault data-plane write

Rotation needs to write new secret values into target Key Vaults. Use the data-plane RBAC role rather than the control-plane Contributor:

az role assignment create \
  --assignee $IDENTITY_ID \
  --role "Key Vault Secrets Officer" \
  --scope /subscriptions/{subscription-id}

Key Vault Secrets Officer grants set / get / list / delete on secret values inside the vault. Use Key Vault Certificates Officer for certificate rotation. During certificate rotation CertifyClouds also reads the certificate's backing secret (the PFX) via Key Vault Secrets User, then re-imports the rotated certificate; the PFX never leaves your tenant.

The Crypto roles are used only by the KV→KV key replication sub-feature of Sync: Key Vault Crypto User on the source vault to export a key (backup_key) and Key Vault Crypto Officer on the target vault to import it (restore_key_backup). There is no baseline key rotation: application encryption uses a locally managed key, not a Key Vault key, so grant the Crypto roles only when you enable KV→KV key replication. The setup script grants Key Vault Crypto Officer per vault on the --pro path.

Avoid Key Vault Contributor

The Key Vault Contributor role is a control-plane role that permits deleting vaults, modifying access policies, and changing network rules - far broader than rotation requires. Use the least-privilege data-plane Officer roles above instead. Grant Contributor only if a customer ops policy explicitly requires it.

Dependent-resource write (full-stack rotation, PRO Dependencies)

Full-stack rotation writes the rotated credential into the dependent resources that consume it, so it needs control-plane WRITE on those resource types. The resource updaters touch:

Microsoft.Web/sites/write          # App Services, Function Apps (Website Contributor)
Microsoft.Sql/servers/write        # SQL Servers (SQL Server Contributor)
Microsoft.App/containerApps/write  # Container Apps (Container Apps Contributor)
Microsoft.Logic/workflows/write    # Logic Apps (Logic App Contributor)

Each write is covered by a least-privilege built-in role: Website Contributor (App Services / Functions), SQL Server Contributor (SQL admin password), Container Apps Contributor (Container App secrets), and Logic App Contributor (Logic App workflows). Assign these at subscription scope, and only when full-stack rotation is enabled for those dependents. The setup script grants all four on the --pro path.

az role assignment create \
  --assignee $IDENTITY_ID \
  --role "Website Contributor" \
  --scope /subscriptions/{subscription-id}

az role assignment create \
  --assignee $IDENTITY_ID \
  --role "SQL Server Contributor" \
  --scope /subscriptions/{subscription-id}

az role assignment create \
  --assignee $IDENTITY_ID \
  --role "Container Apps Contributor" \
  --scope /subscriptions/{subscription-id}

az role assignment create \
  --assignee $IDENTITY_ID \
  --role "Logic App Contributor" \
  --scope /subscriptions/{subscription-id}

Permission Verification

Test Azure Login

# For Managed Identity, CertifyClouds auto-detects managed identity
# when deployed to Azure VM, App Service, or Container Apps.
# No manual token retrieval required.

# For Service Principal
az login --service-principal \
  --username $AZURE_CLIENT_ID \
  --password $AZURE_CLIENT_SECRET \
  --tenant $AZURE_TENANT_ID

Test Subscription Access

az account list

Test Key Vault Access

az keyvault list --subscription {subscription-id}

Troubleshooting

"Insufficient permissions to list subscriptions"

Cause: Managed identity doesn't have Reader on subscription.

Fix: 

az role assignment create \
  --assignee $IDENTITY_ID \
  --role Reader \
  --scope /subscriptions/{subscription-id}

"Cannot access Key Vault: {vault-name}"

Cause: Key Vault has firewall enabled and CertifyClouds IP is not whitelisted.

Fix: 

az keyvault network-rule add \
  --name {vault-name} \
  --ip-address {certifyclouds-ip}

"AADSTS700016 - Application not found"

Cause: Service principal client secret expired or invalid.

Fix: 

az ad sp credential reset --name {app-id} --years 1

Security & Privacy

Discovery Does NOT Access Vault Contents

With only the Discovery (Reader + Key Vault Reader) roles, CertifyClouds reads configuration metadata only. It does not access:

  • Secret values
  • Key material
  • Certificate private keys

Why? The Reader role does not grant Key Vault data plane access. For Discovery, CertifyClouds only uses Azure Resource Manager (ARM) APIs to read resource properties.

PRO rotation is the one exception: when rotating a certificate it reads the certificate's backing secret (the PFX) inside your tenant via Key Vault Secrets User, solely to re-import the rotated certificate. That value never leaves your environment.

Audit Trail

All CertifyClouds API calls are logged in Azure Activity Logs:

# View CertifyClouds activity
az monitor activity-log list \
  --caller $IDENTITY_ID \
  --start-time 2025-11-09T00:00:00Z

Summary Checklist

Before running CertifyClouds scans, ensure:

  • [ ] Managed Identity or Service Principal created
  • [ ] Reader role assigned at subscription scope
  • [ ] Role assignment verified with az role assignment list
  • [ ] CertifyClouds can authenticate (test connection in UI)
  • [ ] Firewall rules configured if Key Vaults have network restrictions
  • [ ] Audit logging enabled to monitor access

Minimum Required: Reader role at /subscriptions/{subscription-id} scope

That's it! CertifyClouds requires no data plane access, no write permissions (except for Rotation), and no privileged roles.

Next: Network Requirements

Permissions get the app authorized; networking gets the app reachable. See Network Requirements for the outbound allowlist (license server, Docker Hub, Graph, Key Vault), the NSG / Azure Firewall snippets, and a diagnostic curl sequence for troubleshooting connectivity.