Skip to main content
Version: 11.5.0

Microsoft 365 Copilot

Overview​

The Microsoft 365 Copilot connector lets your agents and users reach Microsoft 365 Copilot through HYPR AgentPass™. Copilot traffic then picks up the same identity, policy, approval and audit controls as every other connector. The connector forwards requests to the Microsoft Graph Copilot APIs (/copilot), and returns Copilot's response through the gateway. In the console, it is listed under the Cloud Agents connector kind.

To govern developer tools that call your own model deployments in Microsoft Foundry or Azure OpenAI, such as GitHub Copilot or Claude Code, use the Microsoft Foundry connector instead.

Access follows a bring-your-own-license (BYOL) model. Each signed-in user calls Copilot on their own Microsoft 365 Copilot license. The gateway does not use a single shared service credential. For each request, it obtains a per-user delegated token and forwards the call as that user.

note

Creating a Microsoft 365 Copilot connector needs Connectors: Edit, which Admin has, and Microsoft Entra app registrations in your tenant. See Microsoft Entra Setup for Microsoft 365 Copilot.

How Access Works​

When a signed-in user makes a Copilot request through the gateway:

  1. AgentPass identifies the user from their gateway session.
  2. The gateway exchanges the user's sign-in for a per-user delegated Microsoft Graph token, using the Microsoft OAuth2 On-Behalf-Of (OBO) flow. It caches the token for reuse.
  3. The gateway forwards the request to Microsoft Graph with that user's token, so Copilot responds against the user's own license.

Only the gateway holds the delegated token. It is never returned to the browser or the calling client. Each call is made as the individual user, so Copilot applies that user's license and access. There is no application-only or shared-service path.

This backend-for-frontend design uses two Microsoft Entra app registrations:

  • A confidential middle-tier app that performs the On-Behalf-Of exchange
  • A public app that signs users in to the Agent Portal

Microsoft Entra Setup for Microsoft 365 Copilot covers both, step by step.

A user without an active Microsoft 365 Copilot license cannot reach Copilot through the connector. See Troubleshooting.

Before You Begin​

The connector authenticates to Microsoft as a confidential client. You need Microsoft Entra app registrations in the same tenant as your Microsoft 365 Copilot licenses. Complete the registrations first, then return here to create the connector.

Microsoft Entra Setup for Microsoft 365 Copilot walks through both app registrations, the delegated Microsoft Graph permissions and admin consent, the exposed API scope, and the client secret. When you finish, you have the values the connector form asks for.

Microsoft GCC High tenants

The connector supports GCC High, and everything on this page still applies. The app registrations, admin consent and Microsoft hosts differ, though. Start at Microsoft 365 Copilot on GCC High.

Create the Connector​

  1. In the AgentPass administration console, open Connectors.
  2. Click Add connector.
  3. Under Cloud Agents, choose Microsoft 365 Copilot.
  4. Complete the configuration fields described in the following table.
  5. Click Create Connector. The client secret is stored encrypted, and never displayed again.
The Microsoft 365 Copilot connector configuration fields

The form's How Microsoft 365 Copilot access works panel summarizes what to provide. It links directly to Azure portal → App registrations, where you copy the tenant ID, the application (client) ID and a fresh client secret value. Microsoft Entra Setup for Microsoft 365 Copilot has the full walkthrough.

FieldWhat to enter
Connector NameAn identifier for the connector, such as m365_copilot
Display NameA friendly name shown in the console, such as Microsoft 365 Copilot
Microsoft cloudThe Microsoft cloud your tenant lives in: Commercial (worldwide), the default, or US Government — GCC High. See Microsoft 365 Copilot on GCC High
Tenant IDYour Microsoft Entra directory (tenant) ID
Client IDThe application (client) ID of the middle-tier app registration
Client SecretThe Value of a client secret, from the app's Certificates & secrets. Write-only. When editing, leave it blank to keep the stored secret
Graph scopesThe On-Behalf-Of downstream scope requested from Microsoft Graph. Leave it blank to use the default for the connector's Microsoft cloud: https://graph.microsoft.com/.default on the commercial cloud, and the corresponding US Government scope on GCC High

Set Up the Agent Portal​

The connector also powers the Agent Portal, a web page where a signed-in user chats with Copilot and with the Copilot Studio agents you register. To let users sign in, enter the Agent Portal sign-in details you registered in Entra.

FieldWhat to enter
Portal app (client) IDThe application (client) ID of the public (SPA) app registration that signs users in to the portal
Exposed API scopeThe name of the scope the middle-tier app exposes, such as access_as_user. The gateway adds the middle-tier app's api://<client-id>/ prefix, and the portal requests that scope at sign-in. When left blank, it is access_as_user

Both values come from the same Entra setup. Once both are set, the connector's Overview tab shows a Portal URL row, with a link that opens the portal and Copy. Share that URL with your users. See Register the Agent Portal app. The portal's redirect URI, which is your gateway's public origin plus /portal/, must match the one registered on the public app.

You enter these sign-in details on the connector yourself, with no coordination with HYPR. Only the user's Microsoft sign-in gates the portal. A user with Microsoft 365 Copilot access but no HYPR console access can still use it.

Edit the Connector Later​

Every connection and Agent Portal sign-in field stays editable after the connector is created. Open the connector, and click Edit.

The client secret is write-only. When you edit the connector, leave Client Secret blank to keep the stored value, or enter a new value to replace it.

You edit the connector's Agent Portal branding separately, on the connector detail page. See Brand the Agent Portal.

Registering Copilot Studio Agents for the Agent Portal​

Besides Microsoft 365 Copilot, you can register custom agents your organization builds in Microsoft Copilot Studio. Agent Portal users can then chat with them directly. Each registered agent is addressed on behalf of the signed-in user, so it runs with that user's own identity and access.

You register each Copilot Studio agent on the connector once. Every enabled agent becomes available to the connector's portal users. When a user chats with one, Microsoft applies that user's own access to the agent.

Grant the Power Platform Permission in Microsoft Entra​

Chatting with a Copilot Studio agent uses a delegated permission separate from the Microsoft Graph permissions. Add it to the middle-tier app registration you created for the connector. The steps are in Grant the Power Platform permission (Copilot Studio agents).

Grant the permission and consent to it

Grant the delegated CopilotStudio.Copilots.Invoke permission, and complete admin consent. Without it, registered Copilot Studio agents cannot be reached, and the Agent Portal shows a consent notice instead of a reply.

Build a Minimal Agent in Copilot Studio​

If you do not have an agent to register yet, you can build a usable one in Copilot Studio in a few minutes. All of this happens in Microsoft Copilot Studio, not in the gateway console.

This sample produces the smallest agent the connector can use. It is not a limit on what you can register. A registered agent can use the full range of Copilot Studio capabilities: topics, tools and actions, connected agents, triggers, and any knowledge source Copilot Studio supports.

  1. In Microsoft Copilot Studio, select Agents → + New agent.

  2. Open the new agent's Overview tab.

  3. Under Details, give the agent a Name you will recognize later. Optionally, add a Description and an icon. Click Save.

  4. Under Select your agent's model, choose the model the agent uses for reasoning and responding.

    The Overview tab of a Copilot Studio agent, showing the Details panel and the model selector
  5. Under Instructions, describe what the agent should do and how it should answer. Copilot Studio uses these instructions to shape every response.

  6. Open the Knowledge tab, and click + Add knowledge. Add something to ground the agent's answers in: uploaded files, or a Power Platform connector to a system your organization already runs. Each source you add is listed with its type and the agents it is available to.

    The Knowledge tab of a Copilot Studio agent, listing an uploaded file and a Power Platform connector as knowledge sources
  7. Publish the agent. An unpublished agent cannot be reached from outside Copilot Studio, so the Agent Portal cannot chat with it. See Microsoft's Publish your agent for the current steps.

Knowledge sources stay under Microsoft's access controls. When a portal user chats with the agent, the call is made on that user's behalf, so the agent returns only what the user is already allowed to see.

Find Each Agent's Values in Copilot Studio​

For each agent you want to register, collect its identifying values from Microsoft Copilot Studio.

  1. In Microsoft Copilot Studio, open the agent.
  2. Go to Settings → Advanced → Metadata.
  3. Copy the values listed in the following table.
ValueWhere it comes from
Environment IDThe Copilot Studio environment that hosts the agent
Tenant IDYour Microsoft Entra directory
Agent app IDThe agent's stable identifier
Schema nameThe agent's schema name
Where an agent's schema name and identifiers appear in Copilot Studio

For more detail on these values, see Microsoft's guide, Integrate with web or native apps using the Microsoft 365 Agents SDK.

Add the Agents to the Connector​

  1. On the connector's detail page, click the Copilot Studio agents tab.
  2. Click Add agent.
  3. Complete the fields described in the following table.
  4. Click Add.
  5. Repeat for each agent.

The Add Copilot Studio agent form has these fields.

FieldWhat to enter
NameA display name for the agent, shown to users in the Agent Portal
DescriptionOptional. A short description of what the agent does
Environment IDThe Environment ID from the agent's metadata
Tenant IDOptional. The Tenant ID from the agent's metadata
Agent app IDThe Agent app ID from the agent's metadata. It cannot be changed after you add the agent
Schema nameThe Schema name from the agent's metadata

Each row has Edit, Enable or Disable, and Remove. Every enabled agent is available in the Agent Portal, and disabling an agent removes it. This tab follows the cloud agents permissions, not the connector permissions. At Own scope, it lists only the agents you added, and you can edit and remove only those. Enable and Disable follow the rule for every agent switch. See Who Can Turn an Agent Off and On. A button you cannot use is unavailable. For what the chat looks like to your users, see Chatting in the Agent Portal.

Copilot Studio agents added to the connector, each enabled or disabled independently

Brand the Agent Portal​

The Agent Portal this connector powers can carry your organization's branding instead of the default look. On the connector's detail page, open the Portal branding tab. There you can:

  • Pick a theme from your tenant's theme registry, or follow the tenant default
  • Set the product name the portal presents
  • Add a portal-specific logo

A live preview shows the result, including the sign-in page your users see before they log in.

You manage the themes themselves, with their colors, logos and the tenant default, on the console's Settings → Theme page. See Themes.

Governance​

Microsoft 365 Copilot traffic flows through the same gateway pipeline as your other connectors. Your existing controls apply with no extra configuration:

  • Request Log. Copilot calls appear in the Request Log alongside your other agent activity, attributed to the user who made them.
  • Policies. Your policies evaluate requests before forwarding and responses after, so you can allow, block or require approval for Copilot traffic. A policy can also name the Copilot details behind a request: which part of the portal it came from, the signed-in person, the Copilot Studio agent it targets and any attached files. See Microsoft 365 Copilot Policies.
  • Approvals and audit. Actions that require a supervisor's approval follow the standard human-in-the-loop flow. The audit trail records every request.

Response Policies and Streaming in the Agent Portal​

By default, replies stream into the Agent Portal live, so users start reading as the answer is written.

When an enabled policy that evaluates responses applies to this connector, the gateway holds each reply until the check completes. The complete answer then appears at once, or a blocked notice if the policy blocks it. This applies to every conversation on the connector, not only those a rule matches, so scope such a policy to the connector you mean to govern.

Checking What Copilot Replies covers what a reply-side rule can read, and what users experience while one is enabled.

Troubleshooting​

Users may see these messages.

MessageWhat it meansWhat to do
Microsoft 365 Copilot license requiredMicrosoft rejected the request, because the signed-in user has no active Microsoft 365 Copilot license or lacks access to CopilotConfirm the user is assigned an active Microsoft 365 Copilot license and has access, then try again
Sign-in required / session expiredThe user's session has expired or is no longer valid, so the gateway cannot obtain a token on their behalfHave the user sign in again. The next request obtains a fresh token
Consent requiredThe required Microsoft Graph permissions have not been consented for the user or the tenantConfirm the delegated Microsoft Graph permissions are on the app registration, and admin consent is granted. See Microsoft Entra Setup
Consent required (Copilot Studio agent)The delegated Power Platform permission for Copilot Studio has not been consentedConfirm CopilotStudio.Copilots.Invoke is on the app registration, and admin consent is granted. See Grant the Power Platform permission
Agent not availableA registered Copilot Studio agent could not be reached for the signed-in userConfirm the agent is enabled on the connector, and that the user has access to it in Microsoft