The Microsoft Graph Admin integration gives Cotool agents read-only, organization-wide visibility into Microsoft Entra ID and Microsoft 365 activity. It is designed for security investigations, access reviews, user offboarding, and incident response workflows where an agent needs to answer questions like:Documentation Index
Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
Use this file to discover all available pages before exploring further.
- 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?
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.
- A Cotool admin starts setup from Settings > Integrations and selects Microsoft Graph (Admin).
- Cotool asks for the Microsoft tenant domain, such as
contoso.comorcontoso.onmicrosoft.com. - Cotool redirects the administrator to Microsoft’s admin consent endpoint for that tenant:
- The Microsoft administrator reviews the permissions configured on Cotool’s Entra application and grants tenant-wide consent.
- Microsoft redirects back to Cotool with the consent result.
- 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.
OAuth and consent flow details
Cotool uses two Microsoft identity platform flows:| Stage | Microsoft flow | Purpose |
|---|---|---|
| Initial setup | Tenant-wide admin consent | Grants the Cotool application permission to read approved Microsoft Graph resources for the tenant. |
| Tool execution | OAuth 2.0 client credentials | Retrieves a short-lived app-only access token for Microsoft Graph. |
.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.| Permission | Type | Used for |
|---|---|---|
AuditLog.Read.All | Application | Read Entra directory audit logs, sign-in logs, and provisioning events from /auditLogs/* endpoints. |
Directory.Read.All | Application | Read users, groups, directory roles, direct and transitive memberships, app role assignments, and broad Entra ID directory metadata needed to explain access paths. |
Application.Read.All | Application | Read service principal and enterprise application metadata used to enrich app assignment and consent findings with application names, app IDs, roles, and scopes. |
RoleManagement.Read.Directory | Application | Read Entra role management data, including role definitions and active or eligible Privileged Identity Management (PIM) role schedules. |
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 without write access.
What agents can read
The integration exposes read-only tools to agents. These tools do not create, update, or delete users, groups, roles, app assignments, grants, or logs.| Tool | What it does |
|---|---|
msft_graph_admin_getUser | Resolves a user by object ID, user principal name, email address, or display name. |
msft_graph_admin_listUsers | Lists and searches organization users. |
msft_graph_admin_listGroups | Lists and searches organization groups. |
msft_graph_admin_listUserGroupMemberships | Reads direct and transitive Entra group memberships for a user. |
msft_graph_admin_listUserDirectoryRoles | Reads direct and group-inherited Entra directory roles for a user. |
msft_graph_admin_listUserAppRoleAssignments | Reads enterprise application assignments for a user and enriches them with service principal details. |
msft_graph_admin_listUserOAuth2PermissionGrants | Reads delegated OAuth2 grants associated with a user and enriches them with app/API scope metadata. |
msft_graph_admin_listUserPimRoleSchedules | Reads active and eligible PIM role schedules for a user. |
msft_graph_admin_searchOrgAuditLogs | Searches organization-wide directory audit, sign-in, and provisioning logs. |
- “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.”
Microsoft Graph endpoints used
| Capability | Microsoft Graph data used |
|---|---|
| Resolve and list users | /users and /users/{id} with selected identity fields. |
| List groups | /groups with optional search, OData filters, and group-type filters. |
| Enumerate group membership | /users/{id}/memberOf/graph.group and /users/{id}/transitiveMemberOf/graph.group. |
| Enumerate directory roles | /users/{id}/memberOf/graph.directoryRole and /users/{id}/transitiveMemberOf/graph.directoryRole. |
| Review enterprise app assignments | /users/{id}/appRoleAssignments, enriched with /servicePrincipals/{id} metadata. |
| Review delegated OAuth grants | /users/{id}/oauth2PermissionGrants, enriched with service principal and OAuth permission scope metadata. |
| Review PIM access | /roleManagement/directory/roleAssignmentScheduleInstances, /roleManagement/directory/roleEligibilityScheduleInstances, and role definition details. |
| Search tenant activity | /auditLogs/directoryAudits, /auditLogs/signIns, and /auditLogs/provisioning. |
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.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.