Skip to main content
Version: 0.4 · current

Connect Azure Monitor

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

Connect Azure Monitor to bring your Azure resources into Excubius with their platform metrics, fired alerts, Data Factory runs and expiring secrets. This guide shows the least-privilege roles on the Azure side, how to add the source and how to receive alerts through an action group.

Before you begin​

  • You need the Entity admin role on the entity the subscriptions belong to.
  • In Azure, someone who can assign roles on the subscriptions, and, for app registration expiry, grant admin consent in Entra ID.
  • The feature sources.azure_monitor is on. See Sources.

What Excubius reads​

Azure is read through Azure Resource Manager, Resource Graph, Azure Monitor, Alerts Management, Data Factory, the Key Vault data plane and Microsoft Graph. Every call reads; the few POST requests are queries, such as a Resource Graph query, a pipeline or trigger run query, or an integration runtime status.

PhaseWhatDefault interval
InventoryOne Resource Graph query over the subscriptions, limited to the resource types you choose15 minutes
MetricsThe checks of the Azure module (platform metrics and Resource Graph rows such as backup jobs), VPN tunnel state and, each switchable, the Data Factory checks, Key Vault expiry and app registration secret expiry5 minutes
AlertsFired Azure Monitor alerts of the last 30 days, by target resource5 minutes in Polling; reconciliation every 15 minutes in Hybrid

Choose the identity​

IdentityUse it when
The server's managed identity (recommended)The Excubius server runs in Azure and its identity can reach the subscriptions. Nothing to store or rotate. It is the VM's system-assigned identity, or a user-assigned one when AZURE_CLIENT_ID in the .env file names it
A service principalThe subscriptions are in a tenant the server's identity cannot reach. An app registration with a client secret; rotate the secret before it expires

When the .env file sets all of AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET, the server uses that service principal instead of its managed identity.

Grant the permissions​

Grant only what the options you use need. Role IDs are those of the Azure built-in roles.

ForRole or permissionRole IDScope
Inventory and alertsReaderacdd72a7-3385-48ef-bd42-f606fba81ae7Each subscription, or a management group
Platform metricsMonitoring Reader43d0d8ad-25c7-4714-9337-8ba259a9fe05Same
Data Factory runs, trigger runs, integration runtime statusCustom role Data Factory run reader, belowCreated in your tenantThe factories, or their resource groups
Key Vault expiryKey Vault Reader for vaults with Azure RBAC, or an access policy with List on secrets, keys and certificates21090545-7ca7-4776-b22c-e363652d74d2Each vault
App registration expiryMicrosoft Graph application permission Application.Read.All, with admin consent—The tenant

For example, for the server's managed identity on one subscription:

az role assignment create --assignee <principal-id> --role "Reader" \
--scope /subscriptions/<subscription-id>
az role assignment create --assignee <principal-id> --role "Monitoring Reader" \
--scope /subscriptions/<subscription-id>

A read-only role for Data Factory​

Data Factory exposes its run history as actions. Reader does not include them, and the built-in Data Factory Contributor would grant them together with write access. A custom role keeps it read-only. Save this as data-factory-run-reader.json:

{
"Name": "Data Factory run reader",
"Description": "Read Data Factory pipelines, triggers, runs and integration runtime status.",
"Actions": [
"Microsoft.DataFactory/factories/read",
"Microsoft.DataFactory/factories/pipelines/read",
"Microsoft.DataFactory/factories/triggers/read",
"Microsoft.DataFactory/factories/integrationruntimes/read",
"Microsoft.DataFactory/factories/querypipelineruns/action",
"Microsoft.DataFactory/factories/querytriggerruns/action",
"Microsoft.DataFactory/factories/integrationruntimes/getstatus/action"
],
"NotActions": [],
"AssignableScopes": ["/subscriptions/<subscription-id>"]
}

Then create and assign it:

az role definition create --role-definition data-factory-run-reader.json
az role assignment create --assignee <principal-id> --role "Data Factory run reader" \
--scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>

Without this role everything else works, and Test lists Data Factory as an optional permission that failed.

Add the source​

  1. Open Settings › Sources, select Add a source and choose Azure Monitor.
  2. Under General, enter a Name and choose the Entity.
  3. Under Identity, choose The server's managed identity or A service principal. For a service principal, enter the Tenant ID, the Client ID and the Client secret.
  4. Under Subscriptions, enter the subscription IDs, one per line, or leave it empty to read every subscription the identity can read. Listing them is how you split one tenant between several client entities.
  5. Under Resource types, keep the types you want: virtual machines, Azure SQL databases, SQL managed instances, PostgreSQL flexible servers, storage accounts, key vaults, Recovery Services vaults, data factories, and network gateways, firewalls and load balancers.
  6. Choose what to read: Platform metrics, Fired alerts and Data Factory runs are on by default; Key Vault secret expiry and App registration secret expiry are off until you grant their permissions.
  7. Set the Time zone where "today" starts for the Data Factory summary, for example America/Santo_Domingo.
  8. Under Ingest mode, choose Hybrid (recommended) when your alert rules can reach the Excubius server, or Polling otherwise.
  9. Select Create source and copy the webhook URL. It is shown only once.

Receive alerts through an action group​

In Hybrid or Webhook only mode:

  1. In Azure Monitor, create an action group with a Webhook action to the URL Excubius showed, and switch on the common alert schema.
  2. Use that action group in the alert rules whose alerts you want in Excubius.
warning

Action groups cannot add headers, so the token in the URL is the credential. Keep the URL private, and select Rotate URL on the source if it leaks.

Test and sync​

  1. On the source page, select Test. Each read is listed with its result, optional ones marked: credentials, subscriptions, inventory, alerts, metrics, Data Factory, Key Vault and app registrations.
  2. Select Sync now to bring resources, metrics and alerts in without waiting.

Azure resources appear under the source's entity, matched with the same servers from other sources by their resource ID and names. Each data factory gets a card on the Overview, and secrets that expire within 30 days appear under Expiry and risk.