針對 MCP 和 API 外掛程式驗證進行疑難排解

本文涵蓋在 Microsoft 365 Copilot 中執行的代理程式中設定模型內容通訊協定 (MCP) 和 API 外掛程式驗證時的常見問題和疑問。

若要在代理程式回應中查看驗證錯誤, 請啟用開發人員模式。 本文中的許多錯誤都會出現在偵錯資訊卡中。

使用者無法登入或權杖交換失敗

OAuth 提供者、驗證設定與外掛程式資訊清單之間的值不相符是登入失敗的最常見原因。 請確認下列值:

  • 驗證設定中的 基底 URL 符合 url MCP 外掛程式的外掛程式資訊清單中 MCP 伺服器規格物件 的屬性,或 API 外掛程式的 OpenAPI 文件中陣列中的 servers 項目。
  • 重新導向 URI https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect 已向 OAuth 提供者註冊為允許的重新導向 URI 或授權回呼 URL。
  • reference_id 執行階段中的驗證物件符合 Microsoft Teams 開發人員入口網站所產生的驗證設定識別碼。
  • 應用程式限制 ([限制使用 ]) 和 [組織限制] ([ 由組織) 設定限制使用] 會允許您的 Teams 應用程式和租用戶。

307 Temporary Redirect 從權杖端點

不支援從權杖端點傳回 307 Temporary Redirect HTTP 狀態代碼的 OAuth 2.0 伺服器。 將提供者設定為使用直接權杖端點。

解除安裝代理程式後,儲存的認證會持續存在

使用者可以從 Chat 設定> Microsoft 365 Copilot 中的代理程式登出代理程式。 針對 OAuth 2.0,登出會清除儲存的權杖。 針對 Microsoft Entra SSO,權杖無法直接清除,而且可能會在代理程式解除安裝後因為 SSO 快取、租用戶設定或用戶端差異而繼續保留。

若要強制重新驗證 Entra SSO,請使用 Microsoft Graph revokeSignInSessions API 移除使用者的同意或撤銷其工作階段。

如果您的 MCP 伺服器或 API 使用 代理流程 來存取另一個需要使用者授與同意的 Web API,請傳回 401 Unauthorized 錯誤,讓代理程式提示使用者登入以授與同意。

也請確認:

  • Teams 開發人員入口網站所產生的應用程式識別碼 URI 會新增至 Entra 應用程式註冊的 identifierUris。
  • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect會新增至 Web 平台的重新導向 URI 中。
  • Microsoft 企業版權杖存放區用戶端識別碼 (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) 會新增為 公開 API 下的允許的用戶端應用程式,如果您驗證用戶端應用程式識別碼,則新增為允許的權杖對象。

驗證設定與外掛程式之間的應用程式識別碼不符

如果您在偵錯資訊卡中看到類似下列的錯誤:

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

移至 Teams 開發人員入口網站。 尋找您的 OAuth 用戶端或單一登入 (SSO) 用戶端註冊,並驗證外掛程式中的應用程式識別碼與已註冊的應用程式識別碼相符。

驗證設定中的基底 URL 與外掛程式不符

如果您在偵錯資訊卡中看到類似下列的錯誤:

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

移至 Teams 開發人員入口網站。 尋找您的 OAuth 用戶端或 SSO 用戶端註冊,並驗證外掛程式中的 MCP 伺服器 URL 符合已註冊的基底 URL。

外掛程式資訊清單中的參考識別碼不正確或遺失

如果您在偵錯資訊卡中看到類似下列的錯誤:

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

移至 Teams 開發人員入口網站。 尋找您的 OAuth 用戶端或 SSO 用戶端註冊,並確認 MCP 伺服器執行階段 auth.reference_id 中的識別碼與 Teams 開發人員入口網站中的驗證設定識別碼相符。

組織原則限制存取

如果您在偵錯資訊卡中看到類似下列的錯誤:

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

請連絡貴組織的系統管理員,以檢閱並啟用應用程式的存取權。

[登入] 按鈕非使用中或顯示一般錯誤

如果您的 [登入] 按鈕處於非使用中或停用狀態,或選取它時出現一般性的「無法處理要求」錯誤,則這種情況可能表示暫時驗證或工作階段問題。 重試查詢。 如果問題持續發生,請重新安裝應用程式或連絡貴組織的系統管理員。

無法開啟登入快顯視窗

在瀏覽器的設定中啟用網站的快顯視窗,然後再試一次。

登入快顯視窗隨即開啟,但停滯或永遠無法關閉

如果登入快顯視窗開啟,且使用者完成驗證,但快顯視窗從未關閉,且 Copilot 未收到驗證結果,則快顯視窗的 window.opener 參考很可能在 OAuth 重新導向鏈結期間損毀。 沒有 window.opener,快顯視窗無法將驗證結果傳達回 Copilot。 常見的徵狀是第一次登入失敗,但在重試時成功,因為快取的認證會略過破壞的 window.opener頁面。

檢查 OAuth 重新導向鏈結中的下列項目。

  • JavaScript 無效化 window.opener: 某些登入頁面設置 window.opener = null 為針對反向 tabnabbing 的一攬子安全措施。 如果驗證重新導向鏈結中的任何頁面執行此程式碼,快顯視窗就會失去與 Copilot 的連線。 將索引標籤捕捉保護範圍限定為僅限使用者起始的瀏覽,而且在快顯視窗重新導向期間不會清除 window.opener 。
  • Cross-Origin-Opener-Policy 標頭設定為 same-origin: 如果重新導向鏈結中的任何頁面提供 Cross-Origin-Opener-Policy: same-origin 回應標頭,瀏覽器會永久切斷 window.opener 跨原始來源瀏覽上的參照。 請確定 OAuth 重新導向鏈結中的所有頁面都省 Cross-Origin-Opener-Policy 略預設為 unsafe-none) 的標頭 (或明確設定為 unsafe-none。
  • rel="noopener"使用 : 錨定標籤,其中包含rel="noopener"目標頁面的條帶window.opener。 請勿用於 rel="noopener" 驗證快顯視窗中的瀏覽。

若要偵錯此問題,請在快顯視窗中開啟瀏覽器的開發人員工具,並在重新導向鏈結的每個步驟中輸入 window.opener 主 控台 。 如果傳回null在最後一次重新導向之前,請window.opener識別哪個頁面清除了它。 您也可以檢查 [網路 ] 索引標籤回應標頭, Cross-Origin-Opener-Policy 以取得鏈結中每個頁面上的值。

認證不正確錯誤

如果您在登入快顯視窗或聊天回應中看到「認證不正確」錯誤,請確定您輸入正確的認證。 如果錯誤持續發生,請確定使用者具有必要的權限。

找不到登入 URL

將應用程式解除安裝並重新安裝,然後再次嘗試登入。

驗證期間發生內部伺服器錯誤

檢查驗證快顯視窗中的詳細資料,並針對權限問題與貴組織的系統管理員連絡。

如果出現要求權限或商務理由的同意對話方塊,請檢閱要求的權限,並在必要時提供商務理由。 如果您不確定,或同意對話方塊要求需要系統管理員同意的權限,請連絡貴組織的系統管理員。