Chỉnh sửa

Troubleshoot MCP and API plugin authentication

This article covers common problems and questions when you configure authentication for Model Context Protocol (MCP) and API plugins in agents running in Microsoft 365 Copilot.

To see authentication errors in agent responses, enable developer mode. Many of the errors in this article appear in the debug information card.

Users can't sign in or token exchange fails

Mismatched values between your OAuth provider, your auth config, and your plugin manifest are the most common cause of sign-in failures. Verify the following values:

  • The Base URL in your auth config matches the url property of the MCP server spec object in the plugin manifest for MCP plugins, or an entry in the servers array in your OpenAPI document for API plugins.
  • The redirect URI https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect is registered as an allowed redirect URI or authorization callback URL with your OAuth provider.
  • The reference_id in the runtime authentication object matches the auth config ID generated by the Microsoft Teams developer portal.
  • The app restriction (Restrict usage by app) and org restriction (Restrict usage by org) settings allow your Teams app and tenant.

307 Temporary Redirect from the token endpoint

OAuth 2.0 servers that return 307 Temporary Redirect HTTP status codes from their token endpoint aren't supported. Configure your provider to use a direct token endpoint.

Stored credentials persist after uninstalling the agent

Users can sign out of an agent from Chat settings > Agents in Microsoft 365 Copilot. For OAuth 2.0, signing out clears the stored token. For Microsoft Entra SSO, the token can't be cleared directly and might continue to persist after an agent is uninstalled due to SSO caching, tenant settings, or client differences.

To force reauthentication for Entra SSO, remove the user's consent or revoke their sessions by using the Microsoft Graph revokeSignInSessions API.

If your MCP server or API uses the on-behalf-of flow to get access to another web API that requires the user to grant consent, return a 401 Unauthorized error to cause the agent to prompt the user to sign in to grant consent.

Also confirm that:

  • The Application ID URI generated by the Teams developer portal is added to the identifierUris of your Entra app registration.
  • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect is added to the Redirect URIs in the Web platform.
  • The Microsoft Enterprise token store client ID (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) is added as an allowed client application under Expose an API and, if you validate the client app ID, as an allowed token audience.

App ID mismatch between auth configuration and plugin

If you see errors in your debug information card similar to:

OAuth authentication failed: The App ID used in the request does not match the App ID in the authentication configuration. (HTTP 404)

Go to the Teams developer portal. Find your OAuth client or single sign-on (SSO) client registration and verify that the App ID in your plugin matches the registered App ID.

Base URL in auth configuration doesn't match the plugin

If you see errors in your debug information card similar to:

OAuth authentication failed: The base URL in your authentication configuration does not match the server URL. (HTTP 401)

Go to the Teams developer portal. Find your OAuth client or SSO client registration and verify that the MCP server URL in your plugin matches the registered base URL.

Reference ID in the plugin manifest is incorrect or missing

If you see errors in your debug information card similar to:

OAuth authentication failed: No matching configuration found for referenceID in 'runtime.auth' section of the action manifest

Go to the Teams developer portal. Find your OAuth client or SSO client registration and verify that the ID in your MCP server's runtime's auth.reference_id matches the auth config ID in the Teams developer portal.

Organization policy restricts access

If you see errors in your debug information card similar to:

OAuth authentication failed: Access is restricted by your organization's policy. (HTTP 404)

Contact your organization's administrators to review and enable access for your app.

Sign in button is inactive or displays general error

If your sign in button is inactive or disabled, or selecting it gives a general "Request cannot be processed" error, this condition might indicate temporary authentication or session problems. Retry the query. If the problem continues, reinstall the app or contact your organization's administrators.

Sign in popup fails to open

Enable popups for the site in your browser's settings and try again.

Sign in popup opens but gets stuck or never closes

If the sign in popup opens and the user completes authentication, but the popup never closes and Copilot doesn't receive the auth result, the popup's window.opener reference was likely destroyed during the OAuth redirect chain. Without window.opener, the popup can't communicate the auth result back to Copilot. A common symptom is that sign in fails the first time but succeeds on retry, because cached credentials skip the page that destroyed window.opener.

Check the following items in your OAuth redirect chain.

  • JavaScript nullifying window.opener: Some login pages set window.opener = null as a blanket security measure against reverse tabnabbing. If any page in the auth redirect chain runs this code, the popup loses its connection to Copilot. Scope tabnabbing protections to user-initiated navigation only, and don't clear window.opener during in-popup redirects.
  • Cross-Origin-Opener-Policy header set to same-origin: If any page in the redirect chain serves a Cross-Origin-Opener-Policy: same-origin response header, the browser permanently severs the window.opener reference on cross-origin navigation. Ensure all pages in your OAuth redirect chain either omit the Cross-Origin-Opener-Policy header (which defaults to unsafe-none) or explicitly set it to unsafe-none.
  • Links using rel="noopener": Anchor tags with rel="noopener" strip window.opener from the target page. Don't use rel="noopener" for navigation within the auth popup.

To debug this issue, open your browser's developer tools on the popup window and type window.opener in the Console at each step of the redirect chain. If window.opener returns null before the final redirect, identify which page cleared it. You can also check the Network tab response headers for Cross-Origin-Opener-Policy values on each page in the chain.

Incorrect credentials error

If you see an "Incorrect credentials" error in the sign in popup or chat response, make sure you're entering the correct credentials. If the error persists, ensure that the user has the required permissions.

Sign in URL not found

Uninstall and reinstall the app, and then try signing in again.

Internal server error during authentication

Check details in the authentication popup and contact your organization's administrators for permissions problems.

If a consent dialog appears requesting permissions or business justification, review the requested permissions and provide a business justification if necessary. If you're unsure, or if the consent dialog requests permissions that require admin consent, contact your organization's administrators.

Related content

  • Last updated on