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 集成方案如何验收与交付 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。