> ## Documentation Index > Fetch the complete documentation index at: https://docs.forge.ai/llms.txt > Use this file to discover all available pages before exploring further. # Microsoft Agents > Connect Microsoft agent inventory, audit, hunting, protection, and lifecycle surfaces. Microsoft Agents is a multi-surface connector. Each native feed has its own permission, license, content-visibility, and enforcement state; Forge does not treat a successful Entra token exchange as proof that every Microsoft lane is available. ## Sources | Source | Forge coverage | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Microsoft 365 Agent Registry | Package catalog, package detail, owners, scopes, connector inventory, and eligible lifecycle actions | | Copilot Studio | Agent and tool inventory, Dataverse context, transcripts, and external threat-detection callbacks | | Power Platform | Environments, bots, components, workflows, connectors, connection references, variables, AI models, and DLP context | | Agent 365 / Defender | Advanced-hunting runtime receipts, routes, and Security for AI alerts | | Defender for Cloud Apps | SaaS activity and OAuth permission evidence | | Purview Audit | AI and Copilot audit activity and data-exposure context | | Microsoft 365 Copilot | Interaction export and native policy-setting posture | | Azure AI Foundry | Configure inventory separately under **Settings → Cloud AI → Azure**; it is not imported by this Microsoft connection | | Teams | AI app catalog plus team and personal app installations | | Security Copilot and Fabric | Exported workspace/runtime evidence and tenant inventory when available | Non-AI Teams and package rows are filtered rather than presented as agent inventory. ## Authentication The base connection uses an Entra tenant ID, application client ID, and client secret. Additional Microsoft surfaces require separate delegated or environment-scoped authorization: | Lane | Required authorization | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Agent 365 hunting | Microsoft Graph application role `ThreatHunting.Read.All`; legacy fallback uses Defender `AdvancedHunting.Read.All` and Defender RBAC | | Package catalog actions | Delegated `offline_access` and `CopilotPackages.ReadWrite.All` | | Copilot policy settings | Delegated `offline_access` and `CopilotPolicySettings.Read` | | Power Platform inventory | Delegated Power Platform API `ResourceQuery.Resources.Read` | | Dataverse details/sessions | Optional environment application user with table-level read access for rich Copilot Studio configuration and transcripts | | Power Platform DLP | Delegated PowerApps Service `https://service.powerapps.com/User` | | Defender Cloud Apps | Tenant portal/API authorization for activity; Graph OAuth grants are collected separately | | Azure AI Foundry | Separate Azure connection with Reader and Cognitive Services User on the selected subscriptions or resource groups | Grant only the read lanes needed initially. Package mutation and provider response actions should be authorized separately. ### Add API permissions Permissions with similar names are spread across multiple Entra APIs. Select the API shown below rather than searching only inside Microsoft Graph: | Lane | API | Type | Permissions | | ------------------------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Package catalog | Microsoft Graph | Delegated | `CopilotPackages.ReadWrite.All`, `offline_access` | | Copilot policy | Microsoft Graph | Delegated | `CopilotPolicySettings.Read`, `offline_access` | | Agent 365 hunting | Microsoft Graph | Application | `ThreatHunting.Read.All` | | Purview audit search | Microsoft Graph | Application | `AuditLogsQuery.Read.All`; add `AuditLog.Read.All` only for the directory-audit/sign-in fallback | | Microsoft 365 Copilot export | Microsoft Graph | Application | `AiEnterpriseInteraction.Read.All` | | Teams catalog and installations | Microsoft Graph | Application | `AppCatalog.Read.All` plus `TeamsAppInstallation.Read.All`, or the narrower team/user installation-read roles for only those enabled lanes | | Power Platform inventory | Power Platform API | Delegated | `ResourceQuery.Resources.Read` | | Power Platform DLP | PowerApps Service | Delegated | `https://service.powerapps.com/User` | | Purview labels | Microsoft Graph | Application | `InformationProtectionPolicy.Read.All`; add `Files.Read.All` for known drive-item labels (`Sites.Read.All` is a broader alternative) | | Legacy hunting fallback | Microsoft Threat Protection | Application | `AdvancedHunting.Read.All` | Find **Microsoft Threat Protection** and **Power Platform API** under **APIs my organization uses** in Entra. Grant tenant admin consent after reviewing the permissions. `AdvancedHunting.Read.All` is a legacy fallback and is not required when Microsoft Graph `ThreatHunting.Read.All` works for the tenant. Some inventory lanes also need directory reads to resolve the users, groups, or applications selected for collection. Add `User.Read.All`, `Group.Read.All`, `Directory.Read.All`, or `Application.Read.All` only for those enabled lanes; they are not prerequisites for every Microsoft connection. Forge's package-catalog authorization currently requests `CopilotPackages.ReadWrite.All` because the same lane supports package lifecycle actions. Do not enable that lane for a read-only pilot that cannot approve this scope. Forge never performs a package mutation without a separate action request and exact target confirmation. ### Create the Entra app registration If your organization does not already have a dedicated Forge app registration: 1. In the Microsoft Entra admin center, open **App registrations** under **Entra ID**, then select **New registration**. 2. Enter a recognizable name, such as `Forge ()`. 3. Select **Accounts in this organizational directory only (Single tenant)**. Forge binds the connection to the tenant you enter during setup. 4. Under **Redirect URI**, select **Web** and enter: ```text theme={"system"} https://console.forge.ai/microsoft-agent-security/oauth/callback ``` If you use another Forge Console environment, replace `https://console.forge.ai` with that Console's origin. The Console setup help displays the exact environment-specific value. 5. Select **Register**. Package catalog, Copilot policy, and Power Platform delegated authorization all share this callback. Do not add package-specific callback URLs. 6. On **Overview**, copy **Application (client) ID** and **Directory (tenant) ID**. Do not use the Object ID or tenant display name. 7. Open **Certificates & secrets → Client secrets**, create a client secret, and copy its **Value** immediately. Microsoft only displays the value once; do not copy the Secret ID or put the value in chat, tickets, or screenshots. Forge exchanges delegated authorization codes server-side, which is why this is a **Web** redirect rather than a single-page or mobile application redirect. Forge stores the client secret encrypted and does not return it to the browser. ## Setup 1. In Entra, open **Overview under Entra ID** to find the tenant ID. 2. Save the Entra tenant and app credentials under **Settings → Integrations → Microsoft 365**. 3. If you are connecting Copilot Studio, open **Manage → Environments** in the Power Platform admin center and copy the Environment ID from **Details**. 4. Select **Test credentials**. Forge performs a live Microsoft application token exchange; **Connected** proves the tenant, client ID, and client secret authenticate, but does not prove that every optional API permission, license, or delegated lane is available. 5. Select **Sync**, then review each source state: `connected`, `permission_missing`, `license_missing`, `preview_unavailable`, `pending`, or `degraded`. The source-level result identifies permissions or licenses that are not covered by the base credential test. 6. Authorize the package catalog, Copilot policy, and Power Platform lanes individually as required. Package catalog and Copilot policy both use Microsoft Graph, but Forge keeps their optional grants, stored authorization, health, and revocation independent. Power Platform uses a separate API audience. Defender and the other app-only lanes use permissions and tenant admin consent on the Entra application; they do not have a separate delegated authorization button in Forge. 7. Optional: to import rich Copilot Studio configuration or transcript-backed sessions, add the Forge service principal as an application user in each Dataverse environment in scope: * In the Power Platform admin center, open **Manage → Environments**, select the environment, then open **Settings → Users + permissions → Application users → New app user**. * Select the same Entra app whose Application (client) ID is saved in Forge, select the environment's business unit, and assign a dedicated security role. * Give that role organization-level **Read** access only to the required `bots`, `botcomponents`, `workflows`, `connectionreferences`, `environmentvariabledefinitions`, `appmodules`, and `msdyn_aimodels` tables. Add `conversationtranscripts` only when transcript-backed sessions are required. A Dataverse application user is not created by Power Platform delegated authorization and is not required for basic Resource Query inventory. Repeat this step for every Dataverse environment from which Forge should read rich configuration or transcripts. 8. Run **Sync sources** and compare provider-native counts and checkpoints by feed. A broad first sync can take up to 10 minutes. Forge keeps completed source data while the remaining feeds run, and the Console continues polling until the aggregate sync reaches a terminal state. 9. Configure the Entra trust used by Copilot Studio external threat detection. The least-privilege path is manual: * In the Forge app registration, open **Expose an API** and set the **Application ID URI** to the origin of the Forge protection endpoint (for example, `https://api.forge.ai`). * Open **Certificates & secrets → Federated credentials → Add credential**. * Select **Other issuer** and **Explicit subject identifier**. * Copy the exact **Issuer** and **Subject** generated by the Forge Protection guide. Use audience `api://AzureADTokenExchange`, name `forge-copilot-protection`, and description `Forge Copilot Studio external threat detection endpoint`. Forge can automate these two app-registration changes only when the app has Microsoft Graph `Application.ReadWrite.All` application permission with tenant admin consent. That broad write permission is not required for manual setup. A newly added federated credential can take several minutes to propagate. If Power Platform initially returns `AADSTS70025`, confirm the credential appears on the intended Application (client) ID, wait, and retry before changing its values. 10. Configure Copilot Studio external threat detection under **Power Platform admin center → Security → Threat detection → Additional threat detection**. Select the environment, choose **Set up**, enable provider sharing, enter the Forge Entra app ID and exact protection endpoint, choose the one-second error behavior, and save. 11. Run a published generative-orchestration agent that invokes a tool and verify an authentic callback before enabling that protection path on additional environments. The setting is per environment; Microsoft currently provides no tenant-wide rollout. Test every tool you rely on for blocking because Microsoft decides which tool invocations call the external threat-detection provider; a callback from one tool does not establish coverage for other tools. ## Microsoft Purview sensitivity labels For organization label taxonomy import, add the Microsoft Graph application permission `InformationProtectionPolicy.Read.All` to the Forge Entra app and grant tenant admin consent. Forge uses the service principal and the organization-scoped sensitivity-label endpoint; this is separate from the delegated package-catalog authorization. For sensitivity-label extraction from known SharePoint and OneDrive drive items, add the least-privilege Microsoft Graph application permission `Files.Read.All`. `Sites.Read.All` is a supported higher-privilege alternative, so customers who already granted it do not need to add `Files.Read.All`. Do not grant `Files.ReadWrite.All` solely for Forge label import. Inline policy enrichment applies when the pre-tool request identifies an existing drive item by drive/item ID, supported Work IQ path, or SharePoint or OneDrive URL. Microsoft's hook does not expose a newly created tool output for pre-tool enforcement. After consent, return to **Settings → Integrations → Microsoft 365** and run **Sync**. The Purview taxonomy job imports label IDs, display names, hierarchy, and supported metadata. A successful empty result shows zero labels with a real latest-sync time; zero labels with **Never** means no successful taxonomy run has completed. Microsoft currently documents the sensitivity-label taxonomy endpoint under Microsoft Graph beta; validate availability in the target tenant before relying on it for production policy conditions. Purview audit search is a separate lane. Forge checks it every 15 minutes and queries a rolling 24-hour window. Microsoft processes audit queries asynchronously, so a manual Sync can show `running`; Forge retains the query ID and resumes it on a later scheduled or manual Sync. ## Enforcement | Surface | Boundary | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Copilot Studio external threat detection | Inline Forge PDP for supported generative-orchestration pre-tool calls; Microsoft uses a one-second callback budget | | Agent Registry / Agent Builder | Administrative package block, scope, owner, or lifecycle actions where Graph exposes and authorizes them | | Foundry | Supported lifecycle actions with provider readback | | Defender, Purview, Cloud Apps, Copilot exports | Detective evidence; Microsoft remains the enforcement origin | | Generic Microsoft 365 Copilot sessions | No universal inline Forge control | Action availability is calculated from the connected source, permission, license, object state, and post-action verification support. An action shown as unsupported is not silently replaced with a weaker operation. ## Verification | Lane | Proof | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | Package catalog | List rows plus detail-enrichment state and native package IDs | | Power Platform | Expected environment and basic agent resource; Dataverse access is required only for adjacent configuration and transcripts | | Hunting | A general table succeeds, then an AI/Agent table returns records or a healthy empty result | | Purview labels | Taxonomy shows a completed latest-sync time and readable label names, or a healthy completed empty result | | Purview audit | Async query reaches `succeeded` and advances its checkpoint | | Copilot protection | A published generative-orchestration agent invokes a tool, Forge records the authentic callback and decision, and the agent honors it | | Lifecycle action | Preview, execute, provider readback, and Forge audit record agree | Microsoft setup reference: [Enable external threat detection and protection for Copilot Studio custom agents](https://learn.microsoft.com/microsoft-copilot-studio/external-security-provider). `429` is retained as a degraded, retryable source with the Microsoft `Retry-After` interval. A missing AI hunting table is distinguished from a missing permission and from an unprovisioned Defender tenant.