Skip to main content
The Microsoft Graph Admin integration gives Cotool agents organization-wide visibility into Microsoft Entra ID, Microsoft 365 activity, and Microsoft Intune managed devices, plus two account containment actions: disabling a user and revoking their sign-in sessions. It is designed for security investigations, access reviews, user offboarding, and incident response workflows where an agent needs to answer questions like:
  • What groups, directory roles, and enterprise applications does this user have access to?
  • Which applications have delegated OAuth grants that can act as this user?
  • What sign-in, directory audit, or provisioning activity happened in the tenant?
  • Which users or groups match a specific investigation lead?
  • Which devices does this user have, and are they managed, encrypted, and compliant?
  • Who wiped this device or changed this Intune policy?

​
Integration model

Microsoft Graph does not use Google Workspace-style domain-wide delegation (DWD). The Microsoft equivalent for this integration is tenant-wide admin consent to a Microsoft Entra application, followed by application-only Microsoft Graph access.
After an administrator grants consent, Cotool uses the OAuth 2.0 client credentials flow to request Microsoft Graph tokens for the customer’s tenant. The admin integration does not require Cotool to handle an end-user Microsoft password, and it does not depend on an individual user’s mailbox or session token.
At a high level:
  1. A Cotool admin starts setup from Settings > Integrations and selects Microsoft Graph (Admin).
  2. Cotool asks for the Microsoft tenant domain, such as contoso.com or contoso.onmicrosoft.com.
  3. Cotool redirects the administrator to Microsoft’s admin consent endpoint for that tenant:
  4. The Microsoft administrator reviews the permissions configured on Cotool’s Entra application and grants tenant-wide consent.
  5. Microsoft redirects back to Cotool with the consent result.
  6. Cotool stores the tenant identifier for the organization and uses app-only Graph tokens scoped to that tenant when agents run Microsoft Graph Admin tools.
Cotool uses two Microsoft identity platform flows: During execution, the token request uses:
The .default scope tells Microsoft to issue a token containing the application permissions that were already configured on the Cotool app registration and consented by the tenant administrator. Cotool does not dynamically request additional Microsoft Graph permissions at runtime. Because this is app-only access, Graph calls are not limited to the Microsoft account of the administrator who completed setup. They are limited by the Graph application permissions consented in the customer’s tenant.

​
Required Microsoft Graph permissions

The admin integration uses Microsoft Graph application permissions. In Microsoft terminology, these are app roles granted to the Cotool enterprise application; they are not delegated user scopes. These permissions require Microsoft administrator consent.

​
Office 365 Management APIs permissions

The Microsoft 365 unified audit log streams read from the Office 365 Management Activity API, a separate resource on the same Cotool app registration. Its application permissions are granted in the same admin consent, and its tokens are requested with scope=https://manage.office.com/.default.
Some Microsoft Graph endpoints list narrower least-privilege alternatives. Cotool relies on the permissions above so agents can answer cross-tenant access and audit questions consistently. The only write permissions are the two account containment permissions, and each containment action asks a Cotool user to confirm before it runs.
Tenants that granted admin consent before a permission was added to the Cotool app registration must re-run admin consent to grant the newer permissions: use Reauth on the Microsoft Graph Admin integration, which sends an administrator back through Microsoft’s consent screen for the connected tenant. Cotool reads the permissions Microsoft actually granted from the application token: the Log Ingest card refuses to enable a stream whose permission is missing and names the permission to grant, and an already-enabled stream shows the same notice while its runs are skipped. A stream the tenant is not licensed for (for example, risk detections without Entra ID P2) is reported separately, since re-consenting does not resolve it. Until consent is granted, sign-in log records also lack applied conditional access policy details. Once consent is granted, ingestion resumes and backfills automatically.

​
What agents can read

The read tools below do not create, update, or delete users, groups, roles, app assignments, grants, or logs. Intune tools need the two DeviceManagement* permissions. If a tenant connected before they were added, the tools return an error naming the missing permission until an administrator re-runs consent with Reauth.

​
Account containment

Both actions require a Cotool user to confirm before they run. Disabling an account does not end existing sessions, so containment usually uses both. Access tokens that were already issued stay valid until they expire (typically up to an hour) unless the app supports continuous access evaluation. Microsoft does not let an app disable a user who holds a privileged Entra admin role unless the app also holds a sufficiently privileged Entra role, such as Privileged Authentication Administrator. Without one, disabling an admin fails with a permission error and non-admin users are unaffected. Common questions agents can answer include:
  • “What groups and nested groups give this user access?”
  • “Which Entra roles does this user have directly or through a group?”
  • “Which enterprise applications can this user access?”
  • “Which apps have delegated consent to act as this user?”
  • “Show sign-ins, directory changes, or provisioning events for this user over the last 30 days.”
  • “Is the device in this sign-in managed by Intune and compliant?”
  • “Who wiped or retired devices this week?”

​
Microsoft Graph endpoints used

​
Microsoft 365 unified audit log ingest

With Cotool Logs, the Microsoft Graph Admin integration can also continuously ingest the Microsoft 365 unified audit log into the microsoft_365_audit table. Enable the streams on the integration’s Log Ingest card: Requirements and behavior:
  • Auditing must be turned on in the tenant (it is on by default) and the tenant needs a Microsoft 365 or Office 365 subscription that includes Audit (Standard). Tenants without one are reported as not licensed.
  • Tenants that consented before the Office 365 Management APIs permissions were added must use Reauth to grant them. Until then the Log Ingest card names the missing permission.
  • Cotool starts the tenant’s Management Activity API subscriptions on the first run. Microsoft only publishes audit content from the moment a subscription starts, and the first content can take up to 12 hours to appear. Events from before that point are not available.
  • Cotool checks for new content every five minutes. Microsoft does not guarantee how quickly records become available after the activity; typical delays range from minutes to several hours.
  • Microsoft keeps content available for seven days. If ingestion is interrupted for longer than that, the older content cannot be recovered.
  • Microsoft can deliver the same record more than once. Rows are keyed by the record ID, so query with FINAL to collapse duplicates.
  • Only commercial Microsoft 365 tenants are supported. GCC, GCC High, and DoD tenants are not.
The Azure Event Hub integration’s EnrichedOffice365AuditLogs category covers only SharePoint Online traffic forwarded through Global Secure Access, so it does not replace these streams. Microsoft 365 does not offer a native export of the unified audit log to Event Hubs.

​
Data access and storage

Cotool stores the connected tenant identifier and integration credential metadata for the customer’s organization. For the admin integration, Cotool does not store an end-user Microsoft access token or refresh token. Graph data is fetched when agents call the integration tools and is used to produce the agent response, reports, and normal Cotool audit/history records for the workspace. Log streams you enable on the Log Ingest card, including the Microsoft 365 unified audit log, are stored in your Cotool Logs warehouse under its retention settings.

​
Security and revocation

Administrators can revoke access from Microsoft Entra ID by removing tenant-wide admin consent or deleting the Cotool enterprise application/service principal from the tenant. After revocation, Microsoft stops issuing app-only Graph tokens for Cotool, and Microsoft Graph Admin tools in Cotool will fail authentication. The integration can also be disconnected from Cotool. Recommended controls for customers:
  • Review the requested Microsoft Graph application permissions during admin consent.
  • Limit who in Cotool can configure integrations and run agents with sensitive tools.
  • Monitor Cotool agent activity and workspace audit logs for investigations that use Microsoft Graph Admin data.
  • Periodically review enterprise applications and admin consent grants in Microsoft Entra ID.

​
Operational notes

  • Sign-in log availability depends on the customer’s Microsoft Entra licensing and log retention settings.
  • Microsoft Graph can return partial results or endpoint-specific errors if a tenant policy, license, or permission prevents access to a specific log or object type.
  • The admin integration is separate from Cotool’s user-delegated Microsoft Graph integration, which is used for user-scoped Teams, OneDrive, mail, and delegated workflows.

​
Common prospect questions

​
Is this Google Workspace DWD?

No. Google Workspace uses domain-wide delegation for service accounts. Microsoft uses tenant-wide admin consent to an Entra application plus application permissions. The security outcome is similar: after administrator approval, Cotool can query tenant-wide data for approved permissions without requiring each end user to sign in.

​
Does Cotool need a Global Administrator account password?

No. The Microsoft administrator authenticates directly with Microsoft during the consent flow. Cotool receives the consent result and later uses app-only Microsoft Graph tokens issued by Microsoft.

​
Are the tools read-only?

All but two. The read tools resolve identities, list users and groups, enumerate access paths, inspect role and app assignments, inspect delegated grants, inspect PIM schedules, read Intune devices, and search Entra and Intune audit logs. The two account containment tools disable a user and revoke their sessions, and each needs a Cotool user’s confirmation. Cotool cannot create or delete users or change groups, roles, or app assignments. The Intune permissions are read-only, so Cotool cannot wipe, retire, or reconfigure devices.

​
Why are broad directory permissions required?

Access investigations need to correlate users, groups, directory roles, service principals, app role assignments, delegated grants, and audit logs. Microsoft Graph splits those records across directory, application, role management, and audit-log APIs, so several application permissions are required to build a complete answer.