Connect Microsoft Azure

This guide walks you through connecting an Azure subscription to Onam using a service principal with read-only access. You register an app in Microsoft Entra ID, create a client secret, assign the built-in Reader role, and paste the credentials into the Onam console. The connection is read-only: Onam never makes changes to your Azure environment.

Time to complete: ~20 minutes. Azure knowledge required: Microsoft Entra ID (Azure AD), IAM basics.

How the connection works

The diagram above shows the connection model end-to-end. Onam connects to Azure via a service principal in Microsoft Entra ID with the Reader role at subscription scope. You register an app, generate a client secret, assign Reader, and enter the credentials in the Onam console — Onam then authenticates via OAuth2 client credentials and reads resource configurations through the Azure Resource Manager API.

• Reader role only — Microsoft's built-in least-privilege read role. No write actions are possible.
• Scoped to the subscriptions you assign — Onam cannot see subscriptions you didn't explicitly grant Reader on.
• Client secret expires on the schedule you set — 24 months recommended, with a calendar reminder to rotate.

How the connection stays read-only: the service principal holds only the built-in Reader role plus read-only Microsoft Graph permissions (Directory.Read.All, Policy.Read.All, AuditLog.Read.All). Azure RBAC enforces the boundary on every API call — Onam cannot exceed the roles you assigned. The client secret is stored encrypted (AWS Secrets Manager with KMS) and you can revoke it in Entra ID at any time to sever access instantly.

Before you begin

• An Azure subscription with the Owner or User Access Administrator role
• Permission to register applications in Microsoft Entra ID (Azure AD)
• An Onam account with at least the tenant_admin role

Step 1 — Register an app and create a client secret

Register the app (Azure Portal)

1. Open Microsoft Entra ID
2. Navigate to App registrations → New registration
3. Name: cspm-scanner (or any name you prefer)
4. Supported account types: Accounts in this organizational directory only
5. Redirect URI: leave blank
6. Click Register
7. Copy the Application (client) ID and Directory (tenant) ID — you'll need these later

Register the app (Azure CLI)

# Create the App Registration
az ad app create --display-name cspm-scanner

# Get the App ID
APP_ID=$(az ad app list --display-name cspm-scanner --query '[0].appId' -o tsv)
echo "App ID: $APP_ID"

# Create a Service Principal
az ad sp create --id $APP_ID

# Get your Tenant ID
TENANT_ID=$(az account show --query tenantId -o tsv)
echo "Tenant ID: $TENANT_ID"

Create the client secret (Azure Portal)

1. In your App Registration, navigate to Certificates & secrets
2. Click New client secret
3. Description: cspm-scanner-secret
4. Expiry: 24 months (recommended — set a calendar reminder to rotate)
5. Click Add

Create the client secret (Azure CLI)

# Create a client secret (valid for 2 years)
SECRET=$(az ad app credential reset \
  --id $APP_ID \
  --years 2 \
  --query password -o tsv)
echo "Client Secret: $SECRET"

Copy the secret value immediately — Azure shows it exactly once. If you lose it, generate a new secret; the old one keeps working until you delete it or it expires.

Step 2 — Assign the Reader role at subscription scope

Reader is the lowest-privilege built-in Azure role that grants read access to every resource type. Assigning it at subscription scope automatically covers every resource group and every resource within those groups.

Using the Azure Portal

1. Navigate to Subscriptions → select your subscription
2. Go to Access control (IAM) → Add → Add role assignment
3. Role: Reader
4. Assign access to: User, group, or service principal
5. Select: cspm-scanner (your App Registration)
6. Click Review + assign

Using the Azure CLI

# Get your Subscription ID
SUB_ID=$(az account show --query id -o tsv)
echo "Subscription ID: $SUB_ID"

# Assign Reader role
az role assignment create \
  --assignee $APP_ID \
  --role Reader \
  --scope /subscriptions/$SUB_ID

Step 3 — Grant Microsoft Graph permissions

To scan Microsoft Entra ID resources (users, groups, app registrations, conditional access policies), grant three application-level Graph API permissions:

Using the Azure Portal

1. In your App Registration, go to API permissions → Add a permission
2. Select Microsoft Graph
3. Select Application permissions (not Delegated)
4. Add Directory.Read.All, Policy.Read.All, and AuditLog.Read.All
5. Click Grant admin consent (requires Global Administrator or Privileged Role Administrator)

Using the Azure CLI

# Add Microsoft Graph permissions
GRAPH_APP_ID="00000003-0000-0000-c000-000000000000"

az ad app permission add \
  --id $APP_ID \
  --api $GRAPH_APP_ID \
  --api-permissions \
    7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role \
    246dd0d5-5bd0-4def-940b-0421030a5b68=Role \
    b0afded3-3588-46d8-8b3d-9842eff778da=Role

# Grant admin consent
az ad app permission admin-consent --id $APP_ID

Step 4 — Connect and run your first scan

1. In the Onam console, navigate to Onboarding → Connect Cloud Account
2. Select Microsoft Azure
3. Fill in the four credential fields (table below)
4. Enter an Account Alias (friendly name)
5. Click Validate Connection

Run your first scan

1. Navigate to Onboarding → Cloud Accounts
2. Click the subscription you just added
3. Click Run Scan Now — the first scan typically completes in 15–60 minutes depending on subscription size

You receive an in-app notification and an email when the scan completes.

Multi-subscription setup

To connect multiple Azure subscriptions, repeat Steps 2–4 for each subscription. You can reuse the same App Registration — just assign the Reader role at each subscription scope. For Azure Management Groups (to cover all subscriptions at once):

# Assign Reader at management group scope
MG_ID="your-management-group-id"

az role assignment create \
  --assignee $APP_ID \
  --role Reader \
  --scope /providers/Microsoft.Management/managementGroups/$MG_ID

What gets scanned

Onam evaluates 112 Azure services against 3,741 posture rules, plus 202 identity-focused CIEM rules — the largest per-cloud rule set in Onam's 10,000+ rule registry. New services are added on a quarterly cadence.

The same service principal also powers behavioral threat detection: Onam's CDR engine ingests Azure Monitor activity logs (exported to Blob Storage) and correlates them into threat findings.

Troubleshooting and secret rotation

Rotating the client secret

Client secrets expire. Set a calendar reminder before expiry:

# Create a new secret before the old one expires
NEW_SECRET=$(az ad app credential reset --id $APP_ID --years 2 --query password -o tsv)

# Update the credential in the Onam console:
# Onboarding → Cloud Accounts → [your account] → Edit → Update Secret

Next steps

• Connect Google Cloud Platform — repeat the process for your next cloud; Onam covers all 7.
• CIEM — analyze Entra ID identities and effective permissions across your subscriptions.
• CDR — turn on activity-log threat detection for this subscription.
• Book a demo — walk through your first scan results with an Onam engineer.