Dify MCP 集成實驗05認證體系——MCP Server 如何做企業級認證Dify 實驗系列 · MCP 集成 05/6 | 實驗編號DIFY-107-05基于 Dify 1.16.1 實測2026-081. 業務場景先講一個我們實際遇到的場景。一家做客服工單 SaaS 的公司要接客戶現場的真實數據源mock ERP——但客戶的安全評審第一關就是認證沒有認證的 MCP 接入根本過不了。企業數據源的鑒權有三種典型場景由簡到繁內部服務用預共享密鑰header 靜態 token、系統級服務賬號client_credentials、用戶級授權OAuth 2.1 授權碼 PKCE——管理員授權后普通用戶查詢走已授權 token。我們第一次接這類需求時第一反應是「認證不就是加個 header 嘛」。真正動手才發現——認證是三層模式、失敗形態、token 生命周期的組合題OAuth 授權碼流程涉及 Console 配置入口、回調地址、授權頁面、刷新觸發每一步沒實測過客戶問細節就露怯。我們把三種模式全部跑通把失敗形態整理成表才敢寫進服務描述。這不是個例。任何「企業客戶有真實數據源要接」的集成都是這個模式源碼確認了認證層實現PKCE S256 / 三種 grant type / MCPClientWithAuthRetry但實操流程Console 配置入口、回調地址、授權頁面、刷新觸發全部未實測——不實測交付時就是兩眼一抹黑。2. 場景痛點這個流程的痛點在認證落地時體現得最直接安全評審過不了無認證的 MCP 接入在客戶現場根本過不了安全評審——方案再漂亮第一關就卡死。OAuth 流程是最大未知點Console 配置入口、回調地址、授權頁面、刷新觸發——實操流程全沒驗證過客戶一問細節就露怯。失敗形態說不清401/403/invalid_grant 報錯形態多分不清是認證失敗還是 SSRF 攔截client_credentials 憑據錯會被誤判成「blocked by SSRF protection」——排查沒方向。授權后工具空1.16.1 工具拉取只在 create授權后 tools 空——配完授權工具反而「消失」了。本質上認證不是「加個頭」——三種模式、失敗形態、token 生命周期都要實測才能寫進服務描述。3. 方案為什么是 SDK 2.0 AuthSettings實測 Dify 連接 MCP server 的三種鑒權方式全流程自定義 headers → client_credentials → OAuth 2.1 授權碼 PKCE。選它的理由SDK 自動托管AuthSettingstoken_verifier——未授權自動 401 WWW-Authenticate自動暴露/.well-known/oauth-protected-resource/mcpRFC 9728 格式不用手寫認證中間件三模式遞進實測header內部服務→ client_credentials系統級服務賬號→ OAuth 授權碼 PKCE用戶級授權——覆蓋企業數據源的全部典型場景產出可交付「Dify MCP 認證三步走」標準操作 失敗形態表——直接寫進服務描述客戶現場照著走。這篇文章我們就用它給受保護的 ERP 數據源get_erp_order配齊三種鑒權方式走通全流程并沉淀失敗形態表。4. 整體架構MCP 調用本地開發機dify107_05_auth_server:8905/mcp受保護get_erp_order需 tokenmock OAuth 服務器uvicorn :8906/.well-known/oauth-authorization-servermetadata/authorizePKCE 授權頁auto-approve/tokenauthorization_code / client_credentials / refresh_tokenDify 服務器api含 /console/api/mcp/oauth/callback 回調端點web工具頁 MCP tab鑒權配置Console 授權回調 → token 存庫鏈路很清晰受保護 serverget_erp_order? mock OAuth 服務器metadata/authorize/token? Difyapi 回調端點 web 鑒權配置。關鍵設計是三種鑒權模式在同一個 server 上遞進實測失敗形態逐類記錄——每種模式都驗證到「授權后調用成功」為止。5. 模塊設計5.1 Server 側AuthSettings token_verifierSDK 2.0 自動托管frommcp.server.mcpserverimportMCPServer,AuthSettingsfrommcp.server.auth.middlewareimporttoken_verifier serverMCPServer(namedify107_05_auth_server,version1.0.0,authAuthSettings(issuer_urlhttp://host.docker.internal:8906,resource_server_urlhttp://localhost:8905,required_scopes[erp:read],),token_verifiertoken_verifier,# 未授權 401 WWW-Authenticate)SDK 自動托管/.well-known/oauth-protected-resource/mcpRFC 9728 格式authorization_servers 指向 issuer。5.2 三模式實測鏈路模式流程一自定義 headersprovider 配置 headers{Authorization: Bearer ***}→ 試連帶 header 通過 → 工具拉取成功二client_credentialsmock metadata grant_types[client_credentials] → provider 配 client_id/secret → POST /tokenBasic Auth→ authed三OAuth 授權碼 PKCEDCR 注冊 → authorization_urlPKCE S256state 存 Redis→ auto-approve 授權 → Dify 回調端點 → token 交換 → authed5.3 失敗形態表驗收/排查用場景報錯形態排查指引無 token 調工具server 401{error:invalid_token}→ Dify tool failed檢查 provider authed/headersclient_credentials 憑據錯mock 401 invalid_client → Dify「Client credentials flow failed…blocked by SSRF protection」誤判先本地 curl 復現區分 mock 401 vs squid 403metadata 缺字段Dify「Failed to discover OAuth metadata from server」metadata 必須含 authorization_endpoint/token_endpoint/response_types_supportedauthorize 缺參數400 invalid_requestcode_challenge/redirect_uri/state 必填PKCE 校驗失敗400 invalid_grant PKCE 校驗失敗code_verifier 與 code_challenge 不匹配token 過期/無效server 401 → MCPClientWithAuthRetry 刷新refresh_token刷新失敗則清憑據重新授權授權后工具空tools[]「Tool with name xxx not found」1.16.1 限制工具拉取只在 create授權后手動補/重導6. 運行驗證驗證項預期結果header 鑒權配置后調用成功缺 header 報錯通過client_credentials配置后自動鑒權調用成功通過auth 200 調用 succeededOAuth 授權碼 PKCE授權流程走通、token 存庫、授權后調用成功通過全自動化無真實瀏覽器token 自動刷新401 觸發 MCPClientWithAuthRetry 用 refresh_token 刷新機制源碼確認機制確認端到端過期刷新未實測失敗形態表5 類以上失敗形態 排查指引通過見 4.3認證能力清單OAuth 2.1 PKCE / client_credentials / refresh 自動刷新 / DCR / 資源發現通過7. 實戰坑坑現象修復AccessToken 必填 client_idSDK 2.0 token_verifier 返回 AccessToken 缺 client_id 報 ValidationErrortoken 校驗/構造時帶上 client_id實測metadata 必填字段client_credentials 模式 metadata 缺 authorization_endpoint/response_types 也報錯Dify OAuthMetadata 模型強制grant_types 決定模式實測client_credentials 用 Basic Authmock /token 只讀 form → invalid_client 401 → 被 ssrf_proxy 誤判「SSRF blocked」解析Authorization: Basic ***先本地 curl 復現區分實測回調端點完成交換POST auth 傳 code 報「State parameter is required」code 必須走回調端點 GET /console/api/mcp/oauth/callback?codestatestate 從 Redis 取 code_verifier實測授權后 tools 不刷新1.16.1 工具拉取只在 create授權后 tools 空手動補 DB tools 字段含 outputSchema 才字段展開或刪了重導實測token 校驗與 storemock 重啟 TOKEN_STORE內存清空 → Dify DB token server 不認 → 401演示環境放寬前綴校驗生產用共享存儲/introspection實測sync/async 坑sync def 端點里 request.json()/form() 是 async必須 async def await實測8. 實驗文檔及源碼獲取實驗文檔完整操作步驟DIFY-107-05認證體系.md源碼可直接導入dify107_05_驗證應用.ymlServer 源碼dify107_05_auth_server 目錄含 mock_oauth.py交付驗證記錄認證能力清單 失敗形態表驗證記錄-05-認證體系.md全部目錄dify-107/experiments | dify-107/dsl | dify-107/servers | dify-107/delivery文章聚焦核心配置與采坑點實驗的完整分步操作節點搭建/參數表/調試指引見實驗文檔原文。下一篇Dify MCP 集成實驗06企業級交付驗收——MCP 集成方案如何驗收與交付 你在這個實驗的場景里踩過什么坑歡迎評論區分享你的實戰經驗。 Dify MCP 集成實驗（05）：認證體系——MCP Server 如何做企業級認證？
Dify MCP 集成實驗05認證體系——MCP Server 如何做企業級認證Dify 實驗系列 · MCP 集成 05/6 | 實驗編號DIFY-107-05基于 Dify 1.16.1 實測2026-081. 業務場景先講一個我們實際遇到的場景。一家做客服工單 SaaS 的公司要接客戶現場的真實數據源mock ERP——但客戶的安全評審第一關就是認證沒有認證的 MCP 接入根本過不了。企業數據源的鑒權有三種典型場景由簡到繁內部服務用預共享密鑰header 靜態 token、系統級服務賬號client_credentials、用戶級授權OAuth 2.1 授權碼 PKCE——管理員授權后普通用戶查詢走已授權 token。我們第一次接這類需求時第一反應是「認證不就是加個 header 嘛」。真正動手才發現——認證是三層模式、失敗形態、token 生命周期的組合題OAuth 授權碼流程涉及 Console 配置入口、回調地址、授權頁面、刷新觸發每一步沒實測過客戶問細節就露怯。我們把三種模式全部跑通把失敗形態整理成表才敢寫進服務描述。這不是個例。任何「企業客戶有真實數據源要接」的集成都是這個模式源碼確認了認證層實現PKCE S256 / 三種 grant type / MCPClientWithAuthRetry但實操流程Console 配置入口、回調地址、授權頁面、刷新觸發全部未實測——不實測交付時就是兩眼一抹黑。2. 場景痛點這個流程的痛點在認證落地時體現得最直接安全評審過不了無認證的 MCP 接入在客戶現場根本過不了安全評審——方案再漂亮第一關就卡死。OAuth 流程是最大未知點Console 配置入口、回調地址、授權頁面、刷新觸發——實操流程全沒驗證過客戶一問細節就露怯。失敗形態說不清401/403/invalid_grant 報錯形態多分不清是認證失敗還是 SSRF 攔截client_credentials 憑據錯會被誤判成「blocked by SSRF protection」——排查沒方向。授權后工具空1.16.1 工具拉取只在 create授權后 tools 空——配完授權工具反而「消失」了。本質上認證不是「加個頭」——三種模式、失敗形態、token 生命周期都要實測才能寫進服務描述。3. 方案為什么是 SDK 2.0 AuthSettings實測 Dify 連接 MCP server 的三種鑒權方式全流程自定義 headers → client_credentials → OAuth 2.1 授權碼 PKCE。選它的理由SDK 自動托管AuthSettingstoken_verifier——未授權自動 401 WWW-Authenticate自動暴露/.well-known/oauth-protected-resource/mcpRFC 9728 格式不用手寫認證中間件三模式遞進實測header內部服務→ client_credentials系統級服務賬號→ OAuth 授權碼 PKCE用戶級授權——覆蓋企業數據源的全部典型場景產出可交付「Dify MCP 認證三步走」標準操作 失敗形態表——直接寫進服務描述客戶現場照著走。這篇文章我們就用它給受保護的 ERP 數據源get_erp_order配齊三種鑒權方式走通全流程并沉淀失敗形態表。4. 整體架構MCP 調用本地開發機dify107_05_auth_server:8905/mcp受保護get_erp_order需 tokenmock OAuth 服務器uvicorn :8906/.well-known/oauth-authorization-servermetadata/authorizePKCE 授權頁auto-approve/tokenauthorization_code / client_credentials / refresh_tokenDify 服務器api含 /console/api/mcp/oauth/callback 回調端點web工具頁 MCP tab鑒權配置Console 授權回調 → token 存庫鏈路很清晰受保護 serverget_erp_order? mock OAuth 服務器metadata/authorize/token? Difyapi 回調端點 web 鑒權配置。關鍵設計是三種鑒權模式在同一個 server 上遞進實測失敗形態逐類記錄——每種模式都驗證到「授權后調用成功」為止。5. 模塊設計5.1 Server 側AuthSettings token_verifierSDK 2.0 自動托管frommcp.server.mcpserverimportMCPServer,AuthSettingsfrommcp.server.auth.middlewareimporttoken_verifier serverMCPServer(namedify107_05_auth_server,version1.0.0,authAuthSettings(issuer_urlhttp://host.docker.internal:8906,resource_server_urlhttp://localhost:8905,required_scopes[erp:read],),token_verifiertoken_verifier,# 未授權 401 WWW-Authenticate)SDK 自動托管/.well-known/oauth-protected-resource/mcpRFC 9728 格式authorization_servers 指向 issuer。5.2 三模式實測鏈路模式流程一自定義 headersprovider 配置 headers{Authorization: Bearer ***}→ 試連帶 header 通過 → 工具拉取成功二client_credentialsmock metadata grant_types[client_credentials] → provider 配 client_id/secret → POST /tokenBasic Auth→ authed三OAuth 授權碼 PKCEDCR 注冊 → authorization_urlPKCE S256state 存 Redis→ auto-approve 授權 → Dify 回調端點 → token 交換 → authed5.3 失敗形態表驗收/排查用場景報錯形態排查指引無 token 調工具server 401{error:invalid_token}→ Dify tool failed檢查 provider authed/headersclient_credentials 憑據錯mock 401 invalid_client → Dify「Client credentials flow failed…blocked by SSRF protection」誤判先本地 curl 復現區分 mock 401 vs squid 403metadata 缺字段Dify「Failed to discover OAuth metadata from server」metadata 必須含 authorization_endpoint/token_endpoint/response_types_supportedauthorize 缺參數400 invalid_requestcode_challenge/redirect_uri/state 必填PKCE 校驗失敗400 invalid_grant PKCE 校驗失敗code_verifier 與 code_challenge 不匹配token 過期/無效server 401 → MCPClientWithAuthRetry 刷新refresh_token刷新失敗則清憑據重新授權授權后工具空tools[]「Tool with name xxx not found」1.16.1 限制工具拉取只在 create授權后手動補/重導6. 運行驗證驗證項預期結果header 鑒權配置后調用成功缺 header 報錯通過client_credentials配置后自動鑒權調用成功通過auth 200 調用 succeededOAuth 授權碼 PKCE授權流程走通、token 存庫、授權后調用成功通過全自動化無真實瀏覽器token 自動刷新401 觸發 MCPClientWithAuthRetry 用 refresh_token 刷新機制源碼確認機制確認端到端過期刷新未實測失敗形態表5 類以上失敗形態 排查指引通過見 4.3認證能力清單OAuth 2.1 PKCE / client_credentials / refresh 自動刷新 / DCR / 資源發現通過7. 實戰坑坑現象修復AccessToken 必填 client_idSDK 2.0 token_verifier 返回 AccessToken 缺 client_id 報 ValidationErrortoken 校驗/構造時帶上 client_id實測metadata 必填字段client_credentials 模式 metadata 缺 authorization_endpoint/response_types 也報錯Dify OAuthMetadata 模型強制grant_types 決定模式實測client_credentials 用 Basic Authmock /token 只讀 form → invalid_client 401 → 被 ssrf_proxy 誤判「SSRF blocked」解析Authorization: Basic ***先本地 curl 復現區分實測回調端點完成交換POST auth 傳 code 報「State parameter is required」code 必須走回調端點 GET /console/api/mcp/oauth/callback?codestatestate 從 Redis 取 code_verifier實測授權后 tools 不刷新1.16.1 工具拉取只在 create授權后 tools 空手動補 DB tools 字段含 outputSchema 才字段展開或刪了重導實測token 校驗與 storemock 重啟 TOKEN_STORE內存清空 → Dify DB token server 不認 → 401演示環境放寬前綴校驗生產用共享存儲/introspection實測sync/async 坑sync def 端點里 request.json()/form() 是 async必須 async def await實測8. 實驗文檔及源碼獲取實驗文檔完整操作步驟DIFY-107-05認證體系.md源碼可直接導入dify107_05_驗證應用.ymlServer 源碼dify107_05_auth_server 目錄含 mock_oauth.py交付驗證記錄認證能力清單 失敗形態表驗證記錄-05-認證體系.md全部目錄dify-107/experiments | dify-107/dsl | dify-107/servers | dify-107/delivery文章聚焦核心配置與采坑點實驗的完整分步操作節點搭建/參數表/調試指引見實驗文檔原文。下一篇Dify MCP 集成實驗06企業級交付驗收——MCP 集成方案如何驗收與交付 你在這個實驗的場景里踩過什么坑歡迎評論區分享你的實戰經驗。