Azure M365 Agents — directory role and Graph permissions¶
The Trust3 collector discovers Microsoft 365 Copilot Agent Builder agents as inventory and, when monitoring is enabled, collects agent interaction traces. Both flows authenticate as the service principal from your Microsoft Entra app registration (TRUST3_AZURE_CLIENT_ID, TRUST3_AZURE_CLIENT_SECRET, and TRUST3_AZURE_TENANT_ID).
The two flows need different kinds of access:
| Flow | Data source | Access required |
|---|---|---|
| Inventory | Azure Resource Graph — PowerPlatformResources table, resource type microsoft.copilotstudio/agents | The AI Reader Entra directory role on the service principal |
| Traces (monitoring) | Microsoft Graph — Defender advanced hunting, Purview audit, AI interaction history | Application permissions on the app registration, with admin consent |
For Entra app registration and client secret setup, see Microsoft Copilot Studio Prerequisites.
Inventory — assign an Entra directory role¶
Assign these to the collector's service principal. AI Reader is required for inventory. User.Read is a Delegated Graph permission that new app registrations include by default; grant it if it is missing so the collector can get the owner display name.
| Access | Type | Purpose |
|---|---|---|
| AI Reader | Entra directory role | Required. Authorizes Azure Resource Graph inventory. |
User.Read | Delegated permission | Sign in and read user profile. Default Graph permission; grant it if missing. |
Assign the role in the Azure portal¶
You need Privileged Role Administrator or Global Administrator to assign directory roles.
- Open the Azure Portal.
- Go to Microsoft Entra ID → Roles and administrators.
- Search for and select AI Reader.
- Select Add assignments.
- Search for your app registration name (for example
Trust3-Integration), select it, and select Add. - Confirm the service principal is listed under Assignments for the role.
Service principals in the role picker
The Add assignments picker searches users, groups, and service principals. Search by the app registration's display name — not by its client ID.
Traces — Microsoft Graph application permissions¶
Required when trace collection is enabled (TRACE_COLLECTION_ENABLED=true). Grant these as Application permissions (not delegated) on the same app registration. A Global Administrator or Privileged Role Administrator must grant admin consent.
| Permission | Type | Purpose |
|---|---|---|
ThreatHunting.Read.All | Application | Read Defender advanced hunting data used for agent activity signals. |
AiEnterpriseInteraction.Read.All | Application | Read Microsoft 365 Copilot / AI enterprise interaction history. |
AuditLogsQuery.Read.All | Application | Query unified audit log records related to agent activity. |
In addition, the Defender Microsoft 365 activities connector must be enabled in your tenant so that CloudAppEvents is populated. See CloudAppEvents table in the advanced hunting schema and Connect Microsoft 365 to Microsoft Defender for Cloud Apps.
Add permissions in the Azure portal¶
- Open the Azure Portal.
- Go to Microsoft Entra ID → App registrations → select your Trust3 app (for example
Trust3-Integration). - Select API permissions → Add a permission.
- Select Microsoft Graph → Application permissions.
- Search for and select each permission required for your scenario:
| Scenario | Permissions to add |
|---|---|
| Inventory | None for Resource Graph — inventory uses the AI Reader directory role. Confirm User.Read (Delegated) is present (it is the default). Grant it if missing to get owner display names. |
| Traces | ThreatHunting.Read.All, AiEnterpriseInteraction.Read.All, AuditLogsQuery.Read.All (Application) |
- Select Add permissions.
- Select Grant admin consent for your tenant, then confirm.
After consent, each permission should show Granted for tenant under Status.
Admin consent required
These are application permissions. Without tenant-wide admin consent, Graph calls from the collector fail with authorization errors even when the permissions appear in the app registration.
Map values to configuration¶
Use the same Azure credentials as other Microsoft connectors:
| Portal label | Typical configuration name |
|---|---|
| Application (client) ID | TRUST3_AZURE_CLIENT_ID |
| Directory (tenant) ID | TRUST3_AZURE_TENANT_ID |
| Client secret value | TRUST3_AZURE_CLIENT_SECRET |
For Docker / .env setup and enabling traces, see Run Collector.
Important
Azure M365 agents currently include the following information:
- Metadata: Owner, model, environment, and channels.
- Lineage: Partial lineage information, such as whether model access and web search are enabled.
- Not collected: Agent descriptions, named tools, knowledge sources, and attachments.
- Traces: Agent interaction traces are collected when monitoring is enabled.
- Usage data: Token usage information is not currently captured.
Troubleshooting¶
AccessDenied … The user might not have enough permission¶
The Resource Graph query was rejected. The service principal does not have the AI Reader directory role. Assign AI Reader (see above) and re-run.
Owner fields show GUIDs instead of names¶
User.Read is missing or not granted. Inventory is unaffected; grant the Delegated Graph permission to display names. New app registrations include User.Read by default.
No agents discovered¶
Confirm the tenant actually has Agent Builder agents. Agents created in the full Copilot Studio experience are collected by the azure_copilot collector instead — see Microsoft Copilot Studio Prerequisites.
Permission propagation¶
Directory role assignments and admin consent can take several minutes to take effect. Wait a few minutes before re-running the collector.
Summary¶
| Do | Don’t |
|---|---|
| Assign the AI Reader directory role for inventory | Expect a Microsoft Graph API permission to authorize Resource Graph |
| Add trace permissions only when monitoring is enabled | Over-grant Graph permissions when you only need inventory |
Confirm User.Read (Delegated) is granted for owner names | Treat GUID owner values as an inventory failure |
Official documentation (quick links)¶
| Topic | Microsoft docs |
|---|---|
| Register an app in Microsoft Entra ID | Quickstart: Register an application |
| Assign Entra directory roles | Assign Microsoft Entra roles |
| AI Reader role reference | Microsoft Entra built-in roles |
| Azure Resource Graph | Azure Resource Graph overview |
| Microsoft Graph permissions overview | Permissions and consent |
| CloudAppEvents table | CloudAppEvents table in the advanced hunting schema |
| Microsoft 365 activities connector | Connect Microsoft 365 to Microsoft Defender for Cloud Apps |
| AI enterprise interactions API | getAllEnterpriseInteractions |