如果你们公司也在做 Oracle Hyperion 的单点登录SSO改造你会发现这套系统和普通 Web 应用的 SSO 完全不是一个难度等级。Hyperion 不是一个单点应用它是一整套组件Shared Services、EPM Workspace、Planning、Essbase、HFM每个模块都有自己的会话逻辑SSO 要做的是在这些层之间建立一条统一的身份通道任何一个环节配合不好后面的排查就是无底洞。这篇文章记录的是我在一个 Hyperion 11.1.2.4 项目里做 SSO 集成时实打实踩过的坑覆盖从 WebLogic 到 OAM、从 Shared Services 到业务模块的完整认证链路适合正在做或准备做 Hyperion 单点登录的运维、中间件和 EPM 管理员参考。1. 先摸清Hyperion的认证链路不搞懂这张网络后面全是玄学1.1 Hyperion组件多SSO链路环环相扣很多朋友一上来就问我Hyperion SSO 怎么开实际上这个问题没法直接回答。你要先知道一个 Hyperion 用户的完整请求路径长什么样浏览器 → 前置 OHS/WebGate → OAM 认证服务器 → OHS → WebLogic → EPM Workspace/Planning → Shared ServicesHSS → 各业务服务。这里面每一跳都可能断。更麻烦的是Hyperion 的 SSO 其实有两层认证第一层是 Web 容器层认证也就是 WebLogic 通过 Identity Asserter 识别 OAM 传过来的用户身份第二层是 EPM 应用层认证Workspace 拿到用户身份后还要带着自己的 SSO 令牌去 Shared Services 校验一次。这两个层次只要有一层没打通表现都是登录不进去或者登录进去没有权限但根因可能完全不同。我把这次踩到的问题归纳成了四类认证器配置问题、令牌与目录映射问题、会话超时问题、重定向与编码问题。每类问题都对应一个真实故障而且都有完整的排查链路。如果你能把这四种情况吃透以后再做 Hyperion SSO 至少不会抓瞎。1.2 本次集成的技术选型与关键参数我们的环境选型是基于企业现有的 Oracle 身份体系来定的具体参数如下组件版本角色说明Oracle Hyperion11.1.2.4EPM System 整体套件WebLogic Server10.3.6EPMSystem 域承载 Workspace/Planning/HSSOracle Access Manager11g R2 PS3统一认证中心负责账号密码校验Oracle HTTP Server11.1.1.9前置反向代理安装 OAM WebGateActive Directory2012 R2用户源存放所有域账号对外访问域名epm.example.com浏览器访问的 FQDN内部用短主机名选 OAM 的原因很简单企业里已经有完整的 Oracle Identity 体系而且审计要求所有应用接入统一认证。如果你没有 OAM也可以走WebLogic 自带 LDAP 认证 自定义 Filter的轻量方案但本文涉及的问题以 OAM 方案为主线因为这套方案最典型坑也最多。另外我要提前说一句所有组件的主机名、对外域名、IP 解析、系统时钟在开始之前一定要全部确认一致。我见过太多 SSO 问题最后查出来是 DNS 解析到不同 IP、或者服务器时间差了五分钟这种情况你怎么查配置都查不出结果。2. 坑一加了LDAP认证器之后内置admin反而登不进去了2.1 故障现象与影响面这个坑发生在我们把 WebLogic 安全域里的认证器从默认的 DefaultAuthenticator 切换到 AD 认证器之后。改完之后EPM 前端所有用户都登不进去包括安装 Hyperion 时创建的本地管理账号 admin以及 WebLogic 控制台的 weblogic 用户。影响面有多大EPM Workspace、Planning、Shared Services 这些前端全部无法登录管理控制台也进不去整个环境处于瘫痪但不宕机的诡异状态进程都在服务都是 RUNNING但没有任何人能进去操作。这里我想提醒一下Hyperion 安装时候创建的那些管理账号默认是存放在 WebLogic 文件领域embedded LDAP里的不在 AD 里。你如果贸然把认证源切到 AD却没有保留文件领域这些本地用户就全部失效了包括管理员自己。2.2 顺着日志重建认证调用链我当时第一步是去看 WebLogic 日志路径在EPMSystem_domain/servers/AdminServer/logs/AdminServer.log里面出现了大量类似这样的记录critical WebLogicServer BEA-000362 Authentication failed for user admin javax.naming.AuthenticationException: [LDAP: error code 49] - Invalid Credentials看到 error code 49第一反应是用户本身在 AD 里不存在。于是我用 ldapsearch 去验证ldapsearch -x -h ldap.example.com \ -D cnssobinduser,ouServiceAccounts,dcexample,dccom \ -w 密码 \ -b dcexample,dccom \ (sAMAccountNameadmin) distinguishedName结果这台 AD 里确实没有名为 admin 的用户只有 HR 部门的zhangsan、lisi这些域账号。这就说明问题不在 AD 连接而在于 WebLogic 认证链的配置逻辑我们让所有用户都只能走 AD 验证本地文件领域已经被踢出去了。2.3 根因认证器的 Control Flag 与执行顺序WebLogic 的 AuthenticationProvider 有四种 Control Flag理解这四种标志是做 SSO 的基本功Control Flag行为说明REQUIRED一定会执行且必须认证成功否则直接拒绝REQUISITE一定会执行失败则立即拒绝不再尝试后续 ProviderSUFFICIENT可以执行只要有一个 SUFFICIENT 成功且未被 REQUIRED/REQUISITE 覆盖则认证通过OPTIONAL执行但结果不影响整体认证除非没有其它 Provider 成功我们当时的配置是新加的 AD 认证器设为 REQUIRED 并放在第一位DefaultAuthenticator 被直接移除了。结果就是 WebLogic 认为所有用户都必须通过 AD 验证而 AD 里当然没有本地文件用户 admin 和 weblogic所以全部失败。正确的做法其实是让两者共存DefaultAuthenticator 保留并设为 SUFFICIENTAD 认证器也设为 SUFFICIENT顺序上先本地后 AD。这样本地文件用户还能继续使用AD 用户则会在本地验证失败之后继续尝试下一个 Provider 并成功认证。2.4 修复过程与配置细节修复我建议优先用 WLST 脚本而不是手点控制台因为控制台改 Provider 顺序很容易点错。脚本核心逻辑如下connect(weblogic,密码,t3://wls-host:7001) edit() startEdit() cd(/SecurityConfiguration/epmsystem/Realms/epmsystem/AuthenticationProviders) cmo.createAuthenticationProvider(DefaultAuthenticator, weblogic.security.providers.authentication.DefaultAuthenticator) cmo.createAuthenticationProvider(ADAuthenticator, weblogic.security.providers.authentication.LDAPAuthenticator) cd(DefaultAuthenticator) cmo.setControlFlag(SUFFICIENT) cd(ADAuthenticator) cmo.setControlFlag(SUFFICIENT) cmo.setAttribute(GroupBaseDN, ouGroups,dcexample,dccom) cmo.setAttribute(UserBaseDN, ouPeople,dcexample,dccom) cmo.setAttribute(UserFromNameFilter, ((sAMAccountName%u)(objectclassuser))) cmo.setAttribute(UserObjectClass, user) cmo.setAttribute(UserNameAttribute, sAMAccountName) cmo.setAttribute(Principal, cnssobinduser,ouServiceAccounts,dcexample,dccom) cmo.setAttribute(Credential, 密码) cmo.setAttribute(Host, ldap.example.com) cmo.setAttribute(Port, 389) cd(/SecurityConfiguration/epmsystem/Realms/epmsystem) cmo.setAuthenticationProviders([DefaultAuthenticator,ADAuthenticator]) save() activate()修改完成后重启 AdminServer 和所有 ManagedServer再验证两个场景本地 admin 能登录 WebLogic 控制台AD 里的域账号能登录 WebLogic 控制台。两个都通了再继续做下一步的 EPM SSO 配置。提示如果环境里同时存在多台 WebLogic 节点一定要用一个可复用的 WLST 脚本来统一配置不要在每台机器上手动点否则很容易出现某台节点配置不一致导致后续 SSO 随机失败。3. 坑二OAM令牌验证通过EPM工作台却提示无权限3.1 故障现象令牌有了权限没了WebLogic 认证器修好之后OAM 层面的 SSO 也基本通了。但新问题马上出现用户访问https://epm.example.com/workspace/被 OAM 重定向到统一登录页输入域账号密码后浏览器里已经有了 OAM 的会话 Cookie也能看到地址栏跳回了 Workspace但页面上很快又弹回登录页或者是直接提示 You are not authorized to view this page。这个现象非常典型OAM 认证是成功的但 Workspace 向 Shared Services 提交 SSO 令牌时失败了。因为 Workspace 和 HSS 之间的令牌校验是 Hyperion 自己的机制它不认识 OAM 的登录状态需要额外配置共享密钥和主机标识。3.2 在HSS日志里找到第一现场这种问题不能只看 WebLogic 日志真正的第一现场在 HSSShared Services日志里。路径在EPM_HOME/logs/Foundation/HSS/hss.log和hss_diagnostic.log。我当时在 hss.log 里看到的典型报错是[SEVERE] SSO Token validation failed. shared secret verification mismatch. User not found in external user directory: zhangsan这一条日志同时给了两个线索一是令牌校验失败二是外部目录里找不到用户。所以这个问题要分两层拆。3.3 根因拆解共享密钥、主机标识与用户目录映射第一个根因是共享密钥不一致。Hyperion 的 SSO 令牌在 Workspace 和 HSS 之间是用了对称密钥签名的这个密钥在 Shared Services 控制台的单点登录配置里维护叫 Shared Secret。如果环境里有多个节点或者配置是从别处恢复过来的不同节点的 Shared Secret 不一致就会导致 A 节点签发的令牌 B 节点解不开。第二个根因是外部目录映射缺失。OAM 认证通过后WebLogic 断言的用户名会传给 WorkspaceWorkspace 再去 HSS 里查找这个用户有没有 EPM 角色。但如果 HSS 的外部用户目录还没有启用或者没有把 AD 用户绑定到对应的 EPM 角色上HSS 就会认为这是一个存在但无权的用户最终表现为登录后无权限。第三个根因是用户名格式不匹配。AD 里用户登录名是zhangsan但 WebLogic 断言出来的可能是zhangsanexample.com或EXAMPLE\zhangsan而 HSS 配置的用户目录属性是sAMAccountName两边对不上自然找不到。3.4 修复过程与验证方法修复分三步走第一步重新生成并同步 Shared Secret。在 Shared Services 控制台的配置 → 单点登录里重新保存一次让 HSS 重新生成/加载密钥。如果有多节点保证每个节点的配置文件里保存的密钥一致。保存后必须重启 Foundation Services。第二步配置外部用户目录映射。在 Shared Services 控制台里把外部用户目录AD启用并确保 AD 里域用户归属于正确的组再把对应的组映射到 EPM 的内置角色上比如Administrator、Planning Administrator。这一步很关键很多人只配了用户目录没配组映射导致普通用户能进去但看不到菜单。第三步调整 Principal Name 格式。在 WebLogic 安全域里配置 Principal Name Mapper让 OAM 断言出来的用户名与 HSS 期待的属性一致。我们最终把OAMIdentityAsserter的 User Name Attribute 配成了OAM_REMOTE_USER并且在 WebLogic 里映射用户名时强制转换成sAMAccountName格式。验证方法也简单登录后看 Workspace 右上角显示的用户名如果是未命名用户或者空白基本可以断定是用户目录映射没配对如果能看到具体的中文姓名说明用户映射通了。然后再访问一个需要权限的功能点做二次确认。4. 坑三模块之间会话超时不一致用户做审批做着做着就被踢下线4.1 超时问题的几种表现第三个坑看似比前两个简单但在生产环境里危害一点都不小。现象是用户用 SSO 登录后EPM Workspace 一直开着没问题但点开 Planning 模块操作到一半提示会话过期另一个场景是审批人在审批页停留太久点提交时被要求重新登录还有一个人反馈说明明浏览器里 OAM 的 Cookie 还在但 WebLogic 端却告诉他登录状态失效。这些现象综合在一起说明系统里不是只有一个超时而是多个组件各自维护各自的会话超时它们之间没有一个统一的会话生命周期。4.2 三层超时的配置位置我整理了一下Hyperion SSO 环境里至少存在四层超时层次配置位置说明OAM 全局会话OAM 控制台 → Authentication → AuthN Policy控制 OAM 自身的会话有效期默认 60 分钟WebLogic HTTP Sessionweblogic.xml或应用的web.xml每个应用的 session-timeout 可能不同EPM 业务应用Planning/Reporting 的会话配置、工作流引擎审批流、表单保存有自己的超时机制AD 域令牌组策略里的 Kerberos 票据生命周期走 SPNEGO/Kerberos 时才会受影响在我们的环境里Workspace 的 session-timeout 被设成了 120 分钟Planning 的 web.xml 还是默认的 30 分钟OAM 那边则按安全要求设了 60 分钟。用户如果长时间停留在 Workspace 再点进 PlanningPlanning 的会话已经失效了但页面不会主动跳转直到提交时才报错。4.3 让超时行为一致的落地配置我的建议是把这些超时统一到一个经过安全、业务都能接受的数值。当时我们统一成了 120 分钟理由是内部系统使用时长普遍较长并且有操作审计兜底。WebLogic 应用层的配置可以直接在weblogic.xml里指定session-descriptor session-timeout120/session-timeout persistent-store-typereplicated_if_clustered/persistent-store-type /session-descriptorOAM 的控制台里找到对应的认证策略把 Session Timeout 从 60 改成 120同时把会话空闲超时也统一避免空闲 10 分钟就掉线。这一步还要注意如果你们用的是 WebLogic 集群多节点必须确认负载均衡上开启了基于 Cookie 的粘性会话或者配置了集群 Session 复制。否则用户第一次请求打到节点 A第二次请求漂到节点 B节点 B 没有用户的 Session哪怕 SSO 令牌还有效应用也会认为用户未登录。这个问题我见过很多次结果都是SSO 有问题实际是负载均衡没配好。5. 坑四重定向地址异常与中文乱码多级代理下的小问题大麻烦5.1 现象重定向回内网IP与混合内容报错这个坑是上面三个都修好之后才暴露出来的也是多级代理环境里最容易忽视的问题。登录流程本身已经通了但用户登录成功后浏览器地址栏里的 URL 从https://epm.example.com/workspace/变成了http://10.0.0.5:19000/workspace/。紧接着浏览器就开始报警混合内容登录状态直接丢失。还有一种表现是 URL 里的中文资源和产品名全部变成%E6%B5%8B%E8%AF%95这种编码串部分前端脚本解析不了点菜单直接 404。这些问题的共同点是请求经过了多次代理转发但每一层对原始请求的主机名、协议、编码处理不一致。浏览器认的是外部域名后端却按内部 IP 在生成重定向地址自然就串了。5.2 根因主机标识、代理头与Cookie Domain根因可以拆成三点。第一点EPM 内部注册的主机标识不对。我们在安装 Hyperion 时填写的 AdminServer 地址是10.0.0.5:19000这种内网地址这导致 HSS 和 Workspace 在生成重定向 URL 时会优先使用这个内部地址。解决方法是把 EPM System Registry 里的主机标识统一改成 FQDN也就是epm.example.com保证所有重定向都基于对外域名生成。第二点OHS 反向代理没有把原始 Host 头传递给后端 WebLogic。OHS 默认会用自身的 ServerName 来构造 Location 头如果前面还有 F5 或 nginx这个链路会更长。修改 OHS 的httpd.confServerName epm.example.com ProxyPreserveHost On IfModule mod_weblogic.c WebLogicHost wls-node1.example.com WebLogicPort 7001 WLProxySSL ON WLProxySSLPassThrough ON /IfModule Location /workspace SetHandler weblogic-handler /Location如果代理链路上还有 F5/nginx必须让每一层都传递Host和X-Forwarded-Proto否则后端的 WebLogic 永远以为自己是 HTTP 内网访问。第三点Cookie Domain 配置不对。OAM 或 WebLogic 下发的 SSO Cookie 如果Domain被写成10.0.0.5那么浏览器在访问epm.example.com时根本不会携带这个 Cookie会话自然建立不起来。需要把 Cookie Domain 统一成.example.com同时 HTTPS 环境下 Cookie 要带Secure标志。5.3 处理中文乱码与编码一致性关于中文乱码其实是 JVM 编码和应用容器编码不一致导致的。EPM 必须统一使用 UTF-8否则中文菜单、中文工作空间名在转发过程中会变成乱码。在 WebLogic 的启动脚本setDomainEnv.sh里加上JAVA_OPTIONS${JAVA_OPTIONS} -Dfile.encodingUTF-8 export JAVA_OPTIONSOHS 的httpd.conf里也要确认AddDefaultCharset UTF-8另外如果 EPM 数据库连接串里有characterEncoding参数统一设为 UTF-8。这些配置看起来不起眼但缺一个就可能在某个页面上暴雷而且暴雷的位置跟你配置的位置八竿子打不着极难排查。提示操作任何 JVM 编码参数前先备份原有启动脚本并在一台测试节点上验证确认没有引入新的兼容问题后再批量同步到所有节点。6. SSO问题的通用排查路径与快速回退方案6.1 SSO排查日志地图很多朋友遇到 SSO 问题就蒙圈其实只要知道该看哪份日志定位速度能快十倍。这是我整理的一份日志地图组件日志路径关注关键字OAM$OAM_DOMAIN/servers/oam_server1/logs/oam_server1-diagnostic.logAuthentication failed、Session Timeout、User not foundOHS/WebGate$OHS_HOME/logs/access_log、webgate.log401/403、OAM_REMOTE_USER、Host headerWebLogic$WLS_DOMAIN/servers/*/logs/AdminServer.logBEA-000362、AuthenticationException、Identity assertedShared Services$EPM_HOME/logs/Foundation/HSS/hss.log、hss_diagnostic.logSSO Token、shared secret、external directoryEPM Workspace$EPM_HOME/logs/Foundation/workspace.logLogin failure、Principal not found排查顺序永远是从外到内先看浏览器端的网络请求和 Cookie再看 OHS/OAM然后看 WebLogic最后看 HSS。跳跃式排查大概率会绕远路。6.2 一套可以执行的验证清单这里给你一份可以直接抄的验证清单每次做完配置修改后按顺序执行能挡住大部分问题用nslookup epm.example.com确认域名解析指向正确所有服务器能互相解析到 FQDN。检查所有服务器时间是否同步ntpq -p时间偏差超过 5 分钟就要先处理。用 ldapsearch 验证 AD 连接和用户条目确保服务账号能正常 bind。从浏览器 F12 的 Network 面板确认登录重定向链路里Location头始终是https://epm.example.com/...而不是内网 IP。用 curl 模拟一次完整跳转curl -I -L -k https://epm.example.com/workspace/观察每一跳的返回状态和 Location 头。登录后检查浏览器 Cookie确认 SSO Cookie 的 Domain、Secure、Path 都正确。登录后看 HSS 日志确认令牌校验成功且用户能映射到正确的 EPM 角色。6.3 回退方案从SSO安全回到本地认证最后讲一个我希望你永远用不上、但必须准备好的操作SSO 快速回退。生产环境里SSO 出问题经常是紧急状态不可能给你半天时间慢慢排查。我的回退方案分三步第一步在 Shared Services 控制台把单点登录开关改成禁用保存后重启 Foundation Services。这样 Workspace 会回到本地登录页用户可以用 EPM 本地账号登录。第二步在 OAM 控制台删除对 EPM 应用 URL 的保护策略或者把 OAM WebGate 临时从 OHS 里摘除注释掉相关配置让请求不再被重定向到 OAM。第三步恢复 WebLogic 认证器到本地 AD 共存的状态也就是坑一里我们最终采用的配置。这样即使不用 OAMAD 用户仍然可以通过 WebLogic 直接登录。回退完成后最好做一轮回归验证本地 admin 是否能登录、AD 用户是否能登录、所有 EPM 模块是否能正常访问。回退成功之后再去研究 SSO 本身的问题心态会完全不一样。重启顺序也要注意回退后按照这个顺序启动数据库 → Foundation Services → 各应用服务Workspace/Planning → OHS/WebGate。不要跳步也不要开着 OHS 等 WebLogic那样前端会报 503容易误判问题。最后说点实在的这套 SSO 做下来我最大的感受是SSO 方案本身不难难的是让所有组件在同一套身份语义下工作。OAM 有 OAM 的用户名格式WebLogic 有 WebLogic 的 Principal 映射HSS 有自己的用户目录和角色映射三层之间任何一层对用户名的理解不一样最终效果都会是登录失败或无权限。开始配置之前建议先画一张身份传递图把用户从输入密码到打开报表整个链路里每个组件怎么取用户名、怎么校验令牌写清楚再动手改配置。这样出了问题你能直接从图上定位断点在哪个环节而不是靠猜。另外一个小技巧是每一次修改只改一个组件改完立刻验证验证通过再动下一个。多人协作时更要把配置文件纳入版本管理否则回退的时候根本不知道改过什么。这次项目中我们就是因为一开始图快同时改了 OAM 和 WebLogic导致故障发生时完全无法判断是谁引起的。后面老老实实一步一步来反而省了大量时间。
