Azure Setup Guide

This guide walks you through creating a Service Principal with read-only access for CLARITY and adding it to your instance.

Prerequisites

• An Azure subscription with Owner or User Access Administrator role
• Azure CLI installed or access to the Azure Portal

Option 1: Azure CLI (Recommended)

Create a Service Principal and assign the required roles:

# Log in to Azure
az login

# Create a Service Principal with Reader role on your subscription
az ad sp create-for-rbac \
  --name "clarity-finops" \
  --role "Reader" \
  --scopes "/subscriptions/YOUR_SUBSCRIPTION_ID"

This command outputs:

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "displayName": "clarity-finops",
  "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Save these values — you will need them:

• appId = Client ID
• password = Client Secret
• tenant = Tenant ID

Now assign the Cost Management Reader role for billing data access:

# Assign Cost Management Reader role
az role assignment create \
  --assignee "APP_ID_FROM_ABOVE" \
  --role "Cost Management Reader" \
  --scope "/subscriptions/YOUR_SUBSCRIPTION_ID"

Optionally, assign Monitoring Reader for enhanced performance metrics:

# Optional: Monitoring Reader for detailed metrics
az role assignment create \
  --assignee "APP_ID_FROM_ABOVE" \
  --role "Monitoring Reader" \
  --scope "/subscriptions/YOUR_SUBSCRIPTION_ID"

Option 2: Azure Portal

Step 1: Register an Application

1. Go to Microsoft Entra ID (Azure Active Directory) in the Azure Portal
2. Navigate to App registrations > New registration
3. Enter:
   • Name: clarity-finops
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Leave blank
4. Click Register
5. On the overview page, copy the Application (client) ID and Directory (tenant) ID

Step 2: Create a Client Secret

1. In the app registration, go to Certificates & secrets > Client secrets > New client secret
2. Enter a description (e.g., "CLARITY access") and select an expiration period
3. Click Add
4. Copy the secret Value immediately — it is shown only once

Step 3: Assign Roles on the Subscription

1. Go to Subscriptions > select your subscription
2. Navigate to Access control (IAM) > Add role assignment
3. Assign the Reader role:
   • Role: Reader
   • Assign access to: User, group, or service principal
   • Search for clarity-finops and select it
   • Click Review + assign
4. Repeat to assign the Cost Management Reader role
5. Optionally assign Monitoring Reader for enhanced metrics

Step 4: Find the Service Principal Object ID

This step is important for troubleshooting role assignments:

1. Go to Microsoft Entra ID > Enterprise applications
2. Search for clarity-finops
3. Note the Object ID on this page — this is the Service Principal Object ID

Service Principal Object ID

Azure has three different Object IDs for app registrations. When troubleshooting role assignments or referencing the SP programmatically, always use the Object ID from Enterprise Applications (the Service Principal), not the Object ID from the App Registration page. They are different values.

Required Roles

Role	Purpose	Required
Reader	Resource discovery — lists VMs, databases, storage accounts, AKS clusters, and all other resources	Yes
Cost Management Reader	Cost and billing data — service-level costs, resource-level costs, budgets, and forecasts	Yes
Monitoring Reader	Performance metrics — CPU, memory, network, and disk utilization from Azure Monitor	Optional

Why Reader?

Reader is a broad Azure built-in role that grants read access across all resource types in the subscription. CLARITY uses this to discover all resources that may generate costs — VMs, AKS clusters, SQL databases, storage accounts, load balancers, App Services, network resources, and more. This ensures complete visibility into idle, oversized, and underutilized resources.

Multi-Subscription Access

If you have multiple subscriptions under the same tenant, you can assign roles at the Management Group level to grant CLARITY access to all subscriptions at once:

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

CLARITY will automatically discover all subscriptions within the management group scope.

Adding to CLARITY

1. Log in to CLARITY and navigate to Provider Setup
2. Click Add Account and select Azure
3. Enter the following:
   • Subscription ID — your Azure subscription ID
   • Tenant ID — the Directory (tenant) ID from the app registration
   • Client ID — the Application (client) ID from the app registration
   • Client Secret — the secret value you created
4. Click Save

CLARITY validates the credentials immediately by authenticating against your Azure tenant and begins the initial sync.

Verification

After the initial sync completes (typically 2-5 minutes), verify that data is flowing:

• Dashboard — Cost breakdown by Azure service (Virtual Machines, SQL Database, Storage, etc.)
• Resources — Your VMs, AKS clusters, databases, and other resources listed with cost attribution
• Insights — Optimization recommendations based on Azure Advisor and utilization analysis
• Organizations — If the Service Principal has access to multiple subscriptions, they appear under the Organizations page with management group hierarchy

If resources appear but costs show as zero, the Cost Management Reader role may not have propagated yet. Azure role assignments can take up to 5 minutes to take effect.

Cleanup

To remove CLARITY access from your Azure environment:

Azure CLI

# Remove role assignments
az role assignment delete \
  --assignee "APP_ID" \
  --role "Reader" \
  --scope "/subscriptions/YOUR_SUBSCRIPTION_ID"

az role assignment delete \
  --assignee "APP_ID" \
  --role "Cost Management Reader" \
  --scope "/subscriptions/YOUR_SUBSCRIPTION_ID"

# Delete the app registration
az ad app delete --id "APP_ID"

Azure Portal

1. Go to Subscriptions > Access control (IAM) > remove the role assignments for clarity-finops
2. Go to Microsoft Entra ID > App registrations > select clarity-finops > Delete