秘訣
推薦項目: 從 Work IQ 開發工具 開始,支援專業程式碼宣告式代理程式和外掛程式案例。 請參閱 WIQD 快速入門。 工具組式指示仍然適用於需要工具組的指示的現有專案和工作流程。 在選擇工具之前,請先檢查 功能和目標體驗支援 : WIQD 不會以自訂引擎代理程式為目標。
外掛程式可以使用透過 OAuth 2.0 授權碼流程取得的持有人權杖 (MCP) 伺服器或 API 存取模型內容通訊協定,並預設啟用用於代碼交換 (PKCE) 支援的證明金鑰。 在此流程中,Microsoft 365 Copilot 會開啟登入體驗,OAuth 提供者會傳回授權回應給 Microsoft Teams,而 Teams 會交換授權碼換成權杖。
本文使用 MCP 外掛程式作為預設逐步解說。 除非有特別說明,否則相同的步驟也適用於從 OpenAPI 文件建置的 API 外掛程式。
以三個步驟設定 OAuth 2.0 驗證:向身分識別提供者註冊 OAuth 用戶端、設定重新導向 URI,以及建立 OAuth 2.0 設定。
步驟 1:向身分提供者註冊 OAuth 用戶端
向 OAuth 2.0 提供者註冊應用程式 (身分識別提供者) 以取得 用戶端識別碼 ,對於機密 (Web) 用戶端,則需要 用戶端密碼。 當您在 步驟 3 中建立 OAuth 2.0 設定時,請提供這些值。
對於需要授權的 MCP 伺服器,請將執行階段驗證物件的內容設定type為 OAuthPluginVault。
None 且 ApiKeyPluginVault 不適用於需要授權的 MCP 伺服器。 資訊清單中只會儲存驗證設定識別碼,不會寫入用戶端識別碼、用戶端密碼或權杖。 若要動態註冊用戶端,而不是靜態註冊,請保留type為OAuthPluginVault並透過動態用戶端註冊 (DCR) 建立驗證設定,這不適用於受 Microsoft Entra ID 保護的伺服器。
注意
這些值適用於宣告式代理程式動作的 MCP 外掛程式資訊清單。 如果您改為透過 agentConnectors 在 Microsoft 365 應用程式資訊清單中設定外掛程式的遠端 MCP 伺服器,請使用 OAuthPluginVault 或,對於支援 DCR DynamicClientRegistration的伺服器, 。 應用程式資訊清單結構描述 1.29 和 1.30 也包含 AzureKeyVault,但結構描述接受不會在目標體驗中建立支援。 如需設定和主機需求,請參閱為 Microsoft 365 Copilot 外掛程式設定遠端 MCP 伺服器。
步驟 2:設定重新導向 URI
將下列重新導向 URI (也稱為授權回呼 URL) 新增至您的 OAuth 提供者註冊:
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect
這是使用者登入後,OAuth 提供者傳送授權回應的 URL。 Teams 會在此回呼 URL 收到回應,並交換權杖的授權碼。 如果您未向提供者註冊此重新導向 URI,登入會失敗。 每個外掛程式和提供者的重新導向 URI 都相同 - 您不需要針對每個應用程式進行自訂。
步驟 3:建立 OAuth 2.0 驗證組態
OAuth 2.0 驗證仰賴驗證設定 (驗證設定) - 儲存在 Microsoft 企業版權杖存放區中的記錄,Microsoft 365 Copilot 用來取得並重新整理 MCP 外掛程式的權杖。 從支援的專業程式碼專案的 WIQD 開始。 工具組、開發人員技能和 Teams 開發人員入口網站程序仍然可用做為替代方案。
無論您如何建立,驗證設定都有您的外掛程式資訊清單參考的 驗證設定識別碼 。
使用 Work IQ 開發工具 (建議)
針對 MCP 巨集指令,請搭配--mcp-server-url使用 wiqd agent add action 和 --mcp-auth-type oauth。 如有需要,請--mcp-scopes透過 --mcp-client-id和 --mcp-client-secret 提供已註冊客戶的詳細資料。 針對 OpenAPI 動作,請使用 --openapi-auth-identity-provider oauth 和對應 --openapi-auth-client-id的 、 --openapi-auth-client-secret及 --openapi-auth-scopes options。 當您的提供者支援時,為 --openapi-auth-pkce 該 OpenAPI 路由啟用 PKCE。 請參閱 WIQD 動作命令指引。
對於現有的外掛程式資訊清單,請搭配--plugin-manifest使用 wiqd agent add auth 、 --auth-name和 --auth-type oauth。 使用該命令的 OAuth 端點、範圍和用戶端選項;其 PKCE 選項為 --oauth-pkce。 為您的環境完成專案的佈建工作流程。 如需自動用戶端註冊而非靜態 OAuth,請遵循 WIQD DCR 路由。
使用 Microsoft 365 代理程式工具組
當您使用 MCP 外掛程式建置代理程式時 (如果伺服器需要驗證) 或從 Microsoft 365 Agents Toolkit 中的現有 OpenAPI 文件建立 API 外掛程式,工具組會提示您輸入 OAuth 用戶端識別碼、用戶端密碼和範圍。 Agents Toolkit 會從 MCP 伺服器 (的已知端點或 API 外掛程式) 的 OpenAPI 文件擷取授權、權杖和重新整理端點,在企業權杖存放區中建立驗證組態,並自動更新外掛程式資訊清單中的 執行階段驗證物件 。
注意
對於 API 外掛程式,您必須在 OpenAPI 文件中定義 securitySchemes 屬性,以便 Agents Toolkit 可以讀取 OAuth 詳細資料。 如需詳細資訊,請參閱 OAuth 2.0。
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: <authorization_url>
tokenUrl: <token_url>
refreshUrl: <refresh_url>
scopes:
scope: description
預設會啟用 PKCE,因為許多組織會封鎖用戶端密碼。
isPKCEEnabled只有當您的 OAuth 提供者不支援 PKCE 時,才在佈建代理程式之前,才在代理程式專案中設定為 false in m365agents.yml。
isPKCEEnabled: false
若要完全避免用戶端機密,請向您的提供者註冊公用用戶端 - 單頁應用程式平臺,而不是 Web 平臺 - 並讓 PKCE 保護程式碼交換。
使用宣告式代理程式開發人員技能
宣告式代理程式開發人員技能 (declarative-agent-developer) 是 Microsoft Work IQ 中的代理程式技能,包含建置宣告式代理程式所需的知識。 您可以使用自然語言向 Copilot 或 GitHub CLI 描述您想要的內容,而技能會搭建宣告式代理程式、新增 MCP 外掛程式,並為您處理驗證設定。 此技能僅支援 MCP 外掛程式。 針對 OAuth 2.0,它支援靜態註冊和 動態用戶端註冊 (DCR) :它會在企業權杖存放區中建立驗證設定,並更新外掛程式資訊清單,而無需手動步驟。
秘訣
如需使用宣告式代理程式開發人員技能的影片逐步解說,請參閱 使用宣告式代理程式開發人員技能建置宣告式代理程式。
使用 Teams 開發人員入口網站
如果您使用 Agents Toolkit 或宣告式代理程式開發人員技能,則在 Teams 開發人員入口網站註冊為選擇性。 當您想要手動建立驗證組態時,或更常見的是管理 Agents Toolkit 或技能已建立的授權組態時,請使用它。 在入口網站中,您可以將驗證設定限制為特定 Teams 應用程式或 Microsoft 365 組織,並修改其他屬性。
Teams 開發人員入口網站中的 OAuth 用戶端註冊會將代理程式的外掛程式設定連線到為您的 MCP 伺服器或 API 發行權杖的 OAuth 提供者註冊。 此註冊中的值必須符合您的 OAuth 提供者、外掛程式資訊清單和受保護的 API 端點。 不相符的基底 URL、應用程式限制或驗證設定識別碼可能會讓使用者無法登入,或可能封鎖權杖交換。
警告
將註冊限制 為任何 Teams 應用程式。 僅限於特定 Teams 應用程式的註冊會繫結至該 Teams 應用程式識別碼。 Microsoft 365 Copilot 在呼叫 MCP 伺服器時無法解析該識別碼,因此佈建會順利完成,然後每個工具呼叫都會傳回404錯誤。
開啟 Teams 開發人員入口網站。 選取 [ 工具] ->[OAuth 用戶端註冊]。
如果您沒有現有註冊,請選取 [註冊用戶端]。 如果您有現有註冊,請選取 新增 OAuth 用戶端註冊。
填寫下列欄位。
- 註冊名稱:註冊的易記名稱。
-
基底 URL:您的 API 基底 URL。 此值應對應至 MCP 型外掛程式的外掛程式資訊清單中 MCP 伺服器規格物件屬性中的
urlURL,或 API 外掛程式的 OpenAPI 文件中陣列中的servers項目。 - 依組織限制使用情況:選取哪些 Microsoft 365 組織可以使用此 OAuth 註冊來存取您的 API 端點。 僅將 [我的組織 ] 用於開發或在一個租用戶中進行測試。 當外掛程式必須跨租用戶使用時 ,使用任何 Microsoft 365 組織 。
- 依應用程式限制使用方式:選取任何 Teams 應用程式。 請勿將註冊繫結至 MCP 伺服器的 現有 Teams 應用程式識別碼 。 如果您改為使用 Microsoft 365 Agents Toolkit 佈建驗證組態,則 m365agents.yml 中的動作中的
oauth/register對等設定為applicableToApps: AnyApp。 即使會使欄位變成惰性,仍AnyApp保留appId該欄位在該動作中,因為佈建驅動程式會無條件驗證appId,移除它會中斷佈建。 - 用戶端識別碼:OAuth 2.0 提供者所發行的用戶端識別碼或應用程式識別碼。
- 用戶端密碼:由 OAuth 2.0 提供者所發行的用戶端密碼。
- 授權端點:來自 OAuth 2.0 提供者的 URL,應用程式用於 要求授權碼。
- 權杖端點:來自 OAuth 2.0 提供者的 URL,應用程式用來 兌換存取權杖的代碼。
- 重新整理端點:來自 OAuth 2.0 提供者的 URL,應用程式用於 重新整理存取權杖。
-
範圍:您的外掛程式向OAuth提供者要求的許可權。 使用提供者和 API 所需的範圍值。 如果您的提供者使用 Microsoft 身分識別平台,且您的外掛程式需要重新整理權杖,請包含
offline_access任何 API 特定的委派範圍。 - 啟用 PKCE) (代碼交換的證明金鑰 :讓此設定保持啟用。 預設為開啟;只有在您的 OAuth 提供者不支援 PKCE 時,才停用它。
選取 [儲存]。
完成註冊會建立驗證設定,並產生驗證設定 識別碼 (目前在 Teams 開發人員入口網站) 中標示為 OAuth 用戶端註冊識別碼 。
將驗證設定識別碼新增至外掛程式資訊清單
當您在 Teams 開發人員入口網站手動建立驗證設定時,請將執行階段驗證物件的屬性設定type為 OAuthPluginVault,並將 設定為reference_id驗證設定識別碼。 Agents Toolkit 和宣告式代理程式開發人員技能可為您執行此工作。
"auth": {
"type": "OAuthPluginVault",
"reference_id": "auth config ID"
},
Microsoft Entra ID 考量
當您使用 Microsoft Entra ID 保護 MCP 伺服器時,會套用三個限制,且您無法在工具中解決。
- 無法使用動態用戶端註冊。 Microsoft Entra ID 不會發佈 RFC 7591 註冊端點,因此動態用戶端註冊沒有任何可註冊的內容。 遵循本文中的步驟,靜態註冊 OAuth 用戶端。
-
agentConnectors節點沒有 Microsoft Entra 授權類型。 不同於composeExtensions,agentConnectorsMicrosoft 365 應用程式資訊清單中的節點沒有microsoftEntra授權類型。 受 Microsoft Entra ID 保護的 MCP 伺服器一律需要您在 Microsoft Entra ID 中自行註冊的應用程式,以及 OAuth 驗證設定,即使伺服器前端是第一方 Microsoft API。 - 佈建時不會驗證範圍同意。 佈建不會檢查您要求的範圍是否可獲同意。 無法同意成功佈建的範圍,然後稍後因 [需要系統管理員核准] 而失敗,而且您和您的租用戶系統管理員都看不到資源應用程式。在佈建之前,確認系統管理員已同意範圍。
管理驗證設定
oauth/register m365agents.yml 中的動作只會建立驗證設定或跳過建立,並不會重寫現有的記錄。
- 如果已有值,則
configurationId動作不會執行任何動作。 - 如果指向您已刪除的註冊,則
configurationId該動作會警告您,並且不執行任何動作。 - 若要變更現有登錄中的值,請使用巨
oauth/update集指令。 - 若要刪除註冊,請使用 Teams 開發人員入口網站。 這是唯一可以刪除檔案的位置。
登出
注意
使用者可以從 Chat 設定> Microsoft 365 Copilot 中的代理程式登出代理程式。 此動作會清除儲存的 OAuth 權杖。