Skip to main content
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

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: 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: 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 (<organization name>).
  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:
    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

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

Microsoft setup reference: Enable external threat detection and protection for Copilot Studio custom agents. 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.