Tornevall Networks

← Back to docs

Microsoft 365 Copilot Connector

Microsoft 365 Copilot Connector

Tools exposes Microsoft 365 Copilot through two entry points:

  • /admin/copilot for administration, Microsoft account connection and direct testing.
  • POST /api/ai/copilot/respond for external API clients.

Both paths call Microsoft 365 Copilot directly through Microsoft Graph. Copilot does not use OpenAI Engine and has no OpenAI fallback.

Authentication model

Microsoft 365 Copilot Chat requires delegated authentication with a work or school account. Application-only authentication and personal Microsoft accounts are not supported for Copilot Chat.

The environment-backed Copilot setup uses the copilot Microsoft profile for the confidential OAuth application's client ID and client secret. The tenant configured on that profile is the app registration's home tenant; it is not assumed to be the home tenant of every licensed Copilot user.

Browser sign-in uses Microsoft's organizations authority. This lets a licensed work/school account authenticate in its own Entra organization instead of being incorrectly forced into the app registration's home tenant. The Copilot app registration must therefore support Accounts in any organizational directory (AzureADMultipleOrgs) when users from another organization are expected to connect. The required delegated permissions must also be consented in the user's organization.

Other Microsoft integrations can continue to use their own Microsoft profile independently.

The supported sign-in sequence is:

  1. A tenant administrator grants the required delegated Microsoft Graph permissions from /admin/copilot when tenant-wide consent is required.
  2. The Copilot user chooses Connect/reconnect Microsoft 365 Copilot.
  3. Tools starts the normal browser authorization-code flow through the organizations authority and explicitly asks Microsoft to select an account.
  4. The user signs in with the work or school account that has the Microsoft 365 Copilot entitlement.
  5. Microsoft resolves the user's home organization and issues the delegated token for the configured Copilot application.
  6. Tools validates that the token is organizational, was issued to the configured Copilot application and contains the required Graph permissions before the connection is marked ready.
  7. A direct prompt test is sent to Microsoft 365 Copilot.

Tools does not use Microsoft device-code authentication for this web-app flow. A tenant may intentionally block device-code authentication through Conditional Access even when the account credentials are valid.

Admin flow

On /admin/copilot, an administrator can:

  • manage Copilot tenant setups
  • delegate a setup to a Tools user
  • grant tenant-wide Microsoft consent where required
  • connect or reconnect a licensed Microsoft account
  • run a real Microsoft 365 Copilot prompt test

For a multitenant Copilot app, admin consent is granted in the organization selected by the signing administrator. It is not permanently pinned to the app registration's home tenant.

The direct test creates a conversation through POST /beta/copilot/conversations and sends the prompt through POST /beta/copilot/conversations/{conversationId}/chat. A test succeeds only when Microsoft returns an actual Copilot response.

Required Microsoft Graph permissions

The reconnect flow requests the OAuth helper scopes offline_access, openid, profile and User.Read, together with these Copilot permissions:

  • Sites.Read.All
  • Mail.Read
  • People.Read.All
  • OnlineMeetingTranscript.Read.All
  • Chat.Read
  • ChannelMessage.Read.All
  • ExternalItem.Read.All

Some permissions require administrator approval. If any required Graph permission is missing, Tools stops the Copilot request and asks for consent/reconnect instead of falling back to another AI provider.

Connection validation

Tools validates that:

  • the delegated token belongs to an organizational work/school tenant and not the personal Microsoft account tenant
  • the token was issued to the configured Copilot application
  • all required delegated Graph permissions are present
  • the connected account is usable before Microsoft Graph is called

A Microsoft 365 Copilot entitlement is also required for the signed-in user.

When Microsoft says "You don't have access"

If Microsoft reports that the selected user does not exist in the app's tenant and must be added as an external user, this commonly corresponds to AADSTS50020. For an intended cross-tenant organizational Copilot connection, do not add the normal Copilot user as a guest merely to satisfy a tenant-pinned login. Verify both of these instead:

  • Tools is using the organizations authority rather than https://login.microsoftonline.com/<app-home-tenant>.
  • The Copilot app registration supports Accounts in any organizational directory (AzureADMultipleOrgs).

If the app registration is still single-tenant (AzureADMyOrg), Microsoft will reject native users from another organization even when Tools uses the correct organizational authority. Change the app's supported account type before retrying the browser reconnect.

A successful password/sign-in followed by another access-denied page can also be caused by Conditional Access, application assignment, consent policy or another Entra access rule. Inspect the Microsoft Entra sign-in event and its AADSTS code for the exact blocker. If administrator consent has not been granted for the required Graph permissions in the user's organization, run Grant tenant admin consent + reconnect first.

External API

External clients use:

POST /api/ai/copilot/respond

The client authenticates to Tools with a bearer token that has the ai.copilot scope. Tools resolves that token to a Tools user and uses the user's delegated Microsoft 365 Copilot connection.

Example:

curl -X POST "https://tools.example.test/api/ai/copilot/respond" \
  -H "Authorization: Bearer YOUR_TOOLS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_prompt": "Summarize this issue in three bullets.",
    "response_language": "en",
    "use_web_search": false
  }'

At least one of context and user_prompt is required. Supported request fields include context, user_prompt, modifier, previous_reply, mood, custom_mood, instructions, custom_instruction, response_language, use_web_search, web_search_required and an administrator-only connector_slug override.

Microsoft 365 Copilot controls model selection. OpenAI model names, reasoning effort, temperature and OpenAI token limits do not control this connector.

A successful response includes ok: true, the Microsoft 365 Copilot response text, connector metadata and diagnostics identifying Microsoft Graph/Microsoft 365 Copilot as the upstream provider.

Live release validation

Copilot changes are not considered live-verified by application credentials alone. The live CI gate must receive a real answer from Microsoft 365 Copilot.

The preferred live test calls the deployed Tools Copilot API with a protected bearer token whose Tools user has already completed browser OAuth with the licensed Microsoft account. A pre-seeded delegated Microsoft refresh token issued by the same browser authorization-code flow can be used as a direct Graph fallback.

The live gate does not bootstrap with device code. It fails when no delegated live identity is configured, when tenant/client/scope validation fails, or when Microsoft returns no usable Copilot answer. Authentication tokens and secrets are never printed.

Common API errors

  • 401: the Tools user could not be identified.
  • 403: Copilot access, organizational token validation or required Microsoft Graph permission is missing.
  • 409: the Microsoft account is missing or needs reconnecting.
  • 422: the prompt or connector request is invalid.
  • 502: Microsoft Graph returned an unusable response or could not be reached.

Copilot request operations are audit logged separately from the normal application log. OAuth operations record safe action/result and diagnostic identifiers without storing OAuth state, authorization codes, access tokens, refresh tokens or client secrets.