泛微E9与金蝶云星空单点登录集成：Token中转+Python插件免登方案

做了这么多年企业信息化集成被问得最频繁的问题就是能不能别让用户记那么多密码。尤其是办公环境同时用泛微E9和金蝶云星空的单位OA里走审批ERP里做单据两边屏幕来回切账号密码还不一样。用户进不去金蝶第一时间就在群里IT最后背锅的永远是做实施的人。这篇文章聊的就是怎么把这两套系统打通做单点登录用户从泛微E9里点一个链接浏览器自动进入金蝶云星空整个过程不需要第二次输账号密码。方案不引入第三方认证中间件完全依赖泛微E9的集成接口加上金蝶云星空自带的Python插件能力来实现部署简单、后期可控。只要两边系统版本不是特别老照着这个思路做基本都能落地。如果你正在做类似OA与ERP对接又不想一上来就上CAS这种重型方案这篇文章可以帮你少走不少弯路。1. 为什么要做这个集成多系统登录的痛点1.1 企业信息化里的“账号迷宫”绝大多数上了OA和ERP的企业用户都是两套身份两套密码。泛微E9有自己的账号体系金蝶云星空也有自己的人员档案和用户编码。业务人员每天早晨打开电脑先登OA看待办再开金蝶做业务遇到金蝶密码过期还得找管理员重置一来一回半天时间就没了。这还不是最麻烦的。真正头疼的是安全审计员工离职后ERP账号忘了注销或者有人为了省事把密码写在便签纸上贴在显示器边上。这些在集团型企业里都是实打实的合规隐患。把泛微E9当作统一入口让用户在OA里完成认证后直接进入金蝶账号统一管控、密码统一策略审计风险小很多。另外一个容易被忽略的点泛微E9是全员每天必开的后台金蝶云星空则往往只有财务和供应链的人在重度使用。把金蝶的入口收编到OA门户里日常活跃度、点击率、业务协同效率都会明显提升。这也是很多客户做这个集成的直接驱动力。1.2 方案选型token中转为什么比直连数据库靠谱我见过一些集成案例为了省事直接在泛微里配一个金蝶数据库的只读账号通过查库来做个“假登录”。这个方案我极其不建议碰原因有三个一是数据库账号泄露风险太大二是金蝶的密码是加密存储第三方脚本去解密本身就是违规操作三是数据库结构变更一次你的集成脚本就废一次。主流做法其实是CAS或OAuth2统一认证中心但这套方案在企业里推广起来非常重需要维护独立的认证服务、改造两边的登录逻辑、处理来回回调实施周期往往按月起。我的选择是token中转方案泛微E9负责生成一个带签名和时间戳的临时token通过URL传递给金蝶金蝶侧用Python插件接收token再回调泛微的接口校验有效性校验通过后建立本地会话完成免登。这套链路不需要额外部署服务不碰数据库密码两边只暴露一个HTTP接口非常轻量。1.3 整体流程梳理整个登录流程用文字描述大概是这样的用户在泛微E9门户或工作流里点击“进入金蝶云星空”按钮泛微后端根据当前登录用户信息生成带签名token拼成金蝶的免登URL浏览器跳转到金蝶服务端金蝶的Python插件拿到token参数后向泛微的校验接口发请求确认token有效且没过期校验成功后插件内部完成用户身份映射和会话创建再跳转到金蝶首页。这里有个设计上的关键点就是金蝶侧校验token的请求必须设置超时时间一般3秒到5秒。如果泛微偶发响应慢金蝶不能一直挂起等结果要快速失败并引导用户走登录页避免用户卡在一个空白页干瞪眼。2. 前置准备两边系统需要先说好话2.1 版本与环境的硬性要求我实际测试下来泛微E9的版本至少要在9.0.0以上并且开通了集成中心的授权模块。很多客户的E9是标准版没有开通集成模块这种情况就要联系泛微现场服务人员开启相关接口权限或者让泛微提供restful API的调用通道。金蝶云星空这边建议V7.5及以上版本。老版本虽然也能通过BOS插件实现类似功能但新版对Python插件、WebAPI服务的支持更完善排查问题也方便。如果客户用的金蝶云星空是SaaS版本那Python插件方案就不适用了要改用开放平台的标准免登接口这个在4.1我会单独对比。网络层面泛微服务器和金蝶服务器之间必须能互相访问尤其是金蝶需要能主动发起HTTP请求到泛微的接口地址。两边服务器如果跨网段或者有防火墙策略第一时间把白名单和端口策略确认好否则联调的时候会浪费大量时间在“接口通不通”这种基础问题上。2.2 泛微E9端要准备什么泛微E9的集成中心里可以维护第三方系统信息。我们先把金蝶云星空登记为一个外部应用拿到应用标识appId和应用密钥secret后面生成token签名要用。同时要明确泛微对外提供的接口路径。有的现场习惯用/api/ec/dev/auth/checktoken做校验有的版本用/api/ec/dev/auth/applytoken获取token。我一般不纠结具体路径名称以现场实际接口文档为准只要两边约定一致就行。还有一个准备工作容易忽略在泛微组织架构里确认用户的登录名是否稳定。OA登录名一旦变了金蝶这边的用户映射就得跟着改所以尽量用OA账号的登录名作为身份标识不要用工号工号在很多企业里会复用。2.3 金蝶云星空端要准备什么金蝶云星空这边需要在BOS集成开发平台里建立一个Python插件工程。这一步是纯开发工作需要现场服务人员配合给出开发环境和部署权限。插件发布后会在金蝶应用服务器上生成一个HTTP服务地址这个地址就是泛微跳转时填写的目标URL。同时需要准备用户映射表。泛微登录名和金蝶用户编码往往不一致我的做法是维护一张数据库表或者配置文件字段就三个oa_user、kd_user、status。登录的时候插件先用泛微传来的用户名查这张表找到对应的金蝶用户编码再去建立会话。用户映射表建议在上线前就整理好别等联调的时候再逐个对。几十人的小公司还好几百人的集团一个一个对是很痛苦的。2.4 参数约定表下面这张表是我在项目里常用的参数约定直接拿来用可以省掉很多沟通成本。参数名来源用途token泛微E9生成身份凭证校验登录请求合法性uid泛微E9生成OA登录名用于映射金蝶账号ts泛微E9生成Unix时间戳用于防重放appId泛微E9生成三方应用标识kd_user金蝶插件映射金蝶云星空用户编码token的有效期我习惯设置300秒ts超过300秒直接拒绝避免一个链接被反复使用。实际项目中这个时间可以根据业务场景调但不要太长5分钟足够用户完成一次跳转登录了。3. 泛微E9端配置把token发出去3.1 集成第三方系统的入口配置在泛微E9后台控制台找到“集成中心”或“外部系统管理”新增一条记录系统名称写“金蝶云星空”标识建议写成kd_cloud便于后面识别。登记完会生成appId和secret这两个值不要存在前端页面上后续生成签名时才用到。部分客户现场泛微集成中心的菜单名称叫法不一样有的叫“应用中心”有的叫“第三方系统”。如果你找不到直接问泛微的实施顾问最快或者看系统帮助搜索“外部认证”。这里不要自己乱点万一改错全局配置影响OA登录就麻烦了。IP白名单建议一起配置上限制只有金蝶服务器的IP可以调用泛微的校验接口。这一步别偷懒token校验接口本身不复杂但如果任何人都能调用等于把整个认证入口暴露在了公网上。3.2 token生成与签名规则泛微生成的token本身无所谓关键是签名时要把时间戳、appId、secret串起来防止别人看了URL里的token就能伪造。比较常见的做法是MD5拼接字符串伪代码类似这样String raw appId timestamp secret; String token DigestUtils.md5Hex(raw).toUpperCase(); String url http://k3.example.com:8080/ssologin ?token token uid loginName ts timestamp;签名算法具体用MD5还是HmacSHA256每个泛微版本的支撑不太一样。我的建议是优先用HmacSHA256安全强度高一点如果泛微现场不支持再退回MD5方案毕竟token有效期就5分钟攻击窗口有限。secret只存在泛微后端永远不要出现在前端页面或者URL里。如果团队有安全评审要求可以定期轮换secret轮换时注意和金蝶侧同步否则会导致线上突然无法免登。3.3 工作流/门户入口的链接写法链接写在哪里很重要。最朴素的做法是给用户一个收藏夹但这跟没做差不多用户根本不会用。我一般建议在泛微E9的门户页面自定义导航里加一个“金蝶云星空”的菜单项或者在常用工作流表单上放一个“进入金蝶对应单据”的按钮。如果需要在工作流里做单点跳转泛微E9的表单或流程节点上可以挂自定义按钮按钮的URL里把token和用户信息带上。某些版本不支持在URL里直接用当前登录人的参数做替换这时就需要写一个前端脚本去后端取token再拼URL。这时候泛微的统一身份参数能不能自动替换是配置环节最容易卡住的地方。比较实用的做法是建一个独立的JSP或者泛微自带的集成页面在页面上写一段逻辑获取当前登录用户信息、生成token、再重定向到金蝶。这个页面本身不复杂但能把流程梳理得更清晰后续审计也方便。4. 金蝶云星空端Python插件把token接进来4.1 为什么选Python插件方案金蝶云星空有两个原生能力可以实现外部免登一个是开放平台的标准免登接口一个就是BOS平台的Python插件。开放平台方案适合SaaS租户或者对标准性要求高的场景但需要在开放平台注册应用、配置回调地址而且部分私有化部署的客户并没有开通开放平台模块。Python插件方案的优势在于它是BOS自带的扩展点大部分私有化部署的星空版本都能用不依赖外部服务整个逻辑我们自己在插件控制下写出了问题只用找一个开发排查。缺点是它只适用于私有化部署SaaS租户没有应用服务器权限没法部署插件那种情况只能走开放平台。实际项目中我一般先问客户一句话金蝶是你们自己部署的服务器还是用厂商云上的SaaS。如果是自己的服务器直接走Python插件方案如果连服务器都碰不到那就老老实实研究开放平台接口。4.2 WebApi插件核心代码金蝶BOS里的Python插件需要加载System.Web的运行时然后处理HTTP请求。下面是一段我在项目里用过的参考代码核心流程就是接收参数、调用泛微校验、建立会话# -*- coding: utf-8 -*- import urllib.request import json import time class SSOLogin: def AfterExecuteWebRequest(self, e): request e.Request response e.Response token request.QueryString.Get(token) uid request.QueryString.Get(uid) ts request.QueryString.Get(ts) if not token or not uid or not ts: self._output(response, -1, 参数不完整) return # 时间戳窗口校验防重放 if abs(int(time.time()) - int(ts)) 300: self._output(response, -2, token已过期) return # 调用泛微E9校验token verify_url (http://oa.example.com/api/ec/dev/auth/checktoken ?token%susername%s % (token, uid)) try: resp urllib.request.urlopen(verify_url, timeout5) result json.loads(resp.read().decode(utf-8)) except Exception as ex: self._output(response, -3, 调用OA接口失败: str(ex)) return if result.get(success) is True: # 建立金蝶会话此处按实际BOS接口调整 response.Cookies.Add(kd_sso_user, uid) response.Redirect(/K3Cloud/HTML/Index.html) else: response.Redirect(/K3Cloud/HTML/Login.html) def _output(self, response, code, message): response.ContentType application/json response.Write(json.dumps({code: code, message: message})) response.End()注意这段代码是参考框架不同版本的金蝶BOS对插件事件签名和会话处理的写法略有差异。你在开发机上先用BOS IDE建一个WebAPI插件把事件断点跑通再填业务逻辑能省很多调试时间。4.3 用户名映射与会话绑定金蝶云星空登录时要求的用户编码跟OA登录名几乎不可能天然一致。我在客户现场遇到最多的情况是OA里是拼音姓名金蝶里是员工编号两边对照只能靠人工核对Excel。我的做法是在插件里加一个映射查询函数优先查金蝶数据库里的映射表查到就直接返回金蝶用户编码查不到就记录一条日志并默认跳到登录页。这样至少保证映射缺失时不会导致服务崩溃也方便后续在日志里看到底哪些人还没配映射。会话绑定部分金蝶BOS提供了统一登录的API或者Cookie机制你可以直接把金蝶用户编码写到会话里。具体到版本用哪个方法以金蝶自带的开发文档为准。我最开始也试图找一套通用的会话注入代码后来发现不同版本差异确实大反而是在现场对着BOS的自带Demo抄一段更快。4.4 发布与调试插件代码写好后通过BOS IDE编译发布到应用服务器。发布后先不要急着做免登跳转直接在浏览器里访问金蝶的免登服务地址手动带上参数测试。这个步骤能快速区分问题是出在前端还是插件本身。我还习惯在插件里加一行日志输出来记录每次请求的来源IP、参数和校验结果。金蝶的日志目录在应用服务器的安装目录下调试时把日志级别调到Debug联调完再改回Info免得日志文件膨胀飞快。联调时如果一直报token校验失败优先检查泛微校验接口是不是要求带请求头。有的泛微版本除了URL参数还要求在Header里传appId或用户凭证插件里的urllib请求要把Header补全。5. 联调阶段最容易踩的坑5.1 token过期时间不同步这是我在好几个项目里都撞过的坑。泛微生成token时用的是服务器当前时间金蝶校验ts时用的是自己服务器的时间两边系统时钟只要偏差超过5分钟用户一点链接就被判“token已过期”。排查方法很简单把两个服务器的时间同步配好全部用NTP时间源。金蝶和泛微的服务器都要做尤其虚拟机环境特别容易出现时钟漂移。我当时排查了大半天最后发现是金蝶服务器所在虚拟机的时间慢了两小时差点怀疑是接口签名逻辑写错了。5.2 用户映射对不上联调时经常遇到的情况是泛微这边明明传了正确的uid金蝶插件也能调通校验接口但最后就是登录不上一看日志映射表里根本没有这个用户。原因是前期整理映射表的时候只覆盖了有业务系统权限的人漏掉了只做审批查询的读写用户。建议上线前做一次全量扫描把泛微所有在职用户的登录名导出来和金蝶用户表做一次关联比对把差异项提前处理好。宁可多配几个不常用的账号也不要漏掉关键业务部门的人。5.3 域名/IP引起Cookie失效金蝶登录成功后写入的Cookie绑定了域名如果OA跳转过来的地址是IP但金蝶首页访问用的是域名浏览器会认为跨域Cookie写不进去用户还是落在登录页上。我个人建议在泛微的跳转URL里直接用金蝶的域名不要写IP。如果客户现场没有内网DNS可以在泛微服务器和金蝶服务器各自的hosts文件里把域名映射配好保证两边访问同一个域名。5.4 权限和控制台日志金蝶BOS的WebAPI插件对匿名访问默认是受限的有时候前端跳转过来直接被拦截在登录页并不是token校验失败而是这个服务路径没有加到匿名访问白名单里。我在金蝶的管理控制台里找到相关配置把免登服务路径加进允许列表问题立刻解决。建议联调阶段把金蝶应用服务器和泛微应用服务器的访问日志、错误日志同时打开对照时间戳看请求链路。大多数情况下两边日志一对问题出在哪一步就非常清楚了。下面整理一张联调高频问题速查表方便现场排查用。问题可能原因排查方向点击链接跳到金蝶登录页token校验失败或用户映射缺失查看插件日志和泛微校验接口返回提示token已过期服务器时间不同步检查泛微与金蝶服务器时间偏差页面空白跳转地址配错或插件崩溃浏览器F12控制台看请求响应Cookie写不上域名/IP不一致统一使用同一域名访问插件服务无法匿名访问BOS控制台未放行服务路径在金蝶控制台配置匿名白名单6. 上线后的安全加固与后续扩展6.1 传输层安全单点登录跑起来了只是第一步安全加固至少要做三件事。第一泛微和金蝶之间的接口必须走HTTPStoken和用户信息明文走HTTP的话在内网还可以接受只要跨网段就必须上证书。第二泛微的校验接口要限制来源IP只允许金蝶服务器所在网段调用。第三token签名尽量用HmacSHA256虽然有效期短但能多一层防护就多一层。如果你的客户对信息安全有合规审计要求这三条基本是硬性项。不然审计发现ERP免登链路存在明文传输整改意见下来更麻烦。6.2 防重放与IP白名单防重放光靠时间戳窗口还不够稳妥。更严谨的做法是校验接口里记录一条请求缓存同一个token只能消费一次。泛微这边实现起来不难把已经校验过的token存到Redis或者数据库表里设置5分钟的过期时间每次校验前先查一下是否已被使用过。IP白名单一定要做在泛微侧不是做在金蝶侧。金蝶调用泛微校验接口时泛微要能识别来源IP并过滤。如果泛微的集成中心没有直接提供IP白名单配置可以写一个简单的过滤器在网关层处理成本很低。6.3 后续扩展与企业微信/钉钉联动单点登录基础链路稳定之后很多人会继续往下做移动端免登也就是泛微E9对接企业微信、金蝶云星空再对接企业微信的联动方案。这个链路的核心逻辑其实和PC端一模一样只不过身份来源从OA登录用户变成了企业微信的userId中间再铺一层账号映射就行。金蝶云星空对移动端的适配相对成熟只要服务器端注册好企业微信的可信域名用户在企业微信里打开金蝶应用走的还是同一个免登通道。做过一次PC端集成之后移动端扩展基本就是复制粘贴再改参数的事。我的经验是先把PC端SSO流程彻底跑稳把账号映射表维护规范移动端和后续其他系统接入就会顺畅很多。相反如果基础映射和数据维护都乱着接再多前端入口也只是把混乱放大。做这个集成的整个过程中我个人最深的体会是一句话单点登录的技术难点从来不在代码而在两边系统的账号数据规范。只要账号映射整理清楚接口联调半天就能通账号混乱光对需求就能对一周。所以如果你正准备开始做这个项目我的建议是先花时间把两边账号体系梳理干净再考虑写插件和配置URL。这套思路不仅仅是泛微和金蝶之间适用换成其他任意OA和ERP逻辑都是通的。