setup

Microsoft Graph (Entra + Intune + O365 + Defender)

Purpose

Ingests users, groups, service principals, role assignments, managed devices, detected apps, compliance policies, and Office 365 licensing (subscribed SKUs, service plans, and per-user license assignments) from Microsoft Graph, plus Microsoft Defender for Endpoint machines and unresolved alerts when the tenant grants access. Combine with the azure module for a complete view of identity, application, and device access across your Microsoft estate.

The simplest setup registers no application at all. A tenant administrator grants admin consent to Subimage's multi-tenant Entra application once, and this module needs no credential fields.

Connect Microsoft from Settings > Integrations, then run a sync here. For what each grant unlocks, including Azure resources and Defender for Endpoint machines, see How the Microsoft connection works. The same guide lists each permission and why Subimage requests it.

The rest of this page covers registering your own application instead, which is the path to use when your organization does not permit consenting to a vendor multi-tenant application.

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.

These credentials drive upstream Cartography's canonical --microsoft-* args for Microsoft (Entra ID + Intune + O365) ingestion. The legacy --entra-* args remain accepted as deprecated aliases; the Subimage field names below stay entra_*.

Field Secret? Description
entra_tenant_id No Directory / Tenant ID
entra_client_id No Application (client) ID of a registered app
entra_client_secret Yes Client secret for the registered app

Selective Sync

microsoft_requested_syncs limits a sync to some Microsoft resources. This helps in a large tenant when one dataset is slow or failing and you want to run it by itself. Leave it empty to sync everything.

Valid values are users, groups, administrative_units, applications, service_principals, app_role_assignments, directory_roles, federation, intune, o365, defender_machines, and defender_alerts. You can pick Entra and Defender datasets one at a time. Intune and O365 always sync as a whole.

Notes:

  • The Entra tenant always syncs, because every other Microsoft node is attached to it.
  • Resources you don't select are neither synced nor cleaned up, so their existing graph data stays as it was.
  • Relationships to resources you don't select only form if those resources are already in the graph. Run a full sync first.
  • Delegated authentication syncs Entra only, so selecting intune or o365 with it has no effect. Defender is skipped too.

Defender for Endpoint

The module also ingests Microsoft Defender for Endpoint machine inventory and unresolved Defender for Endpoint alerts. Alerts link to the machines in their evidence, machines link to the matching Intune managed devices, and alerts appear as security issues alongside other providers' findings.

There's no setting to turn on. Defender syncs when the application has these read-only application permissions, granted with admin consent:

Dataset API Permission Data
defender_machines WindowsDefenderATP (APIs my organization uses) Machine.Read.All Defender for Endpoint machine inventory
defender_alerts Microsoft Graph SecurityAlert.Read.All Unresolved Defender for Endpoint alerts

If the tenant doesn't have Defender for Endpoint, or a dataset's permission is missing, the sync skips that dataset, logs why (naming the permission when a request is denied), and keeps any Defender data from earlier syncs. Only commercial cloud endpoints are supported.

With admin consent, alerts come from the main Subimage application and machines need the separate Microsoft Defender for Endpoint integration; see the Microsoft integration guide. With your own application, add both permissions to it.

One-time delegated sync

Use delegated authentication only when you can't grant application consent and need a best-effort snapshot of the Entra data visible to a signed-in user. This mode doesn't grant the user additional permissions, and it isn't a replacement for application authentication.

Delegated authentication has these limitations:

  • It attempts Entra datasets only. It skips Intune and Office 365.
  • Microsoft Graph can omit fields or related objects without returning an authorization error. A successful run doesn't prove that the user could read every object.
  • When Graph returns 403 Forbidden for a dataset, Cartography preserves any records already loaded, continues with the next dataset, and Subimage marks the run as Degraded. A denial for one group member or owner can instead omit that relationship and let the dataset continue.
  • Cleanup is disabled. A run doesn't delete Entra data that the user can't see.
  • The access token expires quickly. Use this mode for an attended, one-time run, and keep the module's schedule set to Manual.

To run a delegated sync:

  1. If you need to identify the tenant ID for the Azure CLI command, inspect the currently selected account context. This command is read-only and does not display an access token or secret:

    az account show \
      --query '{tenantId:tenantId,tenantName:tenantDisplayName,subscriptionId:id,subscriptionName:name}' \
      --output json

    Use the tenantId GUID, not the tenant display name, in the commands below. The subscription fields are informational; delegated authentication can also work in a tenant with no subscriptions.

  2. On a trusted workstation, sign in to the target tenant with the user whose visibility you want to test:

    az login --tenant '<TENANT_ID>' --allow-no-subscriptions

    If a browser can't open, add --use-device-code. Your tenant's Conditional Access policy might not allow device-code authentication.

  3. Get a Microsoft Graph access token as JSON:

    az account get-access-token \
      --tenant '<TENANT_ID>' \
      --resource-type ms-graph \
      --query '{accessToken: accessToken, expires_on: expires_on}' \
      --output json

    Copy the entire JSON object, not just the accessToken value. Microsoft Graph access tokens are opaque and aren't always readable JWTs, so Subimage reads the expiry from this response instead of from the token. It uses expires_on, a UTC POSIX timestamp, rather than the local-time expiresOn field. Before the sync starts, Subimage asks Microsoft Graph which tenant issued the token and checks that it matches the module's tenant ID.

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

  4. In the microsoft 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.

  5. Save the module, then select Run sync.

  6. After the run finishes, disable delegated authentication, clear the delegated access token, and save the module again. The token is short-lived, but clearing it also removes the stored credential reference. Disable delegated mode before clearing the field because delegated authentication requires a token. Clear this field before switching back to application authentication.

Subimage stores the pasted JSON in the configured secret provider and sends only the accessToken value to Microsoft Graph. It doesn't return the value to the browser after you save it. Replace it before each later run because an expired token causes the sync to stop.

To inventory Azure resources with the same user, run the Azure delegated sync with a separate Azure Resource Manager token. A Microsoft Graph token can't read Azure.

Bring your own application

  1. Register a new App registration in Azure Portal → Entra ID.
  2. Under API permissions, add the following Application permissions and grant admin consent:
    • AdministrativeUnit.Read.All
    • Application.Read.All
    • DeviceManagementApps.Read.All
    • DeviceManagementConfiguration.Read.All
    • DeviceManagementManagedDevices.Read.All
    • Directory.Read.All
    • Group.Read.All
    • GroupMember.Read.All
    • RoleManagement.Read.Directory
    • User.Read.All
    • AuditLog.Read.All (optional): Entra user sign-in activity and MFA registration. Requires an Entra ID P1 or P2 license. Without it, users still sync but their sign-in timestamps and MFA registration are empty.
    • IdentityRiskyUser.Read.All (optional): Entra ID Protection user risk. Requires an Entra ID P2 license.
    • IdentityRiskyServicePrincipal.Read.All (optional): Entra ID Protection risk for service principals. Requires a Microsoft Entra Workload ID Premium license.
    • SecurityAlert.Read.All (optional): Defender for Endpoint alerts (defender_alerts).
    • WindowsDefenderATP Machine.Read.All (optional): Defender for Endpoint machine inventory (defender_machines). Add it from APIs my organization uses > WindowsDefenderATP.
  3. Generate a Client Secret under Certificates & secrets.
  4. In Subimage, fill in the fields above (use the client secret or its AWS Secret ARN for entra_client_secret) and save the module.

Authenticates via the OAuth 2.0 client credentials flow.