SAML Single Sign-on Plugin

Version

Functions

Users need to implement SAML authentication to log in the Decision-making Platform. This chapter provides the configuration settings for SAML single sign-on plugin.

Users can download the SAML single sign-on plugin to easily log into the Decision-making Platform through SAML authentication without code.

Note:

Remote design defaults to log in the platform without SAML authentication.

Downloading the Plugin

You can obtain the plugin at https://community.finereport.com/plugin/?id=83.

For details about plugin installation methods in the designer, see Designer Plugin Management.

For details about plugin installation methods in the server, see Server Plugin Management.

Introducing the Configuration Page

After installing the plugin, you do not need to restart the designer. Admins can enter the platform and click Manage > System > SAML-SP Settings for configuration.

Note:

1. You need to obtain permissions of System before entering the configuration page.

2. The system supports hot swap, so you do not need to restart the project after installing and enabling the plugin.

3. You do not need to restart the project when modifying the configuration settings.

Enabling SAML Single Sign-on

Click Enable SAML SSO.

Configuring the SAML-SP Settings

After configuration, click Save.

Note:

Failure to complete the configuration will result in storage failure.

For details, see the table below:

Setting Items	Introduction	Required or Not
Enable SAML SSO	Click to enable SAML single sign-on function. After enabling, the filter interceptor will be loaded. When you access the original URL of decision-making platform, the platform will log in according to the SAML single sign-on logic. Note: Do not need to restart the project.	/
Enable debug mode	Click to enable debug mode. After enabling, the assertion information collected during the SAML SSO process will be printed in the error level log of fanrun.log. Note: You are not advised to enable it by default. The funtion is only used for debugging and when it is enabled, it will export the assertion information that may includes account, email and so on.
IDP Metadata	Provided by the identity authentication tool. It is generally the address of the page that returns data in XML format.	Yes
IDP Unique ID	Enter the IDP Unique ID provided by the identity authentication tool. Look up the entityID keyword from IDP Metadata, and the link behind it is the unique ID of IDP.	Yes
IDP SSO address	Fill in the address of the IDP that the filter needs to jump. And you need to obtain different IDP programs according to different situations	Yes
IDP Public Key	The public key used for encrypting when the IDP sends the assertion. It is generally obtained by searching the keyword ds:X509Certificate in the IDP Metadata, and the substring behind is the public key..	Yes
Username Mapping	This is an auxiliary function and is not required. You can use other attribute fields associated with IDP users for single sign-on. When the nameid field returned by IDP by default or is empty, you can configure it to other fields such as: username,email, etc.	No
SP Unique ID	Fill in the identity of the service provider and custom values.	Yes
SP URL	The access path of the FineReport project, which ends with {directory1}/{directory2}/{directory3}/decision For example: https://localhost:8443/webroot/decision	Yes
SP Certificate	Upload the certificate used by the service provider in CRT, CER, or PEM formats.  Note: The certificate is used only for encryption. You can generate the certificate by yourself or obtain it from the certificate service provider. You can also use the default certificate cert.zip.	Yes
SP Private Key	Upload the key file in KEY format. Note: If SP Certificate is set to the default certificate provided in the document, SP Private Key need to be set to the corresponding key in rsa_private.zip.	Yes
Generate metadata xml file	Click to download the MetaData.xml file provided by the service provider. Importing MetaData.xml file into the indentity authentication service can automatically generate a new SAML entity. If the five attributes related to the SP (IDP public key, SP unique ID, SP URL, SP certificate, SP private key) have empty valeus. It will prompt: {} has an unfilled value, please finish it before saving!	Yes
Enable SAML Single Sign-out	Choose whether to enable SAML single sign-out function. When enabling, the SAML single sign-out URL configuration item will be displayed.	No
SAML Single Sign-out Address	Fill in the interface of IDP for sign-out, and realize exiting FineReport at the same time. For example: http://localhost:8080/auth/realms/FineReport/protocol/openid-connect/logout?redirect_uri=http://localhost:8075/webroot/decision/login Parameter description: http://localhost:8080/auth/realms/FineReport/protocol/openid-connect/logout is the part of IDP sign-out interface. Fill in the location that the filter needs to jump behind parameter ?redirect_uri= when signing out. It is recommended to configure it as the FineReport login page.	No
Skip the request for SAML authentication (H5 Request)	A function for you to decide whether to allow h5 request without SAML authentication. When enabling, SAML authentication is required for h5 request. When disabling, SAML authentication cannot be skipped.	No
Skip the request for SAML authentication (Platform Login Page)	Allow login through the Decision-making Platform login page after enabing. Note: 1. Enabled by default. 2. When you disable the function,  you can only login with SAML authentication. And you cannot manually log out the Decision-making Platform without enabling SAML single sign-out function;  When enabling, it will redirect to the original FineReport login page when you log out. 3. Enabling the function when you configure or test SSO is recommended. After configuration is completed, if you do not need to use Platform Login Page, you need to disable the function. Otherwise the entrance will be retained,  and the address will be URL/login. For example, http://localhost:8075/webroot/decision/login	No
Custom	Customize the login requests, separated by semicolons for different requests. You can use wildcards in the request path. For example:/webroot/decision/t*;/webroot/decision/map/edit	No

Note:

When you only configure SAML single sign-on setting, but not configure SAML single sign-out setting:

1. Disable Platform Login Page: You will not log out the page when clicking Logout in the upper right corner and refreshing the page in the browser.

2. Enable Platform Login Page: Click Logout in the upper right corner to force a redirect to the default login page of the platform, but actually the platform is not logged out. When accessing http://{ip:port}/{project}/decision, the previous login status will be saved.

Disabling Enable SAML SSO

The admin accesses the platform, clicks Manage> System> SAML-SP Settings, disables Enable SAML SSO, and clicks Save.

Note:

If you need to perform single sign-on initiated from Azure AD (such as the single sign-on from My appsof Azure AD to the FineReport server), you need to configure the FineReport project for HTTPS access. For details, seeHTTPS Access by Configuring an SSL Certificate.

Filling out Basic SAML Configuration

1. Fill in Identifier (Entity ID) 

You can custom this configuration item, and this section takes jade as an example.

2. Fill in Reply URL (Assertion Consumer Service URL) 

You need to enter the access path of FineReport project. For example, https://localhost:37799/webroot/decision/sso/saml/acs

3. Fill in Sign on URL

This is a required field for performing single sign-on initiated from Azure AD. If you need to execute single sign-on initiated from Azure AD (such as the SSO from My apps of Azure AD to the FineReport server), you need to configure the FineReport project for HTTPS access. For details, see  HTTPS Access by Configuring an SSL Certificate. 

If you has configured the platform as HTTPS access, you can simply fill in the access path of the FineReport project here. For example: https://localhost:37799/webroot/decision

In other application scenario, you can fill in any https link.

4. After configuring all the required fields, click Save.

Completing Configuration items in FineReport

Configuration Item in FineReport	Target Information in Azure AD
IDP Metadata	App Federation Metadata URL
IDP Unique ID	Azure AD Identifier
IDP SSO Address	Login URL
IDP Public Key	Click to download Certificate (Base64), and then obtain the content in Notepad.
SP Unique ID	Can be customized. You can refer to the content in section "Filling out Basic SAML Configuration".
SP URL Enter the access path of the FineReport project, which ends at{directory1}/{directory2}/{directory3}/decision. For example: https://localhost:8443/webroot/decision	/
Upload SP Certificate and SP Private Key	/
Platform Login Page (Enabled by default) When it is disabled, you can only login with SAML authentication. And you cannot manually log out the decision-making platform without enabling SAML single sign-out function;  When enabled, it will redirect to the original FineReport login page when you log out. Note: Enabling the function when you configure or test SSO is recommended. After configuration is completed, if you do not need to use Platform Login Page, you need to disable the function. Otherwise the entrance will be retained,  and the address will be URL/login. For example, http://localhost:8075/webroot/decision/login	/

Demonstration

1.     Enter the original report link https://localhost:8443/webroot/decision, and SAML single sign-on is enabled.

2.     Click Logout, and it will return to https://localhost:8443/webroot/decision/login

Configuring the Settings in ADFS

1. Select Start > Administrative Tools > ADFS Management in ADFS, and then navigate to the Relying Party Trusts folder.

2. Select Action > Add Relying Party Trust.

3. Click Start to run the Add Relying Party Trust wizard.

4. Click Select Data Source > Import data about the relying party from a file, and select the metadata xml file exported from plugin setting page.

5. Click Next to skip the Configure Multi-factor Authentication Now? window.

6. Click Choose Issuance Authorization Rules > Permit all users to access this replying party and click Next.

7. In the Ready to Add Trust window:

Upload SP Certificate from FineReport server In Encryption tab and set Advanced to SHA-1.

8.Click Next in the Ready to Add Trust window.

9. In the Finish window, select Open the Edit Claim Rules dialog for this replying party trust when the wizard closes and click Close.

If the Edit Claim Rules dialog does not open when the wizard closes, right-click the name of the Relying Party Trust that you created, and select Edit Claim Rules...

10. In the Edit Claim Rules dialog, click Add Rule.

11. In the Select Rule Template dialog, for Choose Rule Type, select Send LDAP Attributes as Claims, and click Next.

12. Complete the Configure Rule dialog box:

For Claim rule name, enter UseridentiferToNameID (Or any other name you prefer).

For Attribute store, select Active Directory.

For LDAP Attribute, select SAM-Account-Name (Or any other attribute you use for username).

For Outgoing Claim Type, enter Name ID.

Note:

Username Mapping field should be set to the same value. In some versions of ADFS that allow custom values to be used instead of Name ID, the settings here should be the same as the Username Mapping in the plugin settings.

13. Click Finish.

Common problems and Solutions

Note:

Enable debug mode function is added in V1.0.2 version. When you do not need to debug, you need to disable the function. When encountering any problems, you can contact technical support for help in using the debugging function for troubleshooting.

Correct XML respond from ADFS will contain Name attribute. The correct format is as follows:

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

1. No Name ID Found in Document

./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.

Possible Causes

a. Outgoing Claim Mapping is not configured

b. In some versions of ADFS, Outgoing Claim Mapping must contain Name ID.

2. No Name Field Returned in XML

The Name field (Attribute Name) does not appear in the XML returned by ADFS:

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

Possible Causes

a. SP SSL certificate is not uploaded to ADFS.

b. ADFS encryption type is not set to SHA-1.

3. No Matching User Name Found

Presence of Name field (Attribute Name) in the XML returned by ADFS, but is not recognized by the login application:

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

Possible Causes

The Username Mapping in the SAML plugin does not have the same value as the Outgoing Claim Type setting.

4. User not exist, or wrong password

Presence of Name field (Attribute Name) in the XML returned by ADFS, but the login was not successful:

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

Possible Causes

The field set to Outgoing Claim Type in ADFS is not the username field in FineReport.