Skip to main content
Version: 11.5.0

Microsoft Entra Setup for Microsoft 365 Copilot

Overview​

The Microsoft 365 Copilot connector authenticates to Microsoft with the OAuth2 On-Behalf-Of (OBO) flow. Each end user's own delegated permissions drive the Copilot call, and the Agent Portal never holds a Microsoft Graph token. This guide walks through the Microsoft Entra app registrations that make that possible.

Complete this setup before you create the connector. When you finish, you have the values the connector form asks for. See Microsoft 365 Copilot.

note

You need access to the Azure portal, with permission to create app registrations and grant tenant-wide admin consent. You work in the same Microsoft Entra tenant as your Microsoft 365 Copilot licenses. Plan for 30 to 45 minutes.

GCC High tenants

This guide is written for a commercial Microsoft 365 tenant. For a Microsoft GCC High tenant, the registrations are the same, with three differences. You create them in the Azure Government portal at https://portal.azure.us. You use Microsoft Entra ID for Government identities. You grant admin consent in the GCC High tenant. See Microsoft 365 Copilot on GCC High for the full list of differences.

Why Two App Registrations​

The connector uses a backend-for-frontend (BFF) pattern. The Agent Portal signs the user in, and the gateway, never the browser, exchanges that sign-in for a per-user Microsoft Graph token. That requires two applications in Entra.

RegistrationTypeRole
Connector app (middle-tier)ConfidentialHolds the client secret, exposes the sign-in scope, performs the On-Behalf-Of exchange, and carries the Copilot Graph permissions
Agent Portal appPublic (single-page application)The web portal. Signs the user in against the connector app's exposed scope. It is listed as an authorized client application of the connector app, so no second consent prompt appears

Both live in the same tenant, and use single-tenant (My organization only) accounts.

Delegated and application permissions

The Microsoft Graph Copilot Chat API requires delegated permissions. Copilot answers as the signed-in user, on that user's own license, so the grounding permissions must be added as Delegated. A smaller set of Application permissions covers the tenant-wide reads the Agent Portal makes outside a user session. Both sets go on the connector app. See Grant the Microsoft Graph Permissions.

Prerequisites​

  • A Microsoft Entra tenant with Microsoft 365 Copilot licenses assigned to your test users
  • Global Administrator, or Application Administrator plus Cloud Application Administrator, to grant tenant-wide admin consent
  • Your gateway's public origin, its public base URL. The Agent Portal redirect URI is that origin plus /portal/, for example https://<your-gateway-host>/portal/
  • Access to the gateway administration console, to create the connector afterward

Register the Connector App (Middle-Tier)​

  1. In the Azure portal, go to Microsoft Entra ID → App registrations → + New registration.
  2. Name the app, for example AgentPass Copilot Connector.
  3. For Supported account types, choose Accounts in this organizational directory only. Leave the redirect URI blank.
  4. Click Register.
  5. On the Overview blade, copy the identifiers listed in the following table. You need them for the connector and for the Agent Portal app.
The connector app's Overview blade in Microsoft Entra, showing the identifiers to copy
FieldUsed as
Directory (tenant) IDThe connector's Tenant ID
Application (client) IDThe connector's Client ID (middle-tier)
Object IDReference only

Grant the Microsoft Graph Permissions​

  1. Under the connector app, go to API permissions → + Add a permission → Microsoft Graph.
  2. Add the delegated and application permissions your deployment requires, listed in the following tables.
  3. Click Grant admin consent for your tenant. Every permission here requires admin consent.
The Microsoft Graph permissions on the connector app registration

Most of the set is delegated. The Copilot chat call is made on behalf of the signed-in user, so that user's own license and access apply. A smaller application set covers the tenant-wide reads the gateway performs outside any one user's session.

Delegated Permissions​

PermissionPurpose
User.ReadSign in and read the user profile (base scope)
offline_accessRefresh tokens, to keep the On-Behalf-Of chain alive
Mail.ReadCopilot grounding: user mail
Chat.ReadCopilot grounding: user chat messages
ChannelMessage.Read.AllCopilot grounding: channel messages
People.Read.AllCopilot grounding: people and the org graph
OnlineMeetingTranscript.Read.AllCopilot grounding: meeting transcripts
AppCatalog.Read.AllRead the tenant app catalog
TeamsAppInstallation.ReadForUserDiscover the declarative agents installed for the signed-in user
TeamsAppInstallation.ReadSelectedForUserRead the user's selected installed Teams apps
TeamsAppInstallation.ReadWriteSelfForUserAllow the Teams app to manage itself for a user
TeamsAppInstallation.ReadWriteAndConsentSelfForUserAllow the Teams app to manage itself and its permission grants for a user

Application Permissions​

PermissionPurpose
AiEnterpriseInteraction.Read.AllRead Copilot interaction history, for the conversation list in the Agent Portal
User.Read.AllResolve users' full profiles for that history lookup
Application.Read.AllRead application registrations in the tenant
AgentIdentity.Read.AllRead all agent identities
AgentIdentity.ReadWrite.AllRead and write all agent identities
AgentIdentity.Create.AllCreate agent identities without an agent blueprint
AgentIdentityBlueprint.ReadWrite.AllRead and write all agent identity blueprints

After consent, review the granted set under Microsoft Entra ID → Enterprise applications → <your connector app> → Permissions. Each row should show its type, and that admin consent was granted.

The granted Microsoft Graph permissions on the connector app's enterprise application, showing the type and consent state of each
Grounding scopes are not optional

Copilot grounds its answers in the user's own Microsoft 365 content. Microsoft rejects the chat call with a 403 when a grounding scope the request needs has not been consented. If you trim this set, keep the grounding permissions. Also add Sites.Read.All (SharePoint sites) and ExternalItem.Read.All (Graph connectors and external items) if your users ground answers in that content.

The gateway reports a missing scope as Consent required, not as a license problem. It reads the tenant's permissions again on the next request after consent is granted, so no restart is needed.

The chat call itself always uses the delegated token. The application permissions serve only the tenant-wide reads the Agent Portal performs outside a user session, such as the Copilot conversation history list.

Expose the API Scope​

The sign-in token the gateway exchanges On-Behalf-Of must be issued for this app, not directly for Microsoft Graph. The connector app therefore exposes a scope that the Agent Portal requests at sign-in.

The Expose an API blade, where the connector app's scope is defined
  1. Under the connector app, go to Expose an API.
  2. For Application ID URI, accept the default api://<middle-tier-client-id>.
  3. Click + Add a scope, and enter the values in the following table. The full scope value becomes api://<middle-tier-client-id>/access_as_user.
  4. Under Authorized client applications, click + Add a client application.
  5. Add the Agent Portal app's client ID, and select the access_as_user scope. This preauthorizes the portal, so users are not prompted to consent a second time.
FieldValue
Scope nameaccess_as_user
Who can consentAdmins and users
Admin consent display nameAllow accessing Copilot APIs
StateEnabled

Adding the authorized client needs the Agent Portal app's client ID, which you create in Register the Agent Portal app. Register the portal app first, or return to this step afterward. Either order works.

Create the Client Secret​

  1. Under the connector app, go to Certificates & secrets → Client secrets → + New client secret.
  2. Add a description, and choose an expiry that follows your organization's policy.
  3. Copy the secret's Value immediately. Entra shows it only once.
Store the secret safely

Keep the secret in your password manager, never in a ticket or chat. Enter the Value, not the Secret ID, directly in the connector's secret field in the gateway console, where it is stored encrypted.

Register the Agent Portal App (AgentPassPortal)​

  1. Go to App registrations → + New registration.

  2. Name the app, for example AgentPass Copilot Portal, choose the same single-tenant account type, and click Register.

  3. On the Overview blade, copy the identifiers listed in the following table.

    The Agent Portal app's Overview blade in Microsoft Entra
  4. Go to Authentication → Add a platform → Single-page application.

  5. Add the redirect URI: your gateway's public origin plus /portal/, such as https://<your-gateway-host>/portal/.

    Adding the Agent Portal redirect URI as a single-page application platform
  6. Go to API permissions → + Add a permission → My APIs, select the connector app, select access_as_user, and click Add. The portal app is one of the connector app's authorized client applications, so it needs no extra admin consent.

The portal app's Overview blade gives you these values.

FieldUsed as
Application (client) IDThe connector's Portal app (client) ID
Directory (tenant) IDThe same tenant as the connector app
Register the redirect URI as a single-page application

Register the redirect URI under Single-page application, which uses PKCE and CORS, not under Web. The trailing slash must match exactly what the portal sends.

Values to Carry Into the Connector​

When you create the Microsoft 365 Copilot connector in the gateway console, you need these values.

Connector fieldWhere it comes from
Tenant IDConnector app Overview → Directory (tenant) ID
Client IDConnector app Overview → Application (client) ID
Client SecretThe secret Value from Certificates & secrets. Enter it in the console only
Portal app (client) IDAgent Portal app Overview → Application (client) ID
Exposed API scopeaccess_as_user, the scope name only. The gateway adds the api://<middle-tier-client-id>/ prefix
Agent Portal redirect URIYour gateway origin plus /portal/, registered on the Agent Portal app

Continue at Create the Connector.

Grant the Power Platform Permission (Copilot Studio Agents)​

Complete this section only if Portal users will chat with Microsoft Copilot Studio agents. It uses a separate delegated permission from the Power Platform API, on the same connector (middle-tier) app.

  1. Under the connector app, go to API permissions → + Add a permission → APIs my organization uses.

  2. Search for Power Platform API. If it is missing, register it first, as the following note describes.

    Adding the Power Platform API permission to the connector app
  3. Choose Delegated permissions. Under CopilotStudio, select CopilotStudio.Copilots.Invoke, and click Add.

    Selecting the CopilotStudio delegated permission scope
  4. Grant admin consent for your tenant. On-Behalf-Of cannot do interactive consent, so admin consent is required. Without it, the exchange fails, and the Agent Portal shows a consent notice.

If Power Platform API is not listed

Its service principal is not in your tenant yet. Register it once, then reopen the dialog:

az ad sp create --id 8578e004-a5c6-46e7-913e-12f58912df43

A 409 … service principal name … already in use response means it already exists. Skip creation, and search again.

Once the permission is consented, register your agents on the connector. See Registering Copilot Studio Agents for the Agent Portal.

Verify​

Check each of these before you hand the portal to users:

  • The connector app's Microsoft Graph permissions all show Granted for your tenant, with no warning.
  • The connector app's Expose an API blade lists access_as_user as enabled, and the Agent Portal app under Authorized client applications.
  • The Agent Portal app's Authentication blade shows the redirect URI as a single-page application.
  • A Copilot-licensed test user can sign in to the Agent Portal, and the chat returns a reply.
  • An unlicensed user receives the Microsoft 365 Copilot license required message. See Troubleshooting.