Guandata BI-SSO Integration

1. Guandata SSO Integration Overview

Guandata SSO integration is a simple SSO integration solution based on RSA asymmetric encryption and decryption. This solution allows the use of third-party system accounts to authenticate Guandata Data Platform users and log in.

Integration steps include:

1. Generate an RSA key pair
2. Configure the RSA public key in Guandata BI
3. Use the RSA private key to encrypt login information and generate ssoToken
4. Carry the ssoToken in the Guandata link to log in and access

2. Log in and access Guandata system via SSO

2.1. Generate RSA key pair and configure

Ways to generate RSA key pair:

1. Generate the RSA key pair in the "System Integration" interface of Guandata BI
2. Use the program in 3.1 Java Example Code
3. Create it yourself, format must be PKCS#8, length 1024 bits

Then configure the public key in Guandata BI as shown below:

2.2. Encrypt login information and generate ssoToken

2.2.1. Parameters to be encrypted

Name	Type	Meaning	Required	Remarks
domainId	String	Domain ID	No	Not required since v5.9. Before v5.9, default is guanbi. See [How to get domainId info](../../../10-Tips and Best Practices/6-System Integration/0-How to get domainId info.md)
externalUserId	String	Third-party system user ID	Yes	Must be unique; recommended to be consistent with the account in Guandata system. If inconsistent, manual mapping is required.
timestamp	Integer	Current timestamp	No	If timestamp is passed, login must be completed within 5min from timestamp, otherwise login fails. If not passed, ssoToken is valid forever.
expiredTimeSeconds	Integer	Expiry duration (seconds)	No	If expiredTimeSeconds is passed, login must be completed within expiredTimeSeconds from timestamp, otherwise login fails.

Example before encryption:

{
  "domainId":"abcbi",
  "externalUserId": "userId",
  "timestamp": 1502079219
}

2.2.2. Encryption logic

Use the RSA private key to encrypt the login information to get the ssoToken. Steps:

1. Encrypt the content (JSON format) with the RSA private key;
2. Encode the encrypted content with Base64;
3. Since the encoded string may contain special characters like "=", convert the encrypted string to hex format.

See "3. RSA Encryption/Decryption Code Examples" for code.

2.3. Carry ssoToken to access BI link

Carry provider and the encrypted ssoToken in the BI link to achieve passwordless login.

URL:

?provider={provider}&ssoToken={ssoToken}

Method: GET

Parameters:

Name	Location	Type	Meaning	Remarks
provider	Path	String	Provider	Agreed string to identify the client's system. After 2019/12, provider is the domainId in Guandata, case-sensitive. See [How to get domainId info](../../../10-Tips and Best Practices/6-System Integration/0-How to get domainId info.md), usually guanbi.
ssoToken	Path	String	Encrypted login info	Token generated in step 2.2

Response:

The result is the Guandata home page. If the base URL is a page link, the corresponding page is returned.

2.4. Passwordless login to form entry (optional)

If you need passwordless login to form entry, add a fixed route after the host_url in the configured link as below, then add other parameters as required by third-party integration.

?path_url=survey-engine/

Example:

https://app.mayidata.com?path_url=survey-engine%2Fm%2Fsurvey%2F4bd86aa5-89d3-4b72-8186-a06170cdddbd

Notes for passwordless login link to form entry:

(1) Add the specified parameter "path_url=" before survey-engine Note: The parameter cannot be directly after "/", only after "?"

(2) The form entry link must be URL-encoded Note: You can use tools like https://www.bejson.com/enc/urlencode

Example:

Form link:

https://app.mayidata.com/survey-engine/survey/1b36b7ff-d470-475e-931f-df1ce53b3ed5

Passwordless login link after concatenation:

https://app.mayidata.com?path_url=survey-engine%2Fsurvey%2F1b36b7ff-d470-475e-931f-df1ce53b3ed5&...(other parameters)

3. RSA Encryption/Decryption Code Examples

3.1. Java Example Code

// ... Java code unchanged, see original for details ...

3.2. NodeJS Example Code

// ... NodeJS code unchanged, see original for details ...

3.3. .Net Example Code

// ... .Net code unchanged, see original for details ...

3.4. Notes

• The public/private keys, timestamp, etc. in the code examples are for reference only. Please replace with actual values.

4. FAQ

4.1. Cross-site Cookie

When using this SSO method for cross-system integration or embedding, cross-site Cookie issues may occur, causing BI to repeatedly prompt for login and not work properly.

Solution 1 (recommended): Adjust the BI service domain name to use a subdomain of the same site (main domain) as the external system.

Solution 2: Contact Guandata technical support or O&M to enable cross-site functionality. However, this may reduce token security.

4.2. Decryption Failure

Common reasons:

• Public/private keys do not match. Please check if the private key used for encryption matches the public key configured in Guandata BI.
• Provider is incorrect. After 2019/12, provider is the domainId in Guandata, case-sensitive. See [How to get domainId info](../../../10-Tips and Best Practices/6-System Integration/0-How to get domainId info.md), usually guanbi.