Connect Azure to Xplorr: Service Principal Setup for Cost Data

import { Steps } from ‘@astrojs/starlight/components’;

Connect Azure to Xplorr

Xplorr reads your Azure billing data through the Azure Cost Management API. You grant access by creating a Service Principal (app registration) with Reader-level permissions on your subscription. Xplorr authenticates using the client secret — no interactive login, no user credentials.

What You Need

An Azure subscription with one of these billing account types: Enterprise Agreement (EA), Microsoft Customer Agreement (MCA), or Pay-As-You-Go (PAYG)
Permission to create app registrations in Azure AD (Microsoft Entra ID)
Permission to assign roles on the subscription (Owner or User Access Administrator)

How It Works

Xplorr uses the @azure/identity SDK with ClientSecretCredential to authenticate as your Service Principal. It then calls the Azure Cost Management API to pull daily cost data grouped by service, region, and resource group.

Four values are required:

Tenant ID — Your Azure AD directory
Client ID — The app registration’s Application (client) ID
Client Secret — The app registration’s secret value
Subscription ID — The subscription to pull billing data from

Method 1: Azure Portal

Register an application in Azure AD

Go to Azure Portal > Microsoft Entra ID > App registrations and click New registration.
- Name: Xplorr Cost Reader
- Supported account types: Accounts in this organizational directory only (Single tenant)
- Redirect URI: Leave blank
Click Register. After creation, copy these values from the overview page:
- Application (client) ID — this is your Client ID
- Directory (tenant) ID — this is your Tenant ID
Create a client secret

In the app registration, go to Certificates & secrets > Client secrets > New client secret.
- Description: xplorr-access
- Expires: 24 months (you’ll need to rotate before expiry)
Click Add. Copy the Value immediately — it won’t be shown again. This is your Client Secret.
Assign Reader role on the subscription

Go to Subscriptions, click on your subscription, then go to Access control (IAM) > Add role assignment.
- Role: Cost Management Reader (this is more restrictive than Reader and sufficient for Xplorr)
- Assign access to: User, group, or service principal
- Select: Search for Xplorr Cost Reader (the app you just registered)
Click Save.

If Cost Management Reader isn’t available, use Reader instead. Both work — Cost Management Reader is narrower.
Enter credentials in Xplorr

Log in to console.xplorr.io. Go to Settings > Cloud Accounts > Add Account > Microsoft Azure.

Enter:
- Tenant ID (from step 1)
- Client ID (from step 1)
- Client Secret (from step 2)
- Subscription ID (from the Subscriptions page in Azure Portal)
Click Connect. Xplorr validates the credentials and starts the first sync. Initial sync takes 2-10 minutes depending on the amount of billing history.

Method 2: Azure CLI

If you prefer the command line, run these commands in a terminal with the Azure CLI installed:

# Log in to Azure
az login

# Set your subscription
az account set --subscription "YOUR_SUBSCRIPTION_ID"

# Create the app registration
az ad app create --display-name "Xplorr Cost Reader"

# Note the appId from the output — that's your Client ID
APP_ID="<appId from output>"

# Create a service principal for the app
az ad sp create --id $APP_ID

# Create a client secret (valid for 2 years)
az ad app credential reset --id $APP_ID --years 2

# Note the "password" from the output — that's your Client Secret
# Note the "tenant" from the output — that's your Tenant ID

# Assign Cost Management Reader role on the subscription
SUBSCRIPTION_ID="<your subscription ID>"
az role assignment create \
  --assignee $APP_ID \
  --role "Cost Management Reader" \
  --scope "/subscriptions/$SUBSCRIPTION_ID"

Copy the Tenant ID, Client ID, Client Secret, and Subscription ID into the Xplorr connection form.

Supported Billing Account Types

Billing Type	Supported	Notes
Enterprise Agreement (EA)	Yes	Full cost data, amortized reserved instance costs
Microsoft Customer Agreement (MCA)	Yes	Full cost data
Pay-As-You-Go (PAYG)	Yes	Full cost data
CSP (Cloud Solution Provider)	Partial	Depends on partner permissions
Free / Trial	No	Azure Cost Management API is not available on free tier

Connecting Multiple Subscriptions

Repeat the process for each subscription. The Service Principal can be reused — just assign the Cost Management Reader role on each additional subscription:

az role assignment create \
  --assignee $APP_ID \
  --role "Cost Management Reader" \
  --scope "/subscriptions/ANOTHER_SUBSCRIPTION_ID"

Then add each subscription as a separate cloud account in Xplorr.

Common Mistakes

Copying the secret ID instead of the secret value. Azure shows both an ID and a Value for client secrets. You need the Value (the long random string), not the ID (the GUID).
Not assigning the role on the subscription. Creating the app registration and secret is not enough. The Service Principal must have a role assignment on the target subscription.
Using a role that doesn’t include cost data. Contributor and Owner include cost access, but Reader alone does NOT include cost management. Use Cost Management Reader or Reader + Cost Management Reader.
Expired client secret. If the connection stops working after several months, check if the client secret expired. Create a new one and update the credentials in Xplorr.

Troubleshooting

InvalidAuthenticationToken — The access token is invalid

Verify the Tenant ID, Client ID, and Client Secret are correct and from the same app registration
Check that the client secret hasn’t expired (go to App registrations > your app > Certificates & secrets)
Make sure you copied the secret Value, not the secret ID

AuthorizationFailed — does not have authorization to perform action

The Service Principal doesn’t have a role on the subscription. Go to the subscription’s IAM page and verify the role assignment exists.
Role assignments can take up to 5 minutes to propagate. Wait and retry.

BillingAccountNotFound or no cost data

Azure Cost Management isn’t available on Free/Trial subscriptions
For EA accounts, make sure your enrollment has the “Cost Management” feature enabled (it’s enabled by default for most EA agreements)
Trigger a manual sync from Settings > Cloud Accounts > Sync

Cost data is incomplete or missing some days

Azure Cost Management data can lag 24-48 hours. Recent days may not appear until Azure processes them. This is an Azure limitation, not Xplorr.

Setup Checklist

App registration created in Microsoft Entra ID
Client secret generated and value copied (not the ID)
Cost Management Reader role assigned on the subscription
Tenant ID, Client ID, Client Secret, and Subscription ID entered in Xplorr
Connection shows “Connected” in Settings > Cloud Accounts
Dashboard shows Azure cost data

FAQ

Is the access read-only? Yes. The Cost Management Reader role only permits reading cost and billing data. It cannot create, modify, or delete any Azure resource.

Which Azure regions does Xplorr pull data from? Azure Cost Management is a global service. Cost data covers all regions in the subscription.

How often does Xplorr sync? Every 6 hours. You can trigger a manual sync from the dashboard or via the trigger_sync MCP tool.

Do I need to set up a billing export? No. Unlike GCP, Azure provides cost data directly through the Cost Management API without requiring a separate export.

Can I connect multiple subscriptions under the same tenant? Yes. Create one app registration and assign the role on each subscription. Add each subscription as a separate cloud account in Xplorr.

What about Management Groups? You can assign the role at the Management Group level to cover all subscriptions underneath. Use the scope /providers/Microsoft.Management/managementGroups/YOUR_MG_ID in the role assignment.

Connect AWS — IAM role setup for AWS cost data
Connect GCP — Service account and BigQuery billing export
Budget Alerts — Set up spend notifications after connecting