Microsoft

Connect Microsoft from Settings > Integrations to let SubImage sync Entra identities, Intune devices, Office 365 licensing, and Azure resources without registering an application of your own.

What SubImage Does

SubImage publishes a single multi-tenant Entra application. A tenant administrator grants it admin consent once, which creates a service principal in your directory and grants the read-only Microsoft Graph permissions listed below. SubImage then authenticates as that application against your directory, using its own client credentials, and never asks you to create or paste a client ID or client secret.

One consent serves both Microsoft sync modules:

• the microsoft module reads Entra, Intune, and Office 365 through Microsoft Graph
• the azure module reads your Azure subscriptions through Azure Resource Manager

Consent is enough for the first. It is not enough for the second: admin consent creates the service principal but grants it no Azure role. See Azure role assignment.

SubImage requests application permissions rather than a signed-in user's delegated permissions. A delegated grant would be limited to whatever that one person can see and would stop working when they leave, which produces an inventory that is quietly incomplete rather than visibly broken.

Requested Graph Permissions

All ten are read-only application permissions. Six are required; without them the sync fails. Four are optional in the sense that the sync continues without them and silently omits the data they cover, so SubImage requests them together in one consent screen.

SubImage requests no write permission on any Microsoft surface.

Declining an optional permission produces a sync that reports success with that dataset missing, rather than an error. If Entra directory roles or Intune devices are absent from your inventory, check that its permission was consented.

SubImage Setup

1. Install Microsoft from Settings > Integrations. You must be a tenant administrator in Microsoft Entra to grant consent.
2. Review the permissions on the Microsoft consent screen and accept.
3. SubImage verifies the consent and records your directory. The microsoft module is now configured; open it and run a sync.
4. For Azure resource inventory, continue with the role assignment below.

Azure Role Assignment

Admin consent creates the SubImage service principal in your directory but grants it no Azure Resource Manager role, so it can authenticate to Azure and see nothing. Grant it Reader, then run Check Azure access in the azure module configuration. The module reports itself configured once that check finds at least one readable subscription.

Azure portal

The azure module configuration carries two deploy buttons, both prefilled: one grants Reader on a subscription you pick, the other on a management group and every subscription under it. Take the second if you have more than a handful of subscriptions.

Either needs Owner on the target, or Contributor plus User Access Administrator. The links are signed and expire after an hour; reopen the module configuration for fresh ones.

Finding the service principal object ID

The buttons above carry it already. Assigning the role by hand needs it, and the commands below call it <SERVICE_PRINCIPAL_OBJECT_ID>.

It is the object ID of the SubImage entry under Microsoft Entra ID > Enterprise applications in your own directory. Admin consent creates it, so it exists only after you have consented.

az ad sp list --filter "displayName eq 'SubImage'" --query "[0].id" --output tsv

Role assignments target this object ID. They do not take the application ID, which names SubImage's own registration rather than the principal in your directory, and an assignment made against it grants nothing.

One subscription

az role assignment create \
  --assignee-object-id <SERVICE_PRINCIPAL_OBJECT_ID> \
  --assignee-principal-type ServicePrincipal \
  --role Reader \
  --scope /subscriptions/<SUBSCRIPTION_ID>

Several at once

Reader on a management group above your subscriptions inherits to all of them, including ones added later, and also makes the management-group hierarchy readable. Scope it to a group that covers what you want scanned.

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

The tenant root group is the exception. It starts with no assignments at all, not even for a Global Administrator, who has to turn on access management for Azure resources first. That elevation grants Microsoft.Authorization/* and no deployment rights, so it is enough for the command above and not for the deploy button.

If you scope Reader to individual subscriptions instead, the management-group hierarchy stays unreadable. Add Management Group Reader on the groups you want in inventory. On its own it grants no subscription, so it never makes the module runnable.

Terraform

variable "subimage_principal_id" {
  type        = string
  description = "SubImage service principal object ID, from the azure module configuration."
}

variable "subimage_subscription_ids" {
  type        = list(string)
  description = "Subscriptions SubImage should be granted Reader on."
}

resource "azurerm_role_assignment" "subimage_reader" {
  for_each             = toset(var.subimage_subscription_ids)
  scope                = "/subscriptions/${each.key}"
  role_definition_name = "Reader"
  principal_id         = var.subimage_principal_id
  principal_type       = "ServicePrincipal"
}

Optional data-plane roles

Reader covers Azure Resource Manager but grants no data-plane access:

• Key Vault Reader on each RBAC-enabled vault, to inventory secret, key, and certificate metadata without reading any value. Vaults on legacy access policies need only list for secrets, keys, and certificates.
• Synapse Artifact User on each Synapse workspace, to inventory published pipelines and linked services. Without it SubImage still inventories the workspace and its resources.

Revoking Access

Delete the SubImage enterprise application from Microsoft Entra > Enterprise applications, or remove the installation from Settings > Integrations.

Deleting the enterprise application stops SubImage acquiring any token for your directory. Both sync modules then report a configuration error naming the revoked consent, rather than failing silently.

Removing the Azure role assignments without revoking consent leaves Entra sync working and stops Azure resource inventory.

Bring Your Own Application

Registering your own Entra application is still supported, and is the path to use when your organization does not permit consenting to a vendor multi-tenant application. Configure the credential fields directly in the module instead; see the Microsoft module setup guide and the Azure module setup guide.

Credentials configured on the module take precedence over the integration, so a tenant that already pastes its own is unaffected by installing this integration.

Troubleshooting

If consent appears to succeed but SubImage reports it could not be verified, the grant may still be propagating in Microsoft. Retry the installation after a minute.

If the azure module stays unconfigured after consent, the service principal has no Azure role. Assign the roles above and run Check Azure access again.

If Entra directory roles or Intune devices are missing from an otherwise successful sync, the corresponding optional permission was not consented. Reinstall Microsoft to present the consent screen again.