Connect Microsoft Azure

Connecting Azure brings your subscription costs, invoices, resource metrics and reservation commitments into Helias, so you can see spend by subscription, resource group and resource, and get rightsizing recommendations backed by real utilisation.

Helias reads that data through a service principal that lives in your own Microsoft Entra ID tenant. You create it with one command. It has no secret, no password and no certificate, and Helias signs in as it using federated credentials, so neither side ever holds a key.

This takes about ten minutes with the Azure CLI, or Azure Cloud Shell if you would rather install nothing.

Before you begin

The Azure CLI installed and signed in with az login, or Azure Cloud Shell.
Permission to create a service principal in Microsoft Entra ID.
For a single subscription: Owner or User Access Administrator on that subscription.
For an organization: Owner or User Access Administrator across your tenant, and permission to assign a billing role on your billing account.

Connecting is often two people. Someone with billing visibility knows which billing account pays, and someone with administrative access grants the roles. Check the list above before you start, so you know which.

You also need a Helias account, which is granted by request and approved by a person. Start at Get access if you do not have one yet.

How the connection works

The service principal you create is an identity in your tenant, not a credential you hand over. Helias signs in as it from an environment dedicated to your organization, which is a separate AWS account per customer, so no collector or service principal is ever shared across customers.

Nothing else is created in your tenant, nothing is modified, and the connection costs you nothing in Azure: Helias runs no queries inside your tenant and stores nothing there.

The one temporary change is on the organization path. Assigning a role at the tenant root requires you to hold User Access Administrator on that root, which Azure only grants through a one-time elevation. The commands do the elevation and then remove it again.

Every call Helias makes appears in your own Microsoft Entra ID sign-in and activity logs, attributed to that service principal, and you can remove it from your tenant at any time.

Scope and permissions

You connect at one of two scopes. Every role below is read-only, and none of them can create, modify, delete or start anything. The Permissions reference carries the same grants for every provider in one place, which is the page to send to a security reviewer.

	Organization	Single subscription
Covers	Every subscription under one billing account	One subscription
New subscriptions	Covered automatically	Not covered, connect each one
Reservations	Included	Not available
Needs tenant-level access	Yes, with a temporary elevation you remove afterwards	No

Connect at the organization scope unless you are running a trial on one subscription. You can connect additional subscriptions later either way.

Organization

Grant	Applies to	Why
`Enrollment Reader`	Billing account (Enterprise Agreement)	Reads enrollment cost and invoice data. Used when your agreement type is EA.
`Billing account reader`	Billing account (Microsoft Customer Agreement)	Reads billing profile cost and invoice data. Used when your agreement type is MCA.
`Monitoring Reader`	Tenant root management group	Reads resource metrics and usage across every subscription. This is what makes rightsizing analysis possible, and what covers new subscriptions as they appear.
`Reservations Reader`	/providers/Microsoft.Capacity	Reads your reservation orders, so commitment savings appear in your cost analysis.

Single subscription

Grant	Applies to	Why
`Billing Reader`	The subscription you connect	Reads consumption and cost detail for that subscription.
`Monitoring Reader`	The subscription you connect	Reads resource metrics and usage for that subscription.

Connect your organization

The app generates every command with your own values already filled in. The versions here show the placeholders instead, so you can see exactly what runs.

1
Get your tenant ID
Use the following command to print your Directory (tenant) ID.
```
az account show --query tenantId -o tsv
```
2
Create the Helias service principal
Use the following command to mirror the application Virtasant registered for your organization into your own tenant. This creates an identity and nothing else: no secret, no password, and no roles yet. The app gives you the application ID to substitute for <APP_ID>.
```
az ad sp create --id <APP_ID>
```
3
Get the service principal object ID
Billing role assignments identify the principal by its object ID, which is not the same value as the application ID.
```
az ad sp show --id <APP_ID> --query="id" -o tsv
```
4
Identify your billing account
Your agreement type decides which billing role you assign next. Use the following command to print it.
```
az billing account list --query "[?accountStatus=='Active'].agreementType" -o tsv
```
Then print your billing account ID.
```
az billing account list --query "[?accountStatus=='Active'].name" -o tsv
```
Both commands list active accounts only. An expired or disabled billing account cannot be connected.

Assign the billing role

Run the block that matches the agreement type from the previous step.

Enterprise Agreement. The Enrollment Reader role definition is a fixed, well-known ID, so this is a single call.

az rest --method PUT \
  --url 'https://management.azure.com/providers/Microsoft.Billing/billingAccounts/<BILLING_ACCOUNT_ID>/billingRoleAssignments/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e?api-version=2019-10-01-preview' \
  --headers 'Content-Type=application/json' \
  --body '{"properties":{"principalId":"<SP_OBJECT_ID>","roleDefinitionId":"/providers/Microsoft.Billing/billingAccounts/<BILLING_ACCOUNT_ID>/billingRoleDefinitions/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e"}}'

Microsoft Customer Agreement. The Billing account reader role definition ID is specific to your billing account, so look it up first.

az rest --method GET \
  --url 'https://management.azure.com/providers/Microsoft.Billing/billingAccounts/<BILLING_ACCOUNT_ID>/billingRoleDefinitions?api-version=2019-10-01-preview' \
  --query="value[?properties.roleName == 'Billing account reader'].name" -o tsv

az rest --method POST \
  --url 'https://management.azure.com/providers/Microsoft.Billing/billingAccounts/<BILLING_ACCOUNT_ID>/createBillingRoleAssignment?api-version=2019-10-01-preview' \
  --headers 'Content-Type=application/json' \
  --body '{"properties":{"principalId":"<SP_OBJECT_ID>","roleDefinitionId":"<BILLING_READER_ROLE_DEFINITION_ID>"}}'

6
Assign the tenant-level roles
This block elevates your access, assigns Monitoring Reader at the root management group and Reservations Reader at the tenant Capacity provider.
```
az rest --method post \
  --url "/providers/Microsoft.Authorization/elevateAccess?api-version=2016-07-01" && \
az role assignment create \
  --role "Monitoring Reader" \
  --assignee <APP_ID> \
  --scope "/providers/Microsoft.Management/managementGroups/<TENANT_ID>" && \
az role assignment create \
  --role "Reservations Reader" \
  --assignee <APP_ID> \
  --scope "/providers/Microsoft.Capacity"
```
Why the command elevates your access
Azure only permits a role assignment at the tenant root to a User Access Administrator on that root, and that is a role you have to grant yourself. The first line does exactly that, and nothing more. It changes your own access, not the service principal's. Azure evaluates RBAC per request, so the assignments that follow see the elevated access with no sign-out and no token refresh.
7
Remove the elevation
Return your tenant to least privilege. The role assignments you just made are unaffected.
```
az role assignment delete \
  --role "User Access Administrator" --scope "/"
```
8
Provide the values back to the app
Each has a command above that prints it, so nothing has to be hunted for in the portal.
- Your Directory (tenant) ID.
- The object ID of the service principal you created.
- Your agreement type and your billing account ID. On a Microsoft Customer Agreement, also the Billing account reader role definition ID.

Connect a single subscription

There is no elevation and no tenant-level step on this path.

1
Get your tenant ID
```
az account show --query tenantId -o tsv
```
2
Create the Helias service principal
This creates an identity and nothing else: no secret, no password, and no roles yet. The app gives you the application ID to substitute for <APP_ID>.
```
az ad sp create --id <APP_ID>
```

Assign the subscription roles

Both roles are subscription-scoped, so they run as one block.

az role assignment create \
  --role "Billing Reader" \
  --assignee <APP_ID> \
  --scope "/subscriptions/<SUBSCRIPTION_ID>" && \
az role assignment create \
  --role "Monitoring Reader" \
  --assignee <APP_ID> \
  --scope "/subscriptions/<SUBSCRIPTION_ID>"

4
Provide the values back to the app
- Your Directory (tenant) ID.
- The object ID of the service principal you created.
- The subscription ID.

Verify the connection

Select Validate in the app. Helias checks the access before storing anything, and shows each check as it runs:

Check	What it proves
Authenticate service principal	The service principal exists in your tenant and Helias can sign in as it
Check billing access	The billing role is assigned at the scope Helias reads cost from
Check monitoring access	Monitoring Reader is assigned, so metrics and usage are readable
Check reservations access	Reservations Reader is assigned. Organization scope only

Helias verifies Azure access by reading the service principal's role assignments at each scope, not by calling the APIs and seeing whether they answer. An Azure list call returns 200 with an empty result when a role is missing, so reading the assignments catches it now rather than weeks later as missing data.

If a check fails, nothing is stored and nothing is left behind on either side. Fix the grant and validate again.

After you connect

Your first data appears in Helias within 24 hours of a successful connection, and you get an email when the first insights are ready.

Until then the connections page shows a collection status: Pending while collection has not started, In progress while it runs, and Completed once data is flowing.

Helias checks your access at connect time, not continuously

Every grant is verified when you connect, and a failure names the grant that is missing. Afterwards Helias does not re-check. If you revoke the access on your side later, collection stops but the connections page keeps showing the provider as connected until you disconnect there too.

Limits

Reservations are organization scope only. A single-subscription connection grants no tenant-level access, so reservation orders are not read and commitment savings do not appear. Cost analysis and rightsizing still work.
One billing account per organization connection. Subscriptions billed to a different billing account are not covered by that connection and need their own.
Disconnecting is per subscription. There is no single action that disconnects an entire tenant.
OpenAI models bought through Azure are part of your Azure bill and appear here, not in a separate AI provider connection.

Troubleshooting

Cause	Resolution
Authenticate service principal fails	The service principal was not created in this tenant, or the application ID is wrong. Re-run the `az ad sp create` command and confirm you are signed in to the right tenant with `az account show`.
Check billing access fails, Enterprise Agreement	Enrollment Reader is not assigned on the billing account. Re-run the assignment and confirm the billing account ID is the one from `az billing account list`.
Check billing access fails, Microsoft Customer Agreement	The Billing account reader role definition ID is specific to your billing account. Look it up again for the account you are connecting rather than reusing one from another account.
Check monitoring access fails	Monitoring Reader is missing at the scope you connected. Organization scope needs it at the root management group, single subscription needs it on that subscription. Role assignments can take a few minutes to propagate, so wait a moment and validate again before regranting.
Check reservations access fails	Reservations Reader is not assigned at `/providers/Microsoft.Capacity`. It needs the tenant-root elevation, so if you removed the elevation before the assignment landed, elevate and reassign.
The elevation command is refused	You need Owner or User Access Administrator on the tenant root to elevate. This is the one step that cannot be delegated to a subscription-level role.
A subscription is missing after connecting	Organization scope covers subscriptions under the billing account you connected. Confirm the subscription is billed to that account.

Disconnecting

You can disconnect at any time from the connections page. Disconnecting releases monitoring of that subscription, immediately.

It does not change anything in your own cloud. What stays behind is the mirrored service principal and its role assignments, which stay tenant-wide. Remove the service principal in Microsoft Entra ID.

Helias holds read-only access, so it cannot remove a grant you made.

Azure disconnects one subscription at a time. There is no single action that disconnects an entire tenant, and the service principal is released once the last subscription is gone.