SAML单点登录插件

1.1 版本

1.2 功能

用户需要实现通过 SAML 认证登录数据决策系统，本文提供配置 SAML 单点登录插件方案。

用户可下载 SAML 单点登录插件，无需代码，简单快速地实现通过 SAML 认证登录数据决策系统的效果。

注：远程设计时不走 SAML 认证，默认放行。

2.1 插件下载

请点击链接获取插件试用安装包：点击下载

设计器插件安装方法请参见：设计器插件管理

服务器安装插件方法请参见：服务器插件管理

2.2 界面介绍

安装插件后无需重启，超管进入平台，点击「管理系统>系统管理」，新增「SAML-SP配置」页面。

注：需注意以下几点：

• 用户需要有「管理系统」权限，才可见配置页面。

• 支持热部署，安装启用插件无需重启工程。

• 修改配置无需重启工程。

3.1 开启SAML单点登录

点击「开启SAML单点登录」按钮，如下图所示：

3.2 SAML配置

填写设置项后，需点击「保存」按钮，如下图所示：

注：未填写完配置会导致保存失败，如下图所示：

各设置项介绍如下表所示：

注：只配置 SAML 登录，未配置 SAML 登出时：

未开启「平台登录页」：点击右上角的「退出」按钮，浏览器刷新下页面，不会登出。

开启「平台登录页」：点击右上角的「退出」按钮，强制跳转到平台默认登录页，但是实际上没有登出平台，直接访问 http://ip:端口/工程名/decision，还是显示之前用户的登录状态。

3.3 关闭SAML单点

超管进入平台，点击「管理系统>系统管理>SAML-SP 配置」，关闭「开启SAML单点登录」按钮，点击「保存」，如下图所示：

注：如果需要执行从 Azure AD 发起的单一登录（例如从 Azure AD 的 My apps 单点到 FineReport 服务器），须首先配置 FineReport 工程为 HTTPS 访问。配置HTTPS 访问可参考：配置HTTPS 。

4.1 填写SAML基础设置

1）填写标识符(实体标识符)

此项自定义即可，例如本文示例此处填了工作人员姓名 jade。

2）填写回复 URL(判断断言消费者服务 URL)

此项需要填写 FineReport 工程的访问路径（结尾到 decision）/sso/saml/acs，例如：https://localhost:8080/webroot/decision/sso/saml/acs

3）填写登录 URL

此项是 Azure AD 内的必填项，用于执行从 Azure AD 发起的单一登录。若需要执行从 Azure AD 发起到 FineReport 服务器的的单一登录（例如从 Azure 

AD 的 My apps 单点到 FineReport 服务器），则需要先配置 FineReport 工程为 HTTPS 访问，配置 HTTPS 访问可参考：配置HTTPS 。

若已配置平台为 HTTPS 访问，则此处直接填写 FineReport 工程的访问路径即可，例如：https://localhost:8080/webroot/decision 。

若无此场景需求，可以填写任意 HTTPS 的链接。

4）填写完必填项后，点击「保存」按钮。

4.2 在FineReport中完善配置项

4.3 效果查看

访问原报表链接 https://localhost:8443/webroot/decision，会进行 SAML 单点登录。

点击退出登录当前用户，会返回到 https://localhost:8443/webroot/decision/login。如下图所示：

5.1 ADFS设置

1）打开 ADFS, 选择「Start> Administrative Tools > ADFS Management」，跳转至「Relying Party Trusts」文件夹。

2）选择「Action > Add Relying Party Trust」。

3）选择「Start」来运行「Add Relying Party Trust Wizard」。

4）打开「Select Data Source」窗口，选择 「Import data about the relying party from a file」, 选择从插件配置页上传的 metadata.xml 文件并点击「Next」。

5）选择「Next」，跳过「Configure Multi-factor Authentication Now?」询问窗口。

6）打开「Choose Issuance Authorization Rules」窗口, 选择 「Permit all users to access this replying party」 并点击 「Next」。

7）在 「Ready to Add Trust」 窗口：

点击「Encryption」, 从 FineBI 服务器上传「SP Certificate」（SP 公钥证书）； 点击「Advanced」, 设置为「SHA-1」。

8）打开「Ready to Add Trust」窗口, 点击「Next」。

9）打开「Finish」 窗口, 点击「Open the Edit Claim Rules dialog for this replying party trust when the wizard closes」 并点击「Close」。

如果在关闭向导时没有弹出「Edit Claim Rules」对话框, 右键选择用户设定的 The Relying Party Trust 名称，并选择「Edit Claim Rules...」。

10）打开 「Edit Claim Rules」对话框, 选择「Add Rule」。

11）打开「Select Rule Template」 对话框, 在「Choose Rule Type」下拉列选择「Send LDAP Attributes as Claims」并点击「Next」。

12）填写「the Configure Rule」对话框:

• 在「Claim rule name」栏输入「UseridentiferToNameID 」(可自定义)。

• 在 「Attribute store」栏选择 「Active Directory」。

• 在 「LDAP Attribute」栏选择「SAM-Account-Name」 (或账号的任意属性)。

• 在「Outgoing Claim Type」栏输入「Name ID」。

注：账号映射字段应设置为相同的值。在一些 ADFS 版本中，允许使用自定义值而不限定于名称 ID，此处的设定应为与插件设置中的账号映射相同。

13）点击「Finish」。

5.2 常见问题及解决方案

注：V1.0.2 版本新增调试功能，无需调试时请保持按钮关闭。如遇问题可联系技术支持协助使用调试功能进行排查。

ADFS 的正确 XML 响应将包含 Name 属性，正确格式如下：

...... 
<AttributeStatement> 
<Attribute Name="Name ID"> 
<AttributeValue>username@fanruan.com</AttributeValue> 
</Attribute> 
</AttributeStatement> 
......

5.2.1 在文件中找不到名称ID

./logs/fanruan.log
~ https-openssl-nio-443-exec-16 ERROR [standard] No name id found in Document.
~ com.onelogin.saml2.exception.ValidationError: No name id found in Document.

可能的原因：

1. 未配置「Outgoing Claim Mapping」。

2. 在一些 ADFS 版本中, 「Outgoing Claim Mapping」必须包含「Name ID」。

5.2.2 XML中未返回名称字段

「Name」字段（属性名称）未出现在 ADFS 返回的 XML 中。

./logs/fanruan.log
~ http-nio-37799-exec-35 ERROR [standard] null
~ java.lang.NullPointerException: null

可能的原因：

1）SP SSL 证书未上传至 ADFS。

2）ADFS 加密类型未设置为「SHA-1」。

5.2.3 找不到匹配的账号

ADFS 返回的 XML 中存在「Name」字段（属性名称），但登录应用程序无法识别。

./logs/fanruan.log
~http-nio-37799-exec-12 ERROR [standard] No matching user name found!

可能的原因：

SAML 插件中的「Username Mapping」与「Outgoing Claim Type」设定的值不同。

5.2.4 账号不存在或密码错误

ADFS 返回的 XML 中存在「Name」字段（属性名称），但登录不成功。

./logs/fanruan.log
~http-nio-37799-exec-23 WARN [standard]
com.fr.decision.webservice.exception.login.UserLoginException : User not exist, or wrong password!

可能的原因：

ADFS 中设置为「Outgoing Claim Type」的字段不是 FineReport 中的「username」字段。

5.2.5 登出认证服务器后决策平台未登出

问题现象：用户登出了认证服务器，但决策平台未同步登出。

解决方案：升级插件至 1.0.8 及以上的版本。