SAML Single Sign-on Plugin

Version

Function Description

You need to log in to FineReport via Security Assertion Markup Language (SAML) authentication. This document provides a solution for configuring the SAML SSO.

You can download the SAML SSO plugin to enable zero-code SAML authentication for logging in to the decision-making platform easily and quickly.

Note:

When you connect to a remote server, SAML authentication is not used, and access is allowed by default.

Plugin Download

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

For details about how to install the plugin in the designer, see Designer Plugin Management.

For details about how to install the plugin on the server, see Server Plugin Management.

Page Introduction

After you install the plugin, it will take effect without a restart. The SAML SP Configuration tab will be added under System Management > System Setting.

Note:

1. You need to have the permission on System Management. Otherwise, the SAML SP Configuration tab will not be displayed.

2. Hot deployment is supported. The plugin can take effect without a project restart after being installed or enabled.

3. Configuration modification will take effect without a project restart.

Enabling SAML SSO

Enable Enable SAML SSO, as shown in the following figure.

SAML Configuration

After configuration, you need to click Save to apply the changes, as shown in the following figure.

Note: 

Incomplete configurations will result in a saving failure, as shown in the following figure.

The following table describes the configuration items.

Configuration Item	Description	Mandatory or Not
Enable SAML SSO	You can enable the function by clicking the toggle switch. With the function enabled, a filter is loaded. When accessing the decision-making platform via the original URL, you will be redirected to the page where the SSO logic is applied. Note:  The function can take effect without a restart.	/
Enable Debug Method	You can enable the function by clicking the toggle switch. With the function enabled, SAML assertions will be logged at the ERROR level in fanruan.log during the SSO authentication process. Note:  Since it is primarily intended for plugin debugging, you are advised not to enable the function. After it is enabled, the assertions will be output to the log, which may include information such as usernames and email addresses.	/
IDP Metadata	You need to enter the identity provider (IDP) metadata provided by the IDP. IDP metadata is generally in XML format and accessible via URLs. Therefore, you need to enter the URL where the data is located.	Yes
IDP Unique ID	You need to enter the identity provider (IDP) metadata provided by the IDP. Recommended retrieval method: Locate the keyword entityID in the IDP metadata file. The URL following this tag is the unique identifier of the IDP.	Yes
IDP SSO URL	You need to enter the IDP URL to which the filter will redirect you. The retrieval methods vary by the IDP. Perform the operations according to the actual needs.	Yes
IDP Public Key	You need to enter the public key used by the IDP to encrypt SAML assertions during transmission. Recommended retrieval method: Locate the keyword ds:X509Certificate in the IDP metadata file. The Base64-encoded string following this tag is the public key.	Yes
Username Mapping	This is an auxiliary function. If Username Mapping is set to the default value or left blank, the NameID field returned by the IDP is used.You can also use other user attribute fields returned by the IDP for SSO, for example, username or email.	No
Username Matching Rule	Starting from the SAML SSO plugin V1.1.7, this configuration item has been changed to formula-based definitions. Supported scope of the formula: 1. Case conversion UPPER(SAMLUSER): The parsed account names can be converted to uppercase before matching platform usernames for SSO. LOWER(SAMLUSER): The parsed account name can be converted to lowercase before matching platform usernames for SSO. Empty (no conversion): The system directly matches platform usernames for SSO using the original parsed account names without case conversion. Note:  1. SAMLUSER refers to the original account name provided by the IDP during the SAML authentication process. 2. To maintain compatibility with the plugin before V1.1.7, the original options, Default Rule, Uppercase Conversion Matching, and Lowercase Conversion Matching, are mapped to empty, UPPER(SAMLUSER), and LOWER(SAMLUSER), respectively. 2. String concatenation You can use the plus sign (+) to concatenate two strings. For example, you can combine the alice and @gmail.com strings using alice + @gmail.com. You can also use the CONCATENATE function, for example, CONCATENATE("alice","@gmail.com"), to concatenate strings. 3. Dataset function Only the VALUE, SQL, and MAP functions are supported.	Yes
SP Unique ID	Enter the service provider's identifier. (You can configure it as needed.)	Yes
Default SP Redirect URL	Enter the FineReport project access URL, which should end with /decision. For example, https://localhost:8443/webroot/decision	Yes
SP Certificate	Upload the certificate in the CRT, CER, or PEM format for encryption. Note: This certificate is used for encryption only. You can create a certificate yourself or obtain one from a certificate authority. In addition, you can also use the preset certificate: cert.zip.	Yes
SP Private Key	Upload the key file. The KEY file is supported. Note:  If you used the default certificate provided in SP Certificate in the document, you must use the corresponding key file:rsa_private.zip.	Yes
Generate Metadata XML File	Click the Generate Metadata XML File button to download the MetaData.xml file used by the service provider. Import the Metadata.xml file into the IDP to automatically generate a new SAML entity. If any of the five SP-related attributes (IDP public key, SP ID, default SP redirect URL, SP certificate, and SP private key) contains empty values, a prompt will be displayed, saying "Enter the relevant information completely, including IDP public key, SP unique ID, default SP redirect URL, SP certificate, and SP private key."	Yes
Enable SAML SLO	You can enable or disable the SAML single logout (SLO) function. The SAML SLO URL configuration item is available when the function is enabled.	No
SAML SLO URL	Enter the SAML SLO URL, which includes the IDP logout API, to enable SLO of both FineReport and the IDP. 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 represents the IDP logout API. The post-logout redirect URL is specified after ?redirect_uri= . You are advised to set the parameter value to the FineReport login URL.	No
Request Skipping SAML Authentication: H5 Request	You can enable or disable the function as needed. After this function is enabled, SAML authentication is not required for H5 requests. If this function is disabled, only login through SAML is supported.	No
Request Skipping SAML Authentication: Platform Login Page	After this function is enabled, SAML authentication is not required when you log in through the login page of the decision-making platform. Note:  1. The function is enabled by default. 2. If it is disabled, you can only log in through SAML, and cannot manually log out of the decision-making platform when SAML SLO is disabled. If it is enabled, you will be redirected to the FineReport login page when logging out of the decision-making platform. 3. You are advised to enable this function during SSO testing. After completing the configuration, if the original platform login page is no longer needed, disable this function. Otherwise, the original login entry will remain accessible via the URL formed by suffixing the original URL with /login, for example, http://localhost:8075/webroot/decision/login.	No
Custom Request Bypass	You can customize requests that need to be bypassed. You can separate requests by semicolons (;). Request paths can contain wildcards. For example, /webroot/decision/t*;/webroot/decision/map/edit	No

Note: 

When only SAML SSO is configured without SAML SLO:

If Platform Login Page is disabled, clicking the Exit button in the upper-right corner will refresh the page instead of logging you out.

If Platform Login Page is enabled, clicking the Exit button in the upper-right corner forcibly redirects you to the default platform login page, but you are not actually logged out. Accessing http://IP address:Port number/Project name/decision directly will still display the previous logged-in state.

Disabling the SAML SSO Function

Log in to the decision-making platform as the super admin, choose System Management > System Setting > SAML-SP Setting, disable Enable SAML SSO, and click Save, as shown in the following figure.

Note: 

To enable the SSO initiated by Azure AD (for example, accessing the FineReport server via SSO in My Apps portal in Azure AD), the FineReport project must first be configured for HTTPS access. Otherwise, the SSO function will fail. For details, see HTTPS Access by Configuring the SSL Certificate in Tomcat.

Basic SAML Configuration

1. Enter the Identifier (Entity ID)

You can customize the identifier. This section takes jade as an example.

2. Enter the Reply URL (Assertion Consumer Service URL)

You need to enter the reply URL consisting of the access URL (ending with decision) of FineReport project and the suffix /sso/saml/acs, for example, https://localhost:8080/webroot/decision/sso/saml/acs.

3. Enter the Sign on URL

This is a mandatory configuration item for executing SSO initiated from Azure AD. If you want to execute SSO initiated from Azure AD (for example, 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 the SSL Certificate in Tomcat.

If you have configured the platform for HTTPS access, you can simply enter the access URL of the FineReport project here, for example, https://localhost:8080/webroot/decision.

If this scenario is not required, you may enter any valid HTTPS URL.

4. After configuring all mandatory configuration items, click Save.

Configuration in FineReport

FineReport Configuration Item	Corresponding Azure AD Information
IDP Metadata	App Federation Metadata URL
IDP Unique ID	Azure AD Identifier
IDP SSO URL	Login URL
IDP Public Key	Click Download to download Certificate (Base64), view the content in Notepad, and obtain the desired information.
SP Unique ID	You can customize the identifier. (The configuration item has been mentioned in the "Basic SAML Configuration" section.)
Default SP Redirect URL Enter the FineReport project access URL, which should end with /decision.	/
SP Certificate and SP Private Key This certificate is used for encryption only. You can upload any valid certificate with encryption capabilities.	/
Platform Login Page under Request Skipping SAML Authentication is enabled by default. If Platform Login Page is disabled, you can only log in through SAML, and cannot manually log out of the decision-making platform when SAML SLO is disabled. If it is enabled, clicking the Exit button in the upper-right corner forcibly redirects you to the default platform login page. Note: You are advised to enable this function during SSO testing. After completing the configuration, if the original platform login page is no longer needed, disable this function. Otherwise, the original login entry will remain accessible via the URL formed by suffixing the original URL with /login, for example, http://localhost:8075/webroot/decision/login.	/

Accessing the original report URL https://localhost:8443/webroot/decision will trigger SAML SSO.

Clicking Exit will redirect you to https://localhost:8443/webroot/decision/login, as shown in the following figure. 

AD FS Setting

1. Start the Active Directory Federation Services (AD FS) service, choose Start > Administrative Tools > AD FS Management, and then navigate to the Relying Party Trusts folder.

2. Choose Action > Add Relying Party Trust.

3. Click Start to run Add Relying Party Trust Wizard.

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

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

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

7. In the Ready to Add Trust tab page:

Upload SP Certificate (SP license) from the FineReport server in the Encryption tab and set Advanced to SHA-1.

8. Click Next in the Ready to Add Trust tab page.

9. Choose Finish > 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 pop up 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 box, click Add Rule.

11. In the Select Rule Template dialog box, select Send LDAP Attributes as Claims from the drop-down list of Choose Rule Type, and click Next.

12. In the rule configuration dialog box:

• Enter UseridentifierToNameID in Claim rule name. You can also enter a custom value.

• Select Active Directory in Attribute store.

• Select SAM-Account-Name (or any other attribute) in LDAP Attribute.

• Enter Name ID in Outgoing Claim Type.

Note: 

The username mapping field in User Mapping should be set to the same value. In AD FS (of certain versions) that allow using custom values rather than being limited to NameID, the setting here should be the same as that of Username Mapping in the plugin.

13. Click Finish.

Common Issues and Solutions

Note: 

The Enable Debug Mode function is added in the plugin of V1.0.2. Keep the button disabled when debugging is not required. If you encounter any issues, contact the technical support for assistance in utilizing the debugging function for troubleshooting.

A valid SAML response from AD FS must include the name attribute in the XML format. The correct format is as follows:

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

No Name ID Found

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

1. Outgoing Claim Mapping was not configured.

2. In AD FS of certain versions, Outgoing Claim Mapping must include NameID. The current AD FS may not include it.

Name Field not Returned in the XML File

The SAML response returned from AD FS does not include the required name field.

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

Possible cause:

1. The SP SSL certificate was not uploaded to AD FS.

2. The encryption type, which should be SHA-1, was configured incorrectly.

No Matching Account Found

The SAML response returned from AD FS includes the name field (attribute name), but the target application cannot correctly identify or use this field.

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

Possible cause:

Username Mapping in the plugin and Outgoing Claim Type in AD FS were configured with different values, causing a mismatch between usernames and account names.

Account Not Found or Wrong Password

The SAML response returned from AD FS includes the name field (attribute name), but the login failed.

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

Possible cause:

The field set in Outgoing Claim Type in AD FS does not match the corresponding field set in Username Mapping in the plugin.

Failed Synchronous Logout from the Authentication Server and the Decision-making Platform

Problem: You are synchronously logged out of the decision-making platform when you log out of the authentication server.

Solution: You can upgrade the plugin to V1.0.8 and later versions.