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 P2IdentityRiskyUser.Read.All: Entra ID P2IdentityRiskyServicePrincipal.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.
- In Settings > Integrations, select Install for Microsoft.
- Review the permissions on the Microsoft consent screen, and then select Accept.
- Subimage verifies the consent and records your directory. Open the microsoft module and run a sync.
- Optional: to sync Azure resources, assign the role in Azure role assignment.
- 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.
- In Settings > Integrations, select Install for Microsoft Defender for Endpoint.
- As a tenant administrator, review the consent screen, and then select Accept.
- 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 tsvRole 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
listfor 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.Allon 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.