Connecting Entra ID

Connecting your Entra tenant unlocks the full Microsoft Cloud tool set in InfraScout. Once connected, InfraScout can query your users, groups, roles, Azure subscriptions, Conditional Access policies, Defender alerts, Microsoft 365 services, and more — without requiring an agent on any of those systems.

Setup is one of two paths. Most customers use the PowerShell script InfraScout publishes — it creates the app registration, attaches all required Microsoft Graph and Defender permissions, grants admin consent, and generates a client secret in a single run. If you cannot run scripts in your environment, the manual portal walkthrough at the bottom of this page produces the same result.

What You Need

• Global Administrator, or Privileged Role Administrator plus Application Administrator, in your Entra tenant. Application Administrator alone is not sufficient — admin consent on the privileged Defender permissions requires Privileged Role Administrator or higher.
• PowerShell 7+ on Windows, macOS, or Linux. Windows PowerShell 5.1 also works.
• The Microsoft Graph PowerShell modules — the script installs them on first run if they are missing.
• A secure channel (password manager share, encrypted email) to deliver the resulting credentials to InfraScout.

Quick Path: PowerShell Script

InfraScout ships create-infrascout-customer-app.ps1 for this. The script is idempotent — re-running it with the same display name detects the existing app, re-applies permissions, and optionally rotates the secret.

What It Does

The script performs every step you would otherwise click through in the portal:

1. Installs the required Microsoft Graph PowerShell modules if they are missing.
2. Signs you in to your Entra tenant interactively.
3. Creates a single-tenant app registration (default name InfraScout Data Collection), or finds the existing one if you re-run.
4. Attaches all 48 application permissions across Microsoft Graph, Microsoft Threat Protection, and Defender for Endpoint.
5. Creates the service principal in your tenant.
6. Grants admin consent for every permission.
7. Generates a client secret with a 24-month lifetime (the Entra maximum).
8. Writes a JSON output file with the tenant ID, client ID, and client secret.

Run It

Download the script, then in PowerShell:

# 1) Save the script and unblock it on Windows
Invoke-WebRequest `
  -Uri "https://releases.infrascout.cloud/releases/infrascout/scripts/create-infrascout-customer-app.ps1" `
  -OutFile ".\create-infrascout-customer-app.ps1"
Unblock-File .\create-infrascout-customer-app.ps1

# 2) Run it (defaults are fine for most customers)
.\create-infrascout-customer-app.ps1

A browser window opens for interactive sign-in. After consent, the script logs each permission as it is granted and prints a summary on completion:

================================================================
 InfraScout customer app provisioning complete.
================================================================

 Tenant ID  : 00000000-0000-0000-0000-000000000000
 Client ID  : 11111111-1111-1111-1111-111111111111
 Secret     : (written to ./infrascout-customer-app-output.json — DO NOT COMMIT)

 NEXT STEPS:
   1. Send tenantId + clientId + clientSecret to your InfraScout operator
      (use a secure channel — password manager share, encrypted email).
   2. Operator pastes them into the InfraScout admin UI:
      Admin → Entra Connections → New connection.
   3. After the operator confirms the connection works, securely delete
      this file:
        Remove-Item ./infrascout-customer-app-output.json

DANGER

The client secret is written to ./infrascout-customer-app-output.json. Treat it like any other credential — share it through a vault, then delete the file as soon as InfraScout confirms the connection works. Do not commit it to a repository.

Script Parameters

The script accepts four optional parameters; defaults work for most customers.

Parameter	Default	Purpose
-DisplayName	InfraScout Data Collection	Display name of the app registration. Use a customer-specific name if you provision multiple environments in the same tenant (e.g. InfraScout - Prod, InfraScout - Dev).
-OutputPath	./infrascout-customer-app-output.json	Where the credential output file is written.
-GenerateSecret	$true	Generate a new client secret. Set to $false on re-runs when you only want to refresh permissions.
-SecretLifetimeMonths	24	Client secret lifetime, capped at 24 months by Entra.

Examples:

# Multi-tenant MSP scenario — distinguish customers by display name
.\create-infrascout-customer-app.ps1 -DisplayName "InfraScout - Contoso"

# Refresh permissions only, do not rotate the secret
.\create-infrascout-customer-app.ps1 -GenerateSecret $false

# Shorter-lived secret for a tightly governed tenant
.\create-infrascout-customer-app.ps1 -SecretLifetimeMonths 12

What If a Permission Fails?

The script reports Granted | Already granted | Failed at the end of the consent loop. If anything is non-zero in the Failed column:

• Most common cause — the signed-in account lacks Privileged Role Administrator. Application Administrator can attach the permissions but cannot consent to the privileged Defender ones. Sign in with a Global Administrator and re-run.
• Resource SP not found — the script auto-provisions the Microsoft Threat Protection and Defender for Endpoint service principals if they do not exist yet. Re-running the script after a few seconds usually clears the issue.
• Anything else — the script prints the underlying error message verbatim. Send that line to InfraScout support.

A Granted: 0 | Already granted: 48 summary on a re-run is the expected steady state — every permission is consented and nothing changed.

Permissions the Script Grants

The data-collection app needs read-only access across three APIs. All permissions are application (app-only) permissions; the script does not request any delegated scopes. InfraScout never writes to your directory or any of your Microsoft Cloud services.

Microsoft Graph (39 permissions)

These cover identity, devices, audit, security, and Microsoft 365 workloads.

Identity and directory

Permission	What it enables
User.Read.All	Read user profiles, MFA registration, and account state
UserAuthenticationMethod.Read.All	Read which authentication methods each user has registered
Organization.Read.All	Read tenant-level organization details and license SKUs
Domain.Read.All	Read verified and federated domains
AdministrativeUnit.Read.All	Read administrative units and their members

Groups and access lifecycle

Permission	What it enables
Group.Read.All	Read all groups, properties, and ownership
AccessReview.Read.All	Read access reviews and review decisions
EntitlementManagement.Read.All	Read access packages, catalogs, and assignments

Privileged roles and partner delegation

Permission	What it enables
RoleManagement.Read.Directory	Read directory role definitions and active assignments
RoleAssignmentSchedule.Read.Directory	Read PIM active role assignment schedules
RoleEligibilitySchedule.Read.Directory	Read PIM eligible role assignment schedules
DelegatedAdminRelationship.Read.All	Read GDAP partner delegation relationships

Apps, policies, audit, and reports

Permission	What it enables
Application.Read.All	Read app registrations and service principals
Policy.Read.All	Read Conditional Access, authentication, and authorization policies
AuditLog.Read.All	Read sign-in and audit logs
AuditLogsQuery.Read.All	Search the Microsoft 365 Unified Audit Log across Exchange, SharePoint, OneDrive, and Teams
Reports.Read.All	Read Microsoft 365 usage and activity reports

Identity protection and security signals

Permission	What it enables
IdentityRiskEvent.Read.All	Read Identity Protection risk events
IdentityRiskyUser.Read.All	Read risky user detections
SecurityAlert.Read.All	Read security alerts
SecurityAnalyzedMessage.Read.All	Read Defender for Office 365 analyzed emails (Threat Explorer data)
SecurityEvents.Read.All	Read security event signals
SecurityIncident.Read.All	Read security incidents
ThreatHunting.Read.All	Run Defender Advanced Hunting KQL queries via Microsoft Graph, including the Security Exposure Management attack graph
CloudApp-Discovery.Read.All	Read Defender for Cloud Apps Cloud Discovery (shadow IT) data
SecurityIdentitiesHealth.Read.All	Read Defender for Identity health issues across the hybrid-identity infrastructure
SecurityIdentitiesSensors.Read.All	Read the Defender for Identity sensor inventory and its deployment health
AttackSimulation.Read.All	Read Defender for Office 365 phishing-simulation campaigns, per-user outcomes, and coverage reports

Microsoft 365 workloads

Permission	What it enables
MailboxSettings.Read	Read Exchange mailbox settings (forwarding rules, locale, time zone)
ExchangeMessageTrace.Read.All	Trace mail flow through Exchange Online (message trace)
Team.ReadBasic.All	Read basic Teams metadata
TeamMember.Read.All	Read Teams membership
Channel.ReadBasic.All	Read basic Teams channel metadata
Sites.Read.All	Read SharePoint and OneDrive site metadata
ServiceHealth.Read.All	Read Microsoft 365 service health status and issues
ServiceMessage.Read.All	Read message center announcements

Intune device management

Permission	What it enables
DeviceManagementManagedDevices.Read.All	Read enrolled devices and their compliance status
DeviceManagementConfiguration.Read.All	Read device configuration profiles and compliance policies
DeviceManagementApps.Read.All	Read managed apps and protection policies

Microsoft Threat Protection (2 permissions)

These apply to the Defender XDR (Microsoft Threat Protection) API. Advanced Hunting queries now run through Microsoft Graph using ThreatHunting.Read.All; these XDR permissions remain granted for compatibility.

Permission	What it enables
AdvancedHunting.Read.All	Run KQL hunting queries against the Defender XDR API
Incident.Read.All	Read XDR-correlated incidents across products

Microsoft Defender for Endpoint (7 permissions)

These power machine inventory, recommendations, the logon-user view used during host assessments, and the organization-wide Vulnerability Management views.

Permission	What it enables
Machine.Read.All	List Defender for Endpoint machines
User.Read.All	List logon users observed on Defender machines
SecurityRecommendation.Read.All	Read Defender security recommendations, per machine and organization-wide
Score.Read.All	Read the organization's exposure score and Secure Score for Devices
RemediationTasks.Read.All	Read Vulnerability Management remediation tasks and their progress
Software.Read.All	Read the organization software inventory
Vulnerability.Read.All	Read the CVEs discovered in a given software product

INFO

48 permissions in total, all read-only and admin-consented. The script reports the same number in its completion summary so you can confirm nothing was skipped.

Provisioned before July 2026? Re-run the script

Eight permissions were added during July 2026, and the tools behind them return a clear error naming the missing permission until you consent. Re-running the onboarding script is the fix — it is idempotent, detects your existing app, and re-applies everything without rotating your secret when you pass -GenerateSecret $false.

Added permission	Tools it unlocks
SecurityAnalyzedMessage.Read.All	Defender for Office 365 analyzed emails
SecurityIdentitiesHealth.Read.All	Defender for Identity health issues
SecurityIdentitiesSensors.Read.All	Defender for Identity sensor inventory
AttackSimulation.Read.All	Attack simulation campaigns, per-user outcomes, and coverage
Score.Read.All	Exposure score and Secure Score for Devices
RemediationTasks.Read.All	Vulnerability Management remediation tracking
Software.Read.All	Organization software inventory
Vulnerability.Read.All	Per-product CVE lists

Licensing still applies on top of consent. The analyzed-email and attack-simulation tools need Defender for Office 365 Plan 2; the Defender for Identity tools need a deployed MDI workspace; the Vulnerability Management tools need Defender for Endpoint Plan 2 — all included in Microsoft 365 E5, and none needing a separate add-on. Where a license is missing rather than a permission, the tools say so specifically.

Add the Connection in InfraScout

Once the script finishes, your InfraScout operator pastes the three values from the output JSON into the admin UI:

1. Open https://portal.infrascout.cloud and sign in as an InfraScout administrator.
2. Go to Admin → Entra Connections → New connection.
3. Fill in:
   • A display name for this connection (shown in your AI client when listing available connections)
   • Tenant ID, Client ID, and Client Secret from the script's JSON output
   • Connection Type — choose identity (see Connection types below)
4. Click Save and Test. InfraScout verifies the credentials against Microsoft Graph and, for an identity connection, starts an initial sync.

Delete the JSON output file as soon as the connection shows Connected:

Remove-Item ./infrascout-customer-app-output.json

Connection types

A connection is one of two types. An identity connection is the default for its tenant: there can be only one per tenant, it runs the scheduled directory sync, and every mscloud_* tool resolves it automatically when no connection is specified. An assessment connection holds credentials that are queried only on demand and never runs a scheduled sync.

For a single connected tenant, choose identity. If you create only an assessment connection, the tenant has no default — mscloud_* calls that do not name a connection have nothing to resolve and fail. Reserve assessment connections for additional tenants you target explicitly, such as partner-managed (GDAP) tenants alongside your own default identity connection.

What Syncs

An identity connection keeps a lightweight cache of your users and groups so directory-aware lookups stay fast. The sync runs on the interval you set when creating or editing the connection — every 5 minutes, 15 minutes, 30 minutes, or hourly — and the connection card shows the chosen interval alongside the last successful run. Everything else InfraScout reads only when an assessment asks for it; there is no bulk one-time export of your directory. All sync and query traffic is read-only — InfraScout never writes to your directory or any other Microsoft Cloud service.

The connection card carries the actions you need to operate a connection: Edit, Test connection, and Delete. Identity connections add a Sync button to run the directory sync immediately rather than waiting for the next scheduled run. To enable or disable a connection, open it with Edit and toggle it there.

Scoping the sync

By default, an identity connection syncs every user and group in the tenant. To narrow that scope, set an optional user filter, group filter, or both when editing the connection. Each filter is an OData expression that InfraScout applies to the directory query, so you sync only the objects you care about. Use the Test action next to each filter to validate the expression against your tenant before saving — a filter must pass its test before the connection can be saved.

Changing a filter triggers a full re-sync the next time the connection runs, because the set of objects in scope may have changed. Leaving the filters empty keeps the full directory in scope.

A filtered connection also stops using the fast path. An unfiltered connection syncs incrementally, asking Microsoft Graph only for what changed; Graph's incremental endpoints cannot express a user or group filter, so a filtered connection re-reads everything in scope on every run instead. The sync summary reports which mode a run actually used, per resource, and the counts it shows are the objects that run touched — on a full re-read that is everything in scope, not a count of changes. If you set a filter and your sync starts reporting a full read of your whole filtered directory each time, that is the expected behavior rather than a fault.

Using the Connection

Once connected, the full Microsoft Cloud tool set is available — tools for Entra ID, Azure, Microsoft 365, and Defender. Connection selection happens per tool call, not per session. Omit connection_id and a mscloud_* tool runs against your default identity connection; pass a connection_id to target a different tenant. Call entra_connection_list only when you need to see which tenants are configured or to find the connection_id for a non-default tenant. See Microsoft Cloud Tools for an overview of what each tool provides.

Secret Rotation

Client secrets expire 24 months after creation. Two months before expiry, re-run the same script with -GenerateSecret $true (the default):

.\create-infrascout-customer-app.ps1

The script detects the existing app, re-applies any permission drift, and adds a new client secret next to the old one — both remain valid until the old one expires. Send the new secret to InfraScout to update the connection. Updating the secret in InfraScout takes effect immediately with no disruption to running assessments.

Manual Path: Azure Portal

If running PowerShell scripts is not allowed in your environment, you can produce the same app registration through the Microsoft Entra admin center. Plan for 15–20 minutes of clicking; the script does this in under a minute.

1. Sign in to the Microsoft Entra admin center and go to Identity → Applications → App registrations → New registration.
2. Name it InfraScout Data Collection, choose Single tenant, leave the redirect URI blank, and click Register.
3. Note the Application (client) ID and the Directory (tenant) ID from the Overview blade.
4. Go to API permissions → Add a permission:
   • Add the 39 Microsoft Graph → Application permissions listed in Microsoft Graph above.
   • Under APIs my organization uses, search for Microsoft Threat Protection and add the 2 application permissions listed above.
   • Under APIs my organization uses, search for WindowsDefenderATP and add the 7 application permissions listed above.
5. Click Grant admin consent for (your tenant) at the top of the permissions list. Confirm every permission shows the green Granted for (tenant) indicator before continuing.
6. Go to Certificates & secrets → New client secret. Choose a 24-month lifetime, click Add, and copy the Value field immediately — it is shown only once.
7. Send the Tenant ID, Application (client) ID, and client secret to InfraScout through a secure channel.

WARNING

The portal lists permissions one at a time across three APIs. Missing a permission produces a partial connection in InfraScout — some tools work, others return authorization errors. The PowerShell script is the recommended path because it cannot miss a permission.