Azure Cloud

Connect your Azure subscriptions so the Autoheal agents can investigate incidents across your Azure infrastructure.

You connect one identity and grant it a role — we recommend Reader, for read-only access — on the subscriptions you want the agent to read. One identity covers as many subscriptions as you grant it access to, so there's no separate integration per subscription.

What the agent can do

Capability	Examples
Resources & groups	az group list, az resource list
Compute	virtual machines and scale sets (az vm list, az vmss list)
AKS	clusters and node pools (az aks list, az aks show)
Storage & networking	az storage account list, az network …
Azure Monitor	metrics and the Activity Log (az monitor metrics list, az monitor activity-log list)
Log Analytics	KQL queries (az monitor log-analytics query)
Resource Graph	cross-resource discovery across subscriptions (az graph query)

Set up

How you connect depends on where Autoheal runs. Pick your deployment:

Autoheal Cloud (SaaS)

Connect with Microsoft Entra Workload Identity Federation: create an identity in your Microsoft Entra tenant, configure it to trust Autoheal's OIDC issuer, and assign it the Reader role on the subscriptions you want the agent to read.

Prerequisites

• One or more Azure subscriptions in a single Microsoft Entra tenant, and permission to create a user-assigned managed identity (or an Entra app registration) and assign it a role.
• The issuer, subject, and audience values for your tenant, provided by Autoheal (in the Federated credential reference below).
• Two values to enter in Autoheal: your Directory (Tenant) ID and the identity's Client ID. There's no subscription ID — the identity covers every subscription you grant it Reader on.

Azure CLI

1

Create a user-assigned managed identity

az identity create -g <resource-group> -n autoheal-readonly
# note the clientId, principalId, and tenantId from the output

2

Add a federated credential that trusts Autoheal

Use the issuer / subject / audience from the Federated credential reference below:

az identity federated-credential create \
  --name autoheal-federation \
  --identity-name autoheal-readonly \
  --resource-group <resource-group> \
  --issuer "<AUTOHEAL_ISSUER>" \
  --subject "<AUTOHEAL_SUBJECT>" \
  --audiences "<AUTOHEAL_AUDIENCE>"

3

Assign the Reader role

Grant Reader on each subscription you want the agent to read — repeat this per subscription:

az role assignment create \
  --assignee-object-id <principalId> --assignee-principal-type ServicePrincipal \
  --role Reader --scope /subscriptions/<subscription-id>
# optional, for metrics & logs: --role "Monitoring Reader" / "Log Analytics Reader"

To cover many subscriptions at once, assign Reader once at a management group — it applies to every subscription beneath it (this needs elevated rights on that management group):

az role assignment create \
  --assignee-object-id <principalId> --assignee-principal-type ServicePrincipal \
  --role Reader --scope /providers/Microsoft.Management/managementGroups/<management-group-id>

Reader gives the agent read-only access. Assign a broader role only if you want the agent to make changes.

4

Add the integration in Autoheal

Go to Integrations → Azure Cloud → Workload Identity Federation, enter your Directory (Tenant) ID and the identity's Client ID, then Test Connection → Save. Test Connection lists the subscriptions the identity can read — confirm the ones you expect appear.

tip

Prefer an Entra app registration if your security team needs Conditional Access on the workload identity. Add the federated credential under App registrations → Certificates & secrets → Federated credentials, assign Reader to its service principal, and use the app's Application (Client) ID.

Azure Portal

1

Create a user-assigned managed identity

In the Azure Portal → Managed Identities → Create → pick a resource group and name (e.g. autoheal-readonly) → Review + create.

2

Add a federated credential that trusts Autoheal

Open the identity → Federated credentials → Add credential → scenario Other issuer, and enter the Issuer, Subject identifier, and Audience from the Federated credential reference below.

3

Assign the Reader role

On each subscription you want the agent to read, go to Subscription → Access control (IAM) → Add role assignment → Reader, and assign it to the identity. (Add Monitoring Reader / Log Analytics Reader for metrics and logs.) To cover many subscriptions at once, assign Reader at a management group instead — it applies to every subscription beneath it.

4

Add the integration in Autoheal

Go to Integrations → Azure Cloud → Workload Identity Federation, enter your Directory (Tenant) ID and the identity's Client ID, then Test Connection → Save. Test Connection lists the subscriptions the identity can read.

Federated credential reference

Set the federated credential to these values:

• Issuer — https://app.autoheal.ai
• Subject — coming soon on the Autoheal integration page (the per-tenant value Azure matches on sub)
• Audience — <your-tenant-slug>-oidc-service — your Autoheal organization slug followed by -oidc-service

info

Azure validates the assertion's iss / sub / aud against these values, so they must match exactly. Azure accepts a custom audience — it need not be api://AzureADTokenExchange.

Network requirements

• Microsoft Entra → Autoheal's OIDC issuer (/.well-known/openid-configuration + JWKS) — so Entra can validate the federated assertion.
• Agent sandbox → login.microsoftonline.com, management.azure.com — for az login and read-only az commands.

Federation needs Microsoft Entra to reach Autoheal's issuer over the public internet. For a self-hosted Azure VM (including air-gapped), use the Self-hosted (BYOC) tab instead — it talks only to the VM's local metadata service.

Self-hosted (BYOC)

When you run Autoheal yourself on an Azure VM (Bring Your Own Cloud), connect with the VM's managed identity: attach the identity to the VM once and grant it Reader on the subscriptions you want the agent to read. There are no values to enter in Autoheal — it uses the VM's identity automatically.

Prerequisites

• Autoheal running on an Azure VM.
• Permission to create/attach a managed identity and assign it the Reader role on the subscriptions you want the agent to read (or once at a management group).
• SSH access to the VM (to edit its .env config).

Azure CLI

1

Create the managed identity

From a shell signed in to your subscription:

RG=<your-resource-group>; VM=<your-autoheal-vm>; SUB=<a-subscription-id>
az identity create -g "$RG" -n autoheal-reader

2

Attach it to the VM

az vm identity assign -g "$RG" -n "$VM" \
  --identities "$(az identity show -g "$RG" -n autoheal-reader --query id -o tsv)"

3

Assign the Reader role

Grant Reader on each subscription you want the agent to read (repeat per subscription), or once at a management group to cover all of them:

PRINCIPAL_ID=$(az identity show -g "$RG" -n autoheal-reader --query principalId -o tsv)
# per subscription (repeat with each subscription id):
az role assignment create --assignee-object-id "$PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal --role Reader --scope "/subscriptions/$SUB"
# or once at a management group (covers every subscription beneath it):
az role assignment create --assignee-object-id "$PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal --role Reader \
  --scope /providers/Microsoft.Management/managementGroups/<management-group-id>

4

Point Autoheal at the identity, then restart

SSH into the Autoheal VM, resolve the identity's client ID, and add it to your .env config:

CLIENT_ID="$(az identity show -g "$RG" -n autoheal-reader --query clientId -o tsv)"
printf 'AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID=%s\n' "$CLIENT_ID" | sudo tee -a /opt/autoheal/.env

Then restart Autoheal so it picks up the change.

warning

Write the resolved GUID into .env, not the $(az identity show …) command itself — the .env file isn't a shell.

5

Add the integration in Autoheal

Go to Integrations → Azure Cloud → Managed Identity and click Test Connection → Save — there are no values to enter. Test Connection lists the subscriptions the identity can read.

Azure Portal

1

Create the managed identity

In the Azure Portal → Managed Identities → Create → pick a resource group and a name (e.g. autoheal-reader) → Review + create.

2

Attach it to the VM

Open your VM → Security → Identity → User assigned → Add, search for the identity by name, and add it.

3

Assign the Reader role

On each subscription you want the agent to read, go to Subscription → Access control (IAM) → Add role assignment → Reader → Managed identity, then search for the identity by name. Assign it on the subscription (not the VM) so the agent can read across the whole subscription. To cover many subscriptions at once, assign Reader at a management group instead.

4

Point Autoheal at the identity, then restart

Copy the identity's Client ID (open the managed identity → Properties → Client ID).

SSH into the Autoheal VM and add it to your .env config:

# /opt/autoheal/.env
AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID=<client-id-guid>

Then restart Autoheal so it picks up the change.

5

Add the integration in Autoheal

Go to Integrations → Azure Cloud → Managed Identity and click Test Connection → Save — there are no values to enter. Test Connection lists the subscriptions the identity can read.

Prefer a system-assigned identity? Enable it on the VM's Security → Identity blade instead of creating one — Azure creates it and ties it to the VM, so the VM has a single identity and you leave AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID unset (Autoheal uses it automatically).

info

The agent sandbox runs as a container on the VM and reaches the identity through the local metadata service at 169.254.169.254. If Test Connection fails, confirm reachability from inside a sandbox container:

curl -s -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://management.azure.com/"

A JSON token response means it works; a timeout means the VM's container networking is blocking link-local egress — allow 169.254.169.254 from the sandbox network.

Multiple subscriptions

One identity covers every subscription you grant it Reader on, so a single Azure Cloud integration spans all of them — there's no per-subscription integration.

• Grant access per subscription (repeat the Reader assignment for each), or once at a management group so every subscription beneath it is covered automatically.
• The agent has no default subscription. It targets one explicitly per query: it reads the subscription from the alert's resource when present, otherwise from the subscription map you can label during setup, and uses Resource Graph (az graph query) to search across all of them when the subscription is unknown.
• Scope it down by removing the Reader role on any subscription you don't want the agent to touch — what it can read is exactly what the identity can read.

Limitations

• Single Entra tenant. One integration covers subscriptions in one Microsoft Entra tenant. Subscriptions in a different tenant need a separate identity and a separate integration.
• Control-plane reads by default. Data-plane reads (blob contents, Key Vault secret values) need separate, opt-in data roles.
• One identity for everything. Use the same identity for Azure Cloud and the Azure DevOps integration — grant it Reader on your subscriptions and add it to each Azure DevOps organization with read access. One identity, one Client ID, used everywhere: the agent's sandbox shares one az session, so two different identities would conflict.

info

This is the Azure Cloud integration (Azure Resource Manager, management.azure.com). It is separate from Azure DevOps (dev.azure.com — repos, pipelines, wiki). Both use the az CLI but are distinct integrations.

Example questions

Once connected, you can ask the agent:

List the resource groups and the VMs running in the prod resource group

Show the status and node pools of our AKS clusters

What's the CPU usage of the <service-name> VM over the last hour?

Query the Activity Log for failed deployments in the last 24 hours

Troubleshooting

Managed Identity: Test Connection fails / 'Please run az login'

Confirm the managed identity is attached to the Autoheal VM and that the sandbox can reach 169.254.169.254 (see the metadata-service check above). For a user-assigned identity, confirm AZURE_BYOC_MANAGED_IDENTITY_CLIENT_ID in .env is a concrete GUID (not a $(…) command) and that you restarted Autoheal.

WIF: Test Connection fails with AADSTS70021

The federated credential's issuer / subject / audience don't match Autoheal's, or it was just created. Re-check them against the Federated credential reference in the Autoheal Cloud (SaaS) tab and retry shortly — propagation can take a few minutes.

Test Connection succeeds but shows no subscriptions

The identity authenticated but has Reader on nothing yet. Add the role assignment — on a subscription, or at a management group above it — and retry (assignments take a minute to propagate).

Test Connection shows fewer subscriptions than expected

The identity has Reader on only some of them. Grant Reader on each missing subscription (or once at a management group above them) and retry — new assignments take a minute to propagate.

403 / access denied

The identity lacks the Reader role on that subscription. Add the role assignment — on the subscription, or at a management group above it — and retry (assignments take a minute to propagate).

Can list resources but not metrics or logs

Add Monitoring Reader (for az monitor metrics list) and Log Analytics Reader (for az monitor log-analytics query).

How to revoke Autoheal's access

Delete the federated credential (SaaS) or detach the managed identity (BYOC), or remove the Reader role assignment.