单点登录（SSO）几乎是每个帆软项目上线前的“必答题”。用户在企业门户或统一认证中心登录一次，访问 FineReport / FineBI 决策平台时无需再次输入账号密码，同时账号、组织和权限与企业现有体系保持一致。
这篇文章结合我们在集成类二开中的经验，梳理常见方案的差异、实施步骤和最容易踩的坑。
常见方案对比
| 方案 | 适用场景 | 关注点 |
|---|---|---|
| CAS | 高校、政企已有 CAS 统一认证中心 | CAS 协议版本、票据校验地址、属性返回格式、统一登出 |
| OAuth2 / OIDC | 自建或商用 IAM、云身份平台、企业微信 / 钉钉 / 飞书扫码登录 | 授权码流程、回调地址白名单、用户信息接口字段、令牌有效期 |
| LDAP / AD | 企业以 AD 域账号为主 | 严格来说是“统一账号密码”而非免登；可与其他 SSO 组合使用 |
| SAML 2.0 | 集团或外企标准身份联合 | 元数据交换、证书签名、断言属性映射 |
| Token / 接口登录 | 业务系统内嵌帆软报表，由后端签发令牌 | 签名算法、防重放、时钟同步、令牌泄露风险控制 |
选型的第一原则：跟随企业现有认证中心，而不是为帆软单独引入新的认证体系。
实施步骤
- 确认认证中心与协议：拿到协议版本、测试环境地址、测试账号与对接文档。
- 确定用户标识映射：认证中心返回的是登录名、工号还是手机号？与帆软用户名如何对应？这是最容易被忽略、也最容易出问题的环节。
- 设计用户与组织同步：帆软决策平台支持多种用户来源，常见做法是通过同步数据集或 LDAP 从已有系统同步用户与组织；映射规则复杂时通过插件实现定时增量同步。
- 开发 / 配置认证插件：基于决策平台开放的扩展点开发认证插件，处理登录、会话建立与跳转。
- 处理登出与会话：统一登出、会话超时、多标签页一致性。
- 联调与验收：覆盖正常登录、账号不存在、无权限、令牌过期、网络异常等场景。
避坑清单
- 反向代理与回调地址：经过 Nginx / 网关后，回调地址中的协议、域名、端口需与认证中心登记一致，注意正确传递
X-Forwarded-*请求头。 - HTTPS 与证书：服务端调用认证中心接口时的证书信任问题，内网自签证书尤其常见。
- iframe 嵌入与 Cookie：帆软报表被嵌入到不同域名的门户时，现代浏览器的
SameSiteCookie 策略可能导致会话丢失，需要从部署域名或 Cookie 属性上统一规划。 - 用户名规范：大小写、前后空格、全角字符不一致，会导致“登录成功但找不到用户”。
- 时钟同步：令牌类方案依赖时间戳，服务器之间时间偏差会造成间歇性登录失败。
- 保留管理员通道：认证中心故障时，需要一个受控的管理员登录入口用于应急处理。
- 移动端：移动 BI、企业 App 容器内的登录跳转行为与 PC 端不同，需要单独适配和测试。
我们如何交付单点登录项目
新软逐鹿按标准化服务流程交付帆软单点登录项目：方案评估阶段明确协议与映射规则，开发阶段在测试环境阶段演示，验收后交付插件、完整源码与部署文档，并提供 7×24 小时线上陪同支撑。开发的通用 SSO 插件可二次转售，适合需要在多个客户项目中复用的帆软合作伙伴。