Azure Accounts

CostLens reads your Azure cost data and resource configuration through a dedicated App Registration (service principal), granted read-only Azure RBAC roles. The guided Add Account wizard connects with a Microsoft sign-in — no app registration, role assignment, or IDs to find and paste.

How it works#

Connect a new Azure subscription#

Step 1 — Add Account → Azure → choose access level#

From the Accounts page, click Add Account, choose Azure, then choose Read-Only or Read/Write:

The trust model is a multi-tenant Microsoft Entra application granted Azure RBAC at the scope you consent to, using a federated credential where supported — no long-lived client secret is required for this flow.

Step 2 — Authorize (Microsoft sign-in)#

Click Authorize. This redirects your browser to Microsoft's own sign-in page (the standard OAuth consent screen) — sign in as a user with Owner (or equivalent role-assignment rights) on the subscriptions you want to connect, and accept.

Step 3 — CostLens discovers and connects automatically#

Microsoft redirects you back into CostLens. From here everything is automatic:

1. CostLens lists every subscription visible to your signed-in identity.
2. It assigns itself Cost Management Reader and Reader on each one.
3. As soon as at least one subscription's roles are confirmed, that subscription connects and its first sync starts.

Azure RBAC can take up to about a minute to propagate — the wizard keeps checking automatically during that window, so you don't need to do anything but wait.

Connect a whole tenant (management group)#

To grant CostLens access to every subscription under a management group in one step instead of one at a time, use the Connect an organization flow from the Accounts page (the same multi-account discovery used for AWS Organizations): pick an already-connected Azure account, optionally run the generated management-group grant script once, then Discover & connect — CostLens enumerates and connects every subscription it can now see.

Reconnecting a removed subscription#

If a subscription was previously connected and later removed, reconnecting it (Authorize again, sign in the same way) reuses the existing role assignments rather than creating duplicates — Azure role assignments are naturally idempotent, so there's nothing to clean up first, unlike AWS's CloudFormation stacks.

If you connect a subscription that turns out to already be active in your CostLens organization, you'll see "This account already exists — it's already connected. Nothing was added again" on the success screen.

Alternative: connect with your own App Registration#

If your organization requires using its own app registration rather than CostLens's, or Authorize isn't available in your environment, use the manual path instead.

Step 1 — Azure CLI setup script#

The wizard's manual-entry step generates this script with your Subscription ID pre-filled and offers a one-click copy/download. Run it in Azure Cloud Shell or any terminal with the az CLI signed in as a user who can create app registrations and assign roles.

#!/usr/bin/env bash
# CostLens — Azure connection setup (Cost Management Reader, least privilege)
set -euo pipefail
 
SUBSCRIPTION_ID="<SUBSCRIPTION_ID>"
APP_NAME="costlens-cost-reader"
 
az account set --subscription "$SUBSCRIPTION_ID"
 
# 1. Create an app registration + service principal
APP_ID=$(az ad app create --display-name "$APP_NAME" --query appId -o tsv)
az ad sp create --id "$APP_ID" >/dev/null
 
# 2. Create a client secret (valid 12 months) — copy the printed value
CLIENT_SECRET=$(az ad app credential reset --id "$APP_ID" --years 1 --query password -o tsv)
 
# 3. Grant Cost Management Reader (read-only cost data) at the subscription scope
az role assignment create \
  --assignee "$APP_ID" \
  --role "Cost Management Reader" \
  --scope "/subscriptions/$SUBSCRIPTION_ID"
 
# 4. Grant Reader (resource inventory, Monitor metrics) at the same scope
az role assignment create \
  --assignee "$APP_ID" \
  --role "Reader" \
  --scope "/subscriptions/$SUBSCRIPTION_ID"
 
TENANT_ID=$(az account show --query tenantId -o tsv)
 
echo ""
echo "Enter these into CostLens's manual connect step:"
echo "  Tenant ID:       $TENANT_ID"
echo "  Client ID:       $APP_ID"
echo "  Client secret:   $CLIENT_SECRET"
echo "  Subscription ID: $SUBSCRIPTION_ID"

Step 2 — Enter the details in CostLens#

On the wizard's manual-entry step, enter the Directory (tenant) ID, Subscription ID, and — since you're using your own app registration rather than CostLens's — the Application (client) ID and client secret the script printed. Click Connect account.

Recommendations & Advisor#

Azure recommendations come from two places, both read-only:

• Azure Advisor cost recommendations (right-sizing, shutdown, reservations) — the authoritative source, surfaced by the Azure Advisor (Cost) check. When Advisor's own "right-size or shut down" recommendation targets a VM, CostLens can apply it directly using the same fix flow as its own VM checks.
• CostLens resource checks over the Azure Resource Manager + Monitor APIs — idle VMs, unattached disks, orphaned snapshots, idle public IPs and load balancers.

Both Reader (resource/metric reads) and Cost Management Reader (billing) are granted automatically by Authorize; the manual path needs both assigned explicitly (Step 1 above).

Kubernetes (AKS) cost & optimization#

The Cost Management Reader + Reader roles above already give CostLens what it needs for AKS. Reader covers Azure Monitor metric reads and VM Scale Set enumeration, so no separate Monitoring Reader role is required.

Applying fixes (optional)#

Choosing Read/Write during onboarding already grants what Auto-Fix needs. Scanning itself is always read-only regardless of access level. Today's Azure remediations:

If you connected with Read-Only and want Auto-Fix later, reconnect with Read/Write — Authorize again and choose Read/Write; CostLens adds the missing role assignments to the existing service principal rather than creating a new one.

Enabling automatic Auto-Fix with your own app registration (least privilege)#

If you used the manual/own-app-registration path, grant only VM power control via a custom role rather than broad Contributor:

az role definition create --role-definition '{
  "Name": "CostLens Auto-Fix (VM power)",
  "Description": "Least-privilege VM start/deallocate for CostLens Auto-Fix",
  "Actions": [
    "Microsoft.Compute/virtualMachines/read",
    "Microsoft.Compute/virtualMachines/start/action",
    "Microsoft.Compute/virtualMachines/deallocate/action"
  ],
  "AssignableScopes": ["/subscriptions/<SUBSCRIPTION_ID>"]
}'
az role assignment create --assignee "<CLIENT_ID>" \
  --role "CostLens Auto-Fix (VM power)" --scope "/subscriptions/<SUBSCRIPTION_ID>"

First sync phases#

Managing connected accounts#

Common errors and fixes#