microsoft

Microsoft

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

How the Microsoft connection works

Each kind of Microsoft data needs its own grant. Start with the first row, then add the rows you need.

To sync Grant Used by
Entra identities, Intune devices, Office 365 licensing, and Defender for Endpoint alerts Admin consent to the Subimage application: install Microsoft from Settings > Integrations microsoft module
Azure resources The Reader role for the Subimage service principal on your subscriptions azure module
Defender for Endpoint machines Admin consent to the Subimage – Defender for Endpoint application: install Microsoft Defender for Endpoint from Settings > Integrations microsoft module

Keep the following in mind:

  • One admin consent serves both the microsoft and azure modules. Azure access is a role assignment, not a permission, so consent alone doesn't let Subimage see your subscriptions. See Azure role assignment.
  • Defender for Endpoint machines use a separate application so that connecting Microsoft keeps working in tenants without Defender for Endpoint. See Defender for Endpoint.
  • If your organization doesn't allow consent to vendor applications, register your own application instead. See Use your own application.
  • For an attended assessment where application consent isn't possible, the microsoft module provides a limited one-time delegated sync that reads Entra only.

What Subimage does

Subimage publishes a multi-tenant Entra application. When a tenant administrator grants it admin consent, Entra creates a service principal in your directory with the read-only Microsoft Graph permissions listed below. Subimage then authenticates as that application against your directory with its own client credentials, so you never create or paste a client ID or client secret.

Subimage requests application permissions rather than a signed-in user's delegated permissions. A delegated grant is limited to what one person can see and stops working when that person leaves, which produces an inventory that is incomplete without any visible error.

Requested Graph permissions

All fourteen are read-only application permissions. Six are required; without them, the sync fails. Eight are optional: without them, the sync continues and omits the data they cover. Subimage requests all of them on one consent screen.

Permission Why Subimage needs it Required
Directory.Read.All Reads the directory itself and the subscribed SKUs behind Office 365 licensing Yes
User.Read.All Reads Entra users and their assigned licenses Yes
Group.Read.All Reads groups Yes
GroupMember.Read.All Reads group members and owners, which is what makes group-based access analyzable Yes
Application.Read.All Reads applications, service principals, and app role assignments Yes
AdministrativeUnit.Read.All Reads administrative units Yes
RoleManagement.Read.Directory Reads directory role definitions and assignments, the basis for privilege analysis in Entra No
DeviceManagementManagedDevices.Read.All Reads Intune managed devices No
DeviceManagementConfiguration.Read.All Reads Intune compliance policies No
DeviceManagementApps.Read.All Reads the Intune detected-apps report No
SecurityAlert.Read.All Reads unresolved Defender for Endpoint alerts No
AuditLog.Read.All Reads Entra user sign-in activity and MFA registration No
IdentityRiskyUser.Read.All Reads the users Entra ID Protection flags as risky No
IdentityRiskyServicePrincipal.Read.All Reads the service principals Entra ID Protection flags as risky No

Subimage requests no write permission on any Microsoft surface.

Three optional permissions also need a Microsoft license before they return any data. Without the license, consent still succeeds and the sync continues without that data:

  • AuditLog.Read.All: Entra ID P1 or P2
  • IdentityRiskyUser.Read.All: Entra ID P2
  • IdentityRiskyServicePrincipal.Read.All: Microsoft Entra Workload ID Premium

MFA registration and Entra ID Protection risk are where attack paths start in Entra: a user with no MFA registered, or one Microsoft already flags as compromised.

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.

Connect Microsoft

To grant consent, you must be a tenant administrator in Microsoft Entra.

  1. In Settings > Integrations, select Install for Microsoft.
  2. Review the permissions on the Microsoft consent screen, and then select Accept.
  3. Subimage verifies the consent and records your directory. Open the microsoft module and run a sync.
  4. Optional: to sync Azure resources, assign the role in Azure role assignment.
  5. Optional: to sync Defender for Endpoint machines, follow Defender for Endpoint.

Defender for Endpoint

Defender for Endpoint machine inventory uses a second Subimage application, Subimage – Defender for Endpoint. Its only permission is the read-only WindowsDefenderATP Machine.Read.All. It's separate because Microsoft rejects consent to an application that requests an API your tenant doesn't have, so adding this permission to the main application would block tenants without Defender for Endpoint from connecting Microsoft at all.

Unresolved Defender for Endpoint alerts don't need this application. They come from the main application's SecurityAlert.Read.All.

Before you begin, connect Microsoft and make sure your tenant has Defender for Endpoint.

  1. In Settings > Integrations, select Install for Microsoft Defender for Endpoint.
  2. As a tenant administrator, review the consent screen, and then select Accept.
  3. Run a microsoft module sync. It includes Defender for Endpoint machines.

When Subimage adds a permission

Entra doesn't notify you when Subimage adds a permission to its application, and your directory keeps the permissions it consented to until an administrator consents again. Until then, Subimage omits the data the new permission covers.

To grant newly added permissions, do one of the following as a tenant administrator:

  • In Settings > Integrations, select Install for Microsoft again and accept the consent screen.
  • Go to Microsoft Entra > Enterprise applications > Subimage > Permissions, and then select Grant admin consent.

Either way, the next microsoft module sync picks up the new data.

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.

The deployment first validates the ARM template and then creates a Microsoft.Authorization/roleAssignments resource. For a custom role, grant Microsoft.Resources/deployments/validate/action (or the corresponding deployment permissions) and Microsoft.Authorization/roleAssignments/write at the target scope. The built-in role combination above includes these permissions.

Find 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 subscriptions

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.

Revoke access

To revoke access, delete the Subimage enterprise applications in Microsoft Entra > Enterprise applications, or remove the installations in Settings > Integrations.

  • Deleting Subimage stops Subimage from getting any token for your directory. Both sync modules then report a configuration error that names the revoked consent.
  • Deleting Subimage – Defender for Endpoint stops Defender for Endpoint machines from syncing. Subimage keeps the data from the last sync.
  • Removing the Azure role assignments without revoking consent stops Azure resource inventory and leaves Entra sync working.

Use your own application

If your organization doesn't allow consent to a vendor multi-tenant application, register your own Entra application and enter its credentials in the module. One application can hold every permission, including the Defender for Endpoint ones, because only your tenant consents to it. For the steps, see the Microsoft module setup guide and the Azure module setup guide.

Credentials configured on a module take precedence over the integration, so installing the integration doesn't affect a module that already uses its own credentials.

Troubleshooting

  • Consent succeeds, but Subimage reports that it couldn't verify it. The grant might still be propagating in Microsoft. Wait a minute, and then retry the installation.
  • The azure module stays unconfigured after consent. The service principal has no Azure role. Assign the roles in Azure role assignment, and then select Check Azure access again.
  • Entra directory roles or Intune devices are missing after a successful sync. The matching optional permission wasn't consented. Reinstall Microsoft to show the consent screen again.
  • Defender for Endpoint alerts are missing. Grant admin consent for SecurityAlert.Read.All on the Subimage enterprise application.
  • MFA registration, sign-in activity, or Entra ID Protection risk is missing. Grant admin consent for the newly added permissions, as described in When Subimage adds a permission, and check that the tenant has the license the permission needs.
  • Defender for Endpoint consent fails with AADSTS650052. Your tenant doesn't have Defender for Endpoint.
  • Defender for Endpoint machines are missing after consent. Check that Microsoft Defender for Endpoint shows an installation for the same directory as Microsoft.