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