Overview
Version
| Report Server Version | Plugin Version |
|---|---|
V10.0/V11.0 | V1.0.0 |
Application Scenario
Allowed you to configure single sign-on (SSO) in compliance with the OAuth 2.0 standard to integrate the FineReport/FineBI platform.
Allowed you to customize the SSO logic (such as parameter encryption/decryption and data request).
Allowed you to configure SSO logics independently for PC and mobile (H5 preview) terminals (namely, configure different SSO logics for PC and mobile terminals).
Notes
To configure the SSO logic for the mobile terminal, you need to configure the HTML5 plugin in advance for normal use.
You can install this plugin by hot deployment in V11.0. After installing and updating this plugin in V11.0, you need to restart the report project. Configuration modification in both V11.0 and V10.0 does not require restart.
After you update this plugin of 1.0.3 and earlier versions in V10.0, white screen issues will occur. In this case, you need to perform restart.
Plugin Introduction
Plugin Installation
You can contact our technical support to obtain the OAuth 2.0-Like SSO plugin.
For details about how to install plugins in the designer, see Designer Plugin Management.
For details about how to install plugins on the server, see Server Plugin Management.
Page Description
After this plugin is successfully installed, log in to the decision-making platform and choose System Management > SSO Integration to enter the function page, as shown in the following figure.
Select PC Access or Mobile Access and enable SSO configuration. (The configuration process is the same for both terminals. The following uses PC Access as an example.)
Oauth 2.0 Mode and Custom Authentication Mode are available to you for configuration.
Authentication Mode
No matter which authentication mode you select, the purpose is to obtain the username for logging in to the system. So during the request result configuration in the last step of plugin configuration, the parameter name needs to be fixed to fr_login_name, and the parameter value needs to be set based on the preceding configuration.
Custom Authentication Mode
Basic Configuration
Click Custom Authentication Mode and enable SSO Function, as shown in the following figure: (The basic configuration is the same in OAuth 2.0 Mode and Custom Authentication Mode.)
The following table describes the functions of each configuration item.
| No. | Configuration Name | Definition | Additional Description |
|---|---|---|---|
1 | Dynamically Get Report Domain Name | Function to dynamically or fixedly obtain the platform report domain name. | Dynamic (enabled): The domain name part of the requesturl parameter will be dynamically obtained. Fixed (closed): The domain name part (report server URL) of the requesturl parameter is read fixedly. Common application scenario:
|
2 | Report Platform URL | Access URL of the FineReport platform, for example, http://localhost:8075/webroot/decision | This URL is used in forwarding scenarios where the backend cannot correctly obtain the platform URL. |
3 | Keep Platform Login Page | Indicates whether to keep the login page for /decision/login. | Enabled: When you access /decision/login, the default login page of FineReport is displayed. Disabled: /decision/login is blocked. When you do not access this URL, the configured authentication logic is used. When you access this URL, you will be redirected to the /decision page. |
4 | Platform Logout URL | Platform logout URL, which can be used for SSO, for example, http://www.baidu.com | After platform logout, you will be redirected to this URL. |
5 | Login Failure Processing Logic | Login failure processing logic. | Display Error: If SSO steps fail, the error log is displayed on the page. Display Default Login Page: If SSO steps fail, you will be redirected to the default login page of FanRuan, where you can manually enter your account and password to log in again. (Note: If Keep Platform Login Page is disabled, the default login page will not be displayed after SSO fails, which may result in looped page redirection). |
Step Creation
Click Step Creation. Parameter Getting, Redirect, and Data Request are displayed. The three methods can be freely combined for configuration to obtain the username (fr_login_name) on the FanRuan platform.
1. Parameter Getting
The following table describes common use scenarios.
| Scenario | Parameter Name | Parameter Value | Description |
|---|---|---|---|
Predefine a parameter value. | paramA | demo | Defines a parameter named paramA whose value is demo. |
Get a parameter value. | paramB | ${paramA} | Defines a parameter named paramB whose value is the value of paramA. The following writing syntaxes are collectively referred to as formula syntaxes, which have the consistent writing requirements. paramA is generally sourced from the following two types:
|
Calculate a parameter value. | paramB | ${left(paramA, 3) + "_test"} | Defines a parameter named paramB whose value is calculated by a formula. The formula syntax logic is the same as that in FR. The built-in formulas in FR can all be used. Note that the formula content needs to be wrapped in ${}. For details about common encryption/decryption formulas, see section "Common Parameter and Formula Writing Syntax.' The parameter value in the example is a concatenation of the left three characters of paramA's value and the character string _test. For example, if the value of paramA is demo, the final result is dem_test. |
Transfer the actual login username. | fr_login_name | Name in any above writing syntaxes | If the parameter name is set to fr_login_name, the actual username used for login is the actually-calculated result of the parameter value. |
As shown in the following figure, after two parameter getting steps are configured, the parameter transfer effect can be achieved, which is equivalent to login through the fixed username demo.
2. Redirect
The common use scenario is as follows: You want to replace the default login page of FanRuan with the unified authentication platform available on the client for login. After login to the unified authentication platform, identification parameters such as code and token are carried to redirect you to the FanRuan URL.
Parameter Description:
Redirect URL: target URL to which you will be redirected. Usually, original access link addresses (for example, platform/report links) are concatenated into the URL parameter for callback after login. In this case, the fixed parameter requesturl is required to obtain the original access link addresses. This parameter supports formula writing syntaxes.
Token Parameter Name: name of the identification parameter carried during callback after login to the unified authentication platform available on the client, such as code and token. Token Parameter Name specifies information containing the login username Subsequent parsing is based on this parameter name. You can obtain the login username through configuring fr_login_name.
The following table lists configuration examples.
| Redirect URL | Token Parameter Name | Configuration Description |
|---|---|---|
${"http://ip:port/protal?redirect="+urlencode(requesturl)} | code | During access to links that require login authentication, for example, FanRuan platform/report links (excluding links that can be accessed without login authentication, for example, links passed through template authentication), redirect will be performed if the URL does not contain the code. In urlencode(requesturl):
For example, if the access address is http://localhost:8075/webroot/decision/view/report?viewlet=WorkBook6.cpt&aaa=123, the redirect URL is http://ip:port/protal?redirect=http%3A%2F%2Flocalhost%3A8075%2Fwebroot%2Fdecision%2Fview%2Freport%3Fviewlet%3DWorkBook6.cpt%26aaa%3D123. |
3. Data Request
This method is actually to simulate the action of sending a request. You need to configure the request type, request address, request header, and request body. You can configure them according to the API document provided by the customer.
The parameter values of the request address, request header, and request body support formula writing syntaxes. You can also obtain the parameters pre-defined in previous steps.
The following table lists writing syntax examples of request results.
| Parameter Name | API Request Result Example | Parameter Value | Configuration Description |
|---|---|---|---|
userId | { "status": "1", | data.accountId | If the result returned by the API is in a simple JSON data format, you can concatenate keys using periods (.) to obtain the corresponding field value. In this writing syntax, the 10087897 value is assigned to the userId parameter. |
userId | { "store": { "book": [{ "category": "reference" "author": "Nigel Rees" "title": "Sayings of the Century" "price": 8.95 }, { "category": "fiction" "author": "Evelyn Waugh" "title": "Sword of Honour" "price": 12.99 }, { "category": "fiction" "author": "Herman Melville" "title": "Moby Dick" "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction" "author": "J. R. R. Tolkien", "title": "The Lord of the Rings" "isbn": "0-395-19395-8", "price": 22.99 }], "bicycle": { "color": "red", "price": 19.95 } } } | $..book[2].author | If the result returned by the API is in a complex JSON data format, you can use the jpath statement to obtain the execution value.
In this syntax, the value of author in the second book node is assigned to the userId parameter. |
fr_login_name | Name in any above writing syntaxes | If the parameter name is set to fr_login_name, the actual username used for login is the actually-calculated result of the parameter value. |
OAuth 2.0 Mode
As the most common authentication method based on the authorization code, the OAuth 2.0 mode can actually be understood as a conventional custom authentication mode. Its fixed configuration logic allows you to perform configuration according to the document provided by the customer.
Basic Configuration
For details, see section “Basic Configuration” in "Custom Authentication Mode." The following figure shows details.
Other Configurations
1. Initial Parameter
Configure initialization parameters, such as client_id and secret. The configuration has the same effect as the parameter getting step. You can reference corresponding parameters in the parameter pre-definition, authentication API address, and subsequent steps.
| Setting Item | Parameter Name |
|---|---|
Client ID | ${client_id} |
Client Secret | ${client_secret} |
Grant Type | ${grant_type} |
Scope | ${scope} |
State | ${state} |
Token Name | Value actually entered. For example, if you enter code, you can use ${code} to obtain the value of this parameter in the subsequent step. |
Authentication API URL: If you do not log in to the FanRuan decision-making platform, you are redirected to the address of the customer's OAuth 2.0 authentication platform, for example, ${"http://ip:port/oauth/login?redirect=" + URLEncode(requestURL)+ "&client_id=" + client_id + "&scope=" + scope}.
2. Token Application
Based on the value (code) of Token Name carried after login to the authentication platform, the system requests the access token from the customer API.
3. User Info
Based on the access token, the login username is obtained for login.
Advanced Setting
The Advanced Setting option is available in the plugin of V1.0.4 and later versions.
Callback URL Setting
Some authentication centers require callback URL verification. After you log in to the authentication center, the system can only redirect you to a fixed URL. This means that you cannot be redirected to different report links through SSO. To solve this problem, you can use a custom callback URL. In addition to the fixed redirect_uri, you can add a custom parameter, for example, state, to carry the URL accessed before authentication. After calling back to the fixed URL, the plugin obtains the value of the custom parameter as the new address and redirects you to the new address.
However, some authentication centers also have restrictions on the parameters carried during redirect. In this case, you can enable Transfer by Cookie. Before redirect, the plugin stores the requested URL in the cookie. After callback to the FanRuan platform, the system will redirect you to the access address stored in the cookie.
For configuration convenience, you are advised to preferentially transfer the URL through the cookie.
Custom Error Page Info
After customization, the configured error message instead of the actual error reason will be displayed if a plugin error occurs. This is a configuration item that is not recommended because it will affect the determination of error reasons. For example, if "Sorry, an error occurred." is set here, the following figure shows the effect.
Log Page Display
If encountering errors during SSO configuration, you often need to export logs to locate reasons, which is cumbersome. By enabling Log Page Display, you can access http://ip:port/webroot/decision/sso/plugin/log to view the logs output by the SSO plugin. The log level here is the same as that set on the platform.
Example
SSO Through &user=Anna Carried in the URL
In this example, the Parameter Getting method in Custom Authentication Mode is used. But this method has lower security because it uses the plain-text username for login. This example only displays the basic plugin functions. This method is less used in actual scenarios.
Configuration
The parameter name is set to fr_login_name, and the parameter value is set to Anna (a user of the FanRuan decision-making platform), as shown in the following figure.
You can also configure a concatenation of any parameter name and parameter value here for login.
Effect
Click Save in the upper right corner and log in to http://localhost:8075/webroot/decision?user=Anna. In this case, you can directly enter Anna's decision-making platform page without entering any account or password.
If you want to dynamically obtain the parameter transferred in the URL, you can set the parameter value to ${user}. In this way, you can access http://localhost:8075/webroot/decision?user=xxx (where xxx is any username of the decision-making platform) to achieve dynamic username login.
SSO Through the Parameter Carried in the URL (Requiring API Authentication)
In this example, the Data Request method in Custom Authentication Mode is used. Ciphertexts are generated based on JWT encryption, as shown in the following figure.
For example, the username Anna is encrypted using the key ceshi according to the JWT standard to obtain a ciphertext.
Configuration
In actual business scenarios, you just need to perform configuration based on the configuration document provided by the customer. The following figure shows the configuration in this example.
The following figure displays specific parameter configuration.
| Setting Item | Content |
|---|---|
Request URL | POST/${"http://localhost:8075/webroot/decision/sso/test/jwt/decode/json?token=" + token} |
Request Header | Parameter name: hk; parameter value: hv |
Request Body | JSON parameter name: bk; parameter value: bv Parameter name: key; parameter value: ceshi |
Request Result | Parameter name: fr_login_name; parameter value: data |
In actual configuration, the configuration document provided by the customer includes specific information such as the request address, request header, request body, request result, and encryption method.
JWT encryption in this example is just for reference. In actual scenarios, you need to perform configuration according to the requirements of the customer-provided configuration document.
Effect
Perform simulation using Postman. Set required parameters to send a request. In the returned result, the username Anna has been parsed. The URL accessed is http://localhost:8075/webroot/decision/sso/test/jwt/decode/json?token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBbm5hIiwiZXhwIjoxNjY2NjA2Njc1fQ.D3K4xzmTZK070MA7nMMveh8sLH6fB3khJnEfd-CGoS0.
The value of token is the ciphertext generated in the previous step.
OAuth 2.0 SSO Authentication
Configuration
In actual business scenarios, you just need to perform configuration based on the configuration document provided by the customer. The configuration document provided by the customer must contain required parameters and address information that need to be configured. The following figure shows the configuration in this example.
Initial Parameter:
Token Application:
User Info:
The following figure displays specific parameter configuration.
| Category | Setting Item | Content |
|---|---|---|
Initial Parameter | Client ID | ci |
Client Secret | cs | |
Token Name | code | |
Scope | sc | |
State | st | |
Authentication API URL | ${"http://localhost:8075/webroot/decision/sso/test/oauth/login?redirect=" + URLEncode(requestURL)} | |
Token Application | Request URL | POST/${"http://localhost:8075/webroot/decision/sso/test/oauth/access?code=" + code} |
Request Header | / | |
Request Body | x-www-form-urlencoded | |
Request Result | Parameter name: access; parameter value: data.access | |
User Info | Request URL | POST/http://localhost:8075/webroot/decision/sso/test/oauth/user |
Request Header | / | |
Request Body | form_data | |
Request Result | Parameter name: fr_login_name; parameter value: data.name |
Effect
Click Save in the upper right corner and log in to http://localhost:8075/webroot/decision. Then you will be redirected to the authentication center address http://localhost:8075/webroot/decision/sso/test/oauth/login?redirect=http%3A%2F%2Flocalhost%3A8075%2Fwebroot%2Fdecision.
Enter the username to log in to the decision-making platform.
Common Parameter and Formula Writing Syntax
The following table lists formulas supported currently and names of some fixed parameters.
| Formula Name | Formula Description | Example |
|---|---|---|
requestURL | URL of the access link address | ${"https://ip:port?redirect=" +requestURL} |
Base64Decode/Base64Encode | Base64 encoding/decoding | ${Base64Decode(accessToken)} |
JwtEncode/JwtDecode | JWT encryption/decryption | ${JwtEncode(accessToken, "FineReport2018", 60000)}
${JwtDecode(accessToken, "FineReport2018")}
|
URLEncode/URLDecode | URL encoding/decoding | ${URLEncode(accessToken)} ${URLDecode(accessToken)} |
HexDecode/HexEncode | Hex encoding/decoding | ${HexDecode(accessToken)} |
AESDecrypt/AESEncrypt | AES encryption/decryption | ${AESDecrypt("AES/ECB/NoPadding", HexDecode(yx_encrypt_ticket), "3.14159265358979")}
${AESEncrypt("AES/ECB/NoPadding", HexDecode(yx_encrypt_ticket), "3.14159265358979")}
|
SM2Decrypt/SM2Encrypt | SM2 encoding/decoding | ${SM2Decrypt(accessToken, "FineReport2018")} ${SM2Encrypt(accessToken, "FineReport2018")}
|
SM4Decrypt/SM4Encrypt | SM4 encoding/decoding | ${SM4Decrypt(accessToken, "FineReport2018")} ${SM4Encrypt(accessToken, "FineReport2018")}
|
SM3Encrypt | SM3 encoding/decoding | ${SM3Encrypt(accessToken)} |
MD5 | MD5 signature | ${MD5(accessToken)} |
Note:Formulas embedded into FR are supported. Formulas are case-insensitive in formula writing syntaxes.
