setup

Microsoft Azure

tip

Set up with an AI agent Using Claude Code, Cursor, Codex CLI, or another coding agent? The subimage-setup:connect-azure skill walks the agent through every choice on this page. Paste this into your agent:

Use curl to download, read and follow: https://skills.subimage.io/plugins/subimage-setup/skills/connect-azure/SKILL.md

Or install the marketplace once with claude plugin marketplace add subimagesec/skills. Full instructions on Agent Skills.

Purpose

Inventories subscriptions, resource groups, compute instances, networking resources, and IAM objects inside your Azure tenant.

The simplest setup registers no application at all. Connect Microsoft from Settings > Integrations, then assign Azure roles to the service principal that consent creates.

Consent alone does not configure this module. It provisions the service principal in your directory but grants it no Azure role, so it can authenticate and see no subscriptions. After consenting, open this module's configuration and use a deploy button, or assign Reader yourself following the Microsoft integration guide, then run Check Azure access. The module reports itself configured once that check finds at least one readable subscription.

The Microsoft integration guide carries ready-to-run Azure CLI, ARM, and Terraform snippets for the assignment.

The rest of this page covers registering your own service principal instead.

tip

Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.

Fields

Leave these empty when Microsoft is connected through admin consent. When set, they take precedence over the integration.

Field Secret? Description
azure_tenant_id No Azure Directory / Tenant ID
azure_client_id No Application (client) ID of the registered service principal
azure_client_secret Yes Client secret generated under Certificates & secrets

For a one-time delegated sync, leave the client ID and client secret empty and use these instead:

Field Secret? Description
azure_delegated_auth No Run with a signed-in user's Azure Resource Manager token
azure_delegated_access_token Yes JSON output of az account get-access-token for Azure Resource Manager

Bring your own service principal

  1. Create the application / service principal with the Reader role on each subscription you want to scan:

    az ad sp create-for-rbac \
        --name subimage-sp \
        --role Reader \
        --scopes /subscriptions/<SUB_ID>  # repeat or elevate as needed

    Copy the appId, password, and tenant values.

  2. Get the service principal's object ID. Azure role assignments should target this object ID, not the application registration's object ID:

    az ad sp show --id <appId> --query id --output tsv
  3. Grant the service principal a management-group-scoped read role so Subimage can read the management-group hierarchy, subscription placement, and management-group role assignments. Assign Management Group Reader at the Tenant Root Group (or another scope broad enough to cover the management groups you want to sync):

    az role assignment create \
        --assignee-object-id <SERVICE_PRINCIPAL_OBJECT_ID> \
        --assignee-principal-type ServicePrincipal \
        --role "Management Group Reader" \
        --scope /providers/Microsoft.Management/managementGroups/<TENANT_ROOT_GROUP_ID>
  4. In Subimage, fill in:

    • azure_tenant_id: the tenant from step 1
    • azure_client_id: the appId from step 1
    • azure_client_secret: the password from step 1 (or its AWS Secret ARN)
  5. Save the module. Subimage scans every subscription visible to the service principal; control the scope with its Azure role assignments.

Selective Sync

azure_requested_syncs limits a sync to some Azure resources, for example just rbac to pull role assignments and role definitions, or one resource type that is slow or failing in a large estate. Leave it empty to sync everything.

Valid values are management_groups, compute, cosmosdb, app_service, functions, event_grid, logic_apps, rbac, workload_identity, sql, storage, resource_groups, key_vaults, aks, event_hub, data_factory, data_lake, network, container_instances, firewall, load_balancers, application_gateways, synapse, monitor, security_center, and permission_relationships.

Notes:

  • The tenant and its subscriptions always sync, because every other Azure node is attached to them.
  • Resources you don't select are neither synced nor cleaned up, so their existing graph data stays as it was.
  • workload_identity and permission_relationships are built from data other resources load. Relationships to resources you don't select only form if those resources are already in the graph. Run a full sync first when you can.

One-time delegated sync

Use delegated authentication only when you can't grant admin consent or create a service principal, and need a snapshot of the Azure resources a signed-in user can read. It doesn't grant the user additional permissions, and it isn't a replacement for a service principal.

Delegated authentication has these limitations:

  • Coverage is limited to what the user can read through their Azure role assignments. Subimage syncs every subscription the user can see, and removes subscriptions from earlier runs that the user can't see, as it would for a service principal that lost access.
  • The token reaches Azure Resource Manager only. Key Vault secrets, keys, and certificates, and Synapse pipelines and linked services, use separate data-plane tokens, so they aren't synced. Key vault contents from earlier runs are left in place. Key vaults and Synapse workspaces themselves still sync.
  • The access token can't be refreshed, and the sync stops once it expires. Use this mode for an attended, one-time run, and keep the module's schedule set to Manual.

To run a delegated sync:

  1. On a trusted workstation, sign in to the target tenant with the user whose access you want to inventory:

    az login --tenant '<TENANT_ID>'
  2. Get an Azure Resource Manager access token as JSON, immediately before the run:

    az account get-access-token \
      --tenant '<TENANT_ID>' \
      --resource https://management.azure.com \
      --query '{accessToken: accessToken, expires_on: expires_on}' \
      --output json

    Copy the entire JSON object. This is the same format the microsoft module's delegated sync uses, but the token is different: an Azure Resource Manager token can't read Entra, and a Microsoft Graph token can't read Azure. Before the sync starts, Subimage checks that the token was issued for Azure Resource Manager, hasn't expired, and belongs to the module's tenant ID.

    Treat this output like a password. Don't put it in shell history, logs, tickets, or chat messages.

  3. In the azure module, set the schedule to Manual, enter the tenant ID, enable delegated authentication, and paste the JSON output into the delegated access-token field. Leave the client ID and client secret empty.

  4. Save the module, then select Run sync.

  5. After the run finishes, disable delegated authentication, clear the delegated access token, and save the module again. Disable delegated mode before clearing the field, because delegated authentication requires a token.

Subimage stores the pasted JSON in the configured secret provider and sends only the accessToken value to Azure. It doesn't return the value to the browser after you save it. Replace it before each later run.

Additional permissions for complete inventory

The subscription Reader role covers Azure Resource Manager inventory, but it does not grant data-plane access:

  • To inventory Key Vault secret, key, and certificate metadata without reading sensitive values, assign Key Vault Reader on each RBAC-enabled vault or at a parent scope. For vaults using legacy access policies, grant only list for secrets, keys, and certificates.
  • To inventory published Synapse pipelines and linked services, assign Synapse Artifact User on each Synapse workspace. Without it, Subimage still inventories the workspace and its ARM resources but omits those artifacts.

Notes

  • Reader on a management group covers both the subscriptions beneath it and the management-group hierarchy, because it grants */read over that scope. Scoped to individual subscriptions instead, it leaves the hierarchy unreadable; add Management Group Reader on the groups you want in inventory.
  • For Entra ID and Intune objects, also connect the microsoft module.