Authentication Methods

When users log in to the HENGSHI SENSE system, the system needs to verify the entered username and password to ensure security. HENGSHI SENSE provides multiple single sign-on (SSO) authentication methods, including CAS, SAML2, and OAUTH2. In SSO single sign-on, HENGSHI SENSE acts as the Service Provider (SP), offering the required services to users, while user identity verification is achieved through the Identity Provider (IDP). Before using authentication services, please ensure that communication between the IDP and SP is established.

Configure Base URL

Base URL plays an important role in login authentication. Before configuring authentication, please set the Base URL.

Authentication Method Configuration

Set the authentication method for user login in System Settings -> Authentication Method. Currently, HENGSHI, LDAP, CAS, SAML2, OAUTH2, DingTalk, Enterprise WeChat, CTR, Yunzhijia, JWT request parameters, Feishu, Qince, and other authentication methods are supported.

When users log in to the system through an authentication method, some user information will also be synchronized to the system via configuration items, such as synchronizing user attributes and organizational structures to the HENGSHI system. These configuration items are collectively referred to as general configuration items, which will be explained uniformly in General Configuration.

HENGSHI

HENGSHI has a built-in user authentication system that verifies identity using the platform's internal user information. Even if other authentication methods are configured, HENGSHI system administrators can still log in via the /login page.

LDAP

Users who store user information using an LDAP authentication server and wish to log in to the HENGSHI SENSE system using the same authentication method can choose the LDAP authentication option. When using LDAP authentication, you need to select the LDAP configuration and perform related LDAP settings in System Settings -> Authentication Method.

LDAP basic configuration includes:

Protocol types, including ldap and ldaps.
Host address.
Port.
Username.
Password.
Search base.
LDAP query.

LDAP general configuration includes username mapping, display name mapping, email mapping, phone number mapping, role mapping, group mapping, organizational structure mapping, enterprise ID mapping, enterprise name mapping, platform ID, enabling SSO exp session validity synchronization, and session validity mapping. For explanations and usage of general configuration fields, please refer to the General Configuration section.

CAS

Users who use the CAS authentication server to store user information and wish to log in to the HENGSHI SENSE system using the same authentication method can choose the CAS authentication option. When using CAS authentication, you need to select the CAS configuration and perform related CAS settings in System Settings->Authentication Method.

CAS basic configuration includes:

Protocol Type.
CAS Server Address.
Reload User.

CAS general configuration includes display name mapping, email mapping, phone number mapping, role mapping, group mapping, organizational structure mapping, enterprise ID mapping, enterprise name mapping, platform ID, enabling SSO exp session validity synchronization, and session validity mapping. For the description and usage of general configuration fields, please refer to the General Configuration section.

SAML2

Users who use the SAML2 authentication server to store user information and wish to log in to the HENGSHI SENSE system using the same authentication method can choose the SAML2 authentication option. When using SAML2 authentication, you need to select the SAML2 configuration in System Settings -> Authentication Method and perform the relevant SAML2 configuration.

The relevant SAML2 authentication configurations include:

idpMetadataUrl.
Private Key.
Certificate.
entityID.
Reload User.

The general configurations for synchronizing user attributes and other information using SAML2 include: Username Mapping, Display Name Mapping, Email Mapping, Phone Number Mapping, Role Mapping, Group Mapping, Organization Structure Mapping, Enterprise ID Mapping, Enterprise Name Mapping, Platform ID, Enable SSO exp, Session Validity Synchronization, Session Validity Mapping. For explanations and usage of the general configuration fields, please refer to the General Configuration section.

OAuth2

Users who use the OAuth2 authentication server to store user information and wish to log in to the HENGSHI system using the same authentication method can choose the OAuth2 authentication option. When using OAuth2 authentication, you need to select the OAuth2 configuration and perform related settings in System Settings -> Authentication Method.

The relevant configurations for OAuth2 authentication include:

Client Id: Refers to the client ID registered with the OAuth Server, also known as App ID in some systems. Different OAuth Servers may use different terms.
Client Secret: Refers to the client secret registered with the OAuth Server, also known as App Secret in some systems.
Authorize Endpoint: When the system detects that the user is not logged in, it redirects to this address, where the user can enter their username and password to log in to the OAuth Server. After a successful login, the OAuth Server redirects to the redirect_uri provided by HENGSHI, appending the code parameter.
Token Endpoint: The HENGSHI system uses the code parameter to request a token from this endpoint.
User-info Endpoint: The HENGSHI system uses the token to request basic user information from this endpoint.
Logout Endpoint: When logging out of the HENGSHI system, it redirects to this endpoint to log out of the OAuth Server. Some OAuth Servers may not implement this endpoint.
Logout Endpoint Append Redirect URI: Defaults to true. Determines whether the address visited before logging out of HENGSHI is appended to the logout endpoint during logout.
Post-logout Redirect URI Parameter Name: Defaults to redirect_uri. When the HENGSHI system sends a logout request to the OAuth Server, this parameter specifies the address to which the OAuth Server redirects after logging out.
Scope: Defined by the OAuth Server and configured in the HENGSHI SENSE system. The HENGSHI system passes this parameter when requesting the code. New versions of the OAuth Server, such as Keycloak (19.0.2 and above), require the scope to be set to openid.
Original URL Passing Method: Refers to the method of recording the user's original request address. For example, if the user enters the URL http://{host}:{port}/apps/1/dashboard/1, the system redirects to this address after a successful login. Typically, this is recorded in the session. In scenarios where multiple embedded iframe pages are opened simultaneously, it needs to be configured to pass via the URL.
Validate Original URL: The original URL refers to the user's original request address before logging in. If set to true, the system checks whether the original URL starts with the base URL.
Reload User: Determines whether the system needs to fetch the currently logged-in user from the OAuth Server every time the page is refreshed. For specific use cases, see Authentication Method Integration Instructions.

Logout-related notes and examples (URLs below are for demonstration purposes only):

If the Logout Endpoint is not configured, only HENGSHI will be logged out.
If the Logout Endpoint is configured as http://logout.com and Logout Endpoint Append Redirect URI is set to true, the system appends the post-logout redirect URL based on the Post-logout Redirect URI Parameter Name. The resulting URL would be http://logout.com?redirect_uri=http://hengshi.com&activeAuth=oauth2&tenantId=xxxx. The redirect_uri will be encoded; for demonstration purposes, plaintext is used here. The parameter name depends on the configuration of Post-logout Redirect URI Parameter Name.
In newer versions of Keycloak, the redirect_uri parameter for logout has changed. See the Change Notes. If the Logout Endpoint is configured and Logout Endpoint Append Redirect URI is set to false, Keycloak requires the user to confirm the logout. If Logout Endpoint Append Redirect URI is set to true and Post-logout Redirect URI Parameter Name is set to post_logout_redirect_uri, the logout action does not require user confirmation. Keycloak's parameters and behavior may vary by version; please refer to the Keycloak documentation for details.

OAuth2 configurations for synchronizing user attributes and other information include: username mapping, display name mapping, email mapping, phone number mapping, role mapping, group mapping, organizational structure mapping, enterprise ID mapping, enterprise name mapping, platform ID, enabling SSO session expiration synchronization, and session expiration mapping. For explanations and usage of these general configuration fields, please refer to the General Configuration section.

Teams

Integration can be achieved through OAuth2 authentication.

Teams retrieves configuration information through the following steps:

Add App Registration
1. Go to Azure
2. Select "App Registrations".
3. Select "+ New Registration".
4. Enter the name and other information, then click Register.
5. The app is now registered in Entra ID Microsoft. At this point, the app overview page will be displayed. Record the "Application (Client ID)" information and configure the "Application (Client ID)" into the "Client ID" field of HengShi OAuth2 authentication.
Add Web Authentication
1. Under "Manage" in the left pane, select "Authentication".
2. Select "Add a platform > Web".
3. Enter the app's redirect URL, e.g., {https://your-domain}/oauth2/callback?client_name=oauth2. Replace {https://your-domain} with the actual root path of the HengShi system, followed by /oauth2/callback?client_name=oauth2, then click Configure to save.
Create Client Secret
1. Under "Manage" in the left pane, select "Certificates & Secrets". Click "+ New Client Secret" on the right side of the page.
2. Under "Value", select "Copy to Clipboard" to save the client secret value for further use (the client secret value cannot be viewed after creation. Be sure to save the secret upon creation before leaving the page). Configure this secret into the "Client Secret" field of HengShi OAuth2 authentication.
Retrieve the configuration information required for the OAuth Client and configure HengShi OAuth authentication.
1. Configure the "Application (Client ID)" recorded in step [1.5] into the "Client ID" field of HengShi OAuth authentication.
2. Configure the "Client Secret" value recorded in step [3.2] into the "Client Secret" field of HengShi OAuth authentication.
3. Under "Overview" in the left pane, select "Endpoints" to view relevant information. Configure the "OAuth 2.0 Authorization Endpoint (v2)" into the "Authorize Interface" field of HengShi OAuth authentication. Configure the "OAuth 2.0 Token Endpoint (v2)" into the "Token Interface" field of HengShi OAuth authentication. Open the URL under "OpenID Connect Metadata Document": Configure the "userinfo_endpoint" into the "User-info Interface" field of HengShi OAuth authentication. Configure openid into the "Scope" field of HengShi OAuth authentication.
At this point, the necessary information for integration through OAuth2 authentication has been configured. For more detailed configuration, you can refer to the following resources:
1. HengShi OAuth2 configuration instructions can be found in the OAuth2 section.
2. For related explanations about Teams, please refer to the official documentation.

DingTalk

DingTalk authentication methods support QR code login and micro-app seamless login.

DingTalk authentication-related configurations include:

Configuration Item	Required	Description
AppKey	Yes	Basic information of DingTalk micro-app, refer to DingTalk Micro-App Configuration section for details.
AppSecret	Yes	Basic information of DingTalk micro-app, refer to DingTalk Micro-App Configuration section for details.
CorpId	No	If administrators need seamless login in the DingTalk application management backend, this information must be configured. CorpId and SSOsecret can be obtained from DingTalk Micro-App Configuration section.
SSOsecret	No	If administrators need seamless login in the DingTalk application management backend, this information must be configured. CorpId and SSOsecret can be obtained from DingTalk Micro-App Configuration section.
Login Method	Yes	Configure the default login method, which takes effect when the URL does not specify a method. authCode is for micro-app seamless login, and QR code is for login via scanning.
Sync Frequency	No	Configure the synchronization frequency for organizational structure, in minutes. 0 means no synchronization. If organizational structure synchronization is required, AppKey and AppSecret must be configured, and the app must enable address book permissions in permission management.
AgentId	No	Required for scenarios such as subscription and alert message pushing. Refer to DingTalk Work Notification for details.

DingTalk's general configuration for synchronizing user attributes includes username mapping, display name mapping, email mapping, and phone number mapping.
For explanations and usage of general configuration fields, refer to the General Configuration section.

DingTalk Configuration for Micro Apps

The following describes how to create and configure micro apps on the DingTalk Developer Platform.

Obtain DingTalk's CorpId and SSOSecret
Retrieve DingTalk CorpId and SSOSecret from Developer Experience Account Management in DingTalk.
https://open-dev.dingtalk.com/fe/old?hash=%23%2FcorpAuthInfo#/corpAuthInfo
In DingTalk Developer Console -> App Development -> H5 Micro App, click to create an app.
In the basic information section, you can view and obtain the AppKey and AppSecret. These two pieces of information need to be synchronized to the corresponding configuration fields in the DingTalk configuration page of the HENGSHI SENSE system.
Add App Capabilities

Web H5 App Configuration

App H5 Configuration

Configuration Item	Format	Description
App Homepage URL	http://{host}:{port}/?activeAuth=dingtalk&dtLoginType=authCode&corpId={corpId}	dtLoginType=authCode
PC Homepage URL	http://{host}:{port}/?activeAuth=dingtalk&dtLoginType=authCode&corpId={corpId}	dtLoginType=authCode
Admin Console URL	http://{host}:{port}/?activeAuth=dingtalk&dtLoginType=code&corpId={corpId}	dtLoginType=code

Please Note

{corpId} needs to be replaced with the correct corpId value.
If tenant configuration for DingTalk is required, you need to add the tenantCode or tenantId parameter (tenantId is recommended). The format is as follows: http://{host}:{port}/?activeAuth=dingtalk&dtLoginType=authCode&corpId={corpId}&tenantId={tenantId}
tenantId is automatically generated after creating a tenant.

Security Settings

Permission Management

Configuration Item	Description
Server Outbound IP	Enter the server outbound IP (can be queried via `https://www.ip138.com/` or obtained from the network administrator).
Redirect URL (Callback Domain)	BaseURL of the HENGSHI service.
In-App Login-Free URL	Fill in as needed.

Permission Management

Currently known required permissions are as follows:

Permission Information	Permission Code
Read Department Information	qyapi_get_department_list
Read Member Information	qyapi_get_member
Read Personal Contact Info	Contact.User.Read
Employee Mobile Number Info	fieldMobile
Email and Other Personal Info	fieldEmail

Please Note

DingTalk's permission management may change. Refer to DingTalk's official documentation for details.

Permission Management

Version Management and Release
You can set the usage scope for app release as needed. Only personnel within the scope can see the app.

Please Note

Images related to DingTalk micro app documentation may change. Refer to DingTalk's official documentation for accuracy.

Enterprise WeChat

Enterprise WeChat authentication methods support QR code login and app-based seamless login.

Enterprise WeChat authentication-related configurations include:

Enterprise ID, AgentId, Secret: Basic information of Enterprise WeChat, which can be obtained by referring to the Enterprise WeChat Configuration for Custom Apps section.
Login Method: This is the default login method configuration, which takes effect when no specific method is defined in the URL. OAuth enables app-based seamless login, while QR code login allows users to log in by scanning a QR code.
Scope:
- snsapi_base: Silent authorization, which allows access to basic member information (UserId).
- snsapi_privateinfo: Manual authorization, which allows access to detailed member information, including phone numbers, email addresses, etc. For more details, please refer to the Enterprise WeChat Developer Documentation Authentication section.

Enterprise WeChat authentication is used for general configurations to synchronize user attributes, such as username mapping, display name mapping, email mapping, and phone number mapping. For explanations and usage of general configuration fields, please refer to the General Configuration section.

Enterprise WeChat Configuration for Custom Applications

Navigate to Enterprise WeChat App Management -> Apps -> Custom, and click "Create App."
Configure the app logo, app name, app description, and visibility scope.
Configure the app.
1. Enter the AgentId and Secret into the corresponding fields on the Enterprise WeChat configuration page in the HENGSHI SENSE system.
2. Set up the app homepage, such as: http://local.hengshi.org:8080?activeAuth=wechat-work&wcwLoginType=oauth2&tenantCode={tenantCode}. Here, activeAuth and wcwLoginType are fixed values, enabling single sign-on when accessing the HENGSHI app within Enterprise WeChat. For tenant usage, you need to add the tenantCode or tenantId parameter.
3. Configure the trusted domain for web authorization and JS-SDK.
4. If you need the web QR code login feature, configure the authorization callback domain in Enterprise WeChat.

For related documentation on Enterprise WeChat authentication methods, refer to:

Enable Web Authorization Login
Enterprise WeChat Terminology Introduction
View Enterprise ID
View AgentId and Secret Navigate to the specific app.

Please Note

Enterprise WeChat documentation may change. Refer to the official Enterprise WeChat documentation for the latest updates.

CTR

CTR is a customized authentication method for customers, integrated with the customer's self-developed SSO system.

Yunzhijia

If you are using the Kingdee Yunzhijia app and performing expense approval and report analysis tasks within Yunzhijia, you can configure Yunzhijia authentication to access the corresponding report content directly on Yunzhijia.

The entry point for the report is to create an application entry in Yunzhijia. Using the integration API provided by Yunzhijia, you can set up SSO authentication and directly configure the report's URL address in the Yunzhijia app. This allows you to open the report in the Yunzhijia app without logging in.

Configuration steps:

Apply to become a system administrator on Yunzhijia (www.yunzhijia.com) or be invited and designated as a system administrator by someone else.
Once you are a system administrator, navigate to Management Center -> Application Center -> Lightweight Application Management to access the lightweight application management page.
Select "Create Application" and fill in the required information on the opened page. The URL in the red box should be the HENGSHI SENSE system's URL, with activeAuth=yunzhijia appended at the end. If it is for tenant use, you need to include the tenantCode or tenantId parameter. Example: http://192.168.3.226:8080/?activeAuth=yunzhijia&tenantCode=tenant1#/publish.
After saving, an APPId and APPSecret will be generated.
In the HENGSHI SENSE system, go to Settings -> Authentication Methods -> YUN ZHI JIA to configure the APP ID and APPSecret.

JWT Request Parameters

JWT request parameters refer to the process where users access the system by signing/encrypting their basic information according to the JWT specification and passing it to the server via URL, ensuring both security and convenience.

The configuration related to JWT request parameter authentication includes:

JWT Token Name.
Signature verification algorithm, which should be consistent with the HENGSHI configuration during client signing.
Signature verification key: When the verification algorithm is HS256, the client and HENGSHI configuration should be consistent. When the verification algorithm is RS256, the client uses a private key for signing, and the HENGSHI configuration specifies the public key.
Signature verification key uses base64 decoding.
Decryption method, which should be consistent with the HENGSHI configuration during client encryption.
Decryption algorithm, which should be consistent with the HENGSHI configuration during client encryption.
Decryption key: The client uses a public key for encryption, and the HENGSHI configuration specifies the private key.
The URL for accessing the system is: http://{host}:{port}/?activeAuth=jwt-param&jwtParam={signed/encrypted jwt string}
Groovy script: Configures the default role for users after login. By default, the role assigned to users after login is "Data Viewer."

Related Reference Materials for JWT request parameters.

The general configuration for synchronizing user attributes and other information using JWT request parameters includes username mapping, display name mapping, email mapping, phone number mapping, role mapping, group mapping, organizational structure mapping, enterprise ID mapping, enterprise name mapping, platform ID, enabling SSO exp session validity synchronization, session validity mapping, groovy script, and more.
For explanations and usage of general configuration fields, please refer to the General Configuration section.

JWT Basic Format Description

Standard claims in JWT:

Claim	Meaning	Required	Processing Logic and Restrictions
iss	JWT issuer	No	None
sub	JWT subject	Yes	Non-empty and unique. If there is no mapping configuration for loginName/email, HENGSHI uses this value as the unique identifier for the user. If there is a mapping configuration for loginName/email, this value is ignored. It is recommended to use the mapping configuration for loginName/email, where the value of `sub` is the same as the value of loginName/email.
exp	JWT expiration time	No	If expired, the JWT becomes invalid.

Custom claims:

Claim	Meaning	Processing Logic and Restrictions
Custom claims with mapping configuration	Mapping relationships are configured in the HENGSHI system	HENGSHI saves the information to the corresponding user fields based on the mapping relationships. For example, if `loginName=alice` is configured as the login name mapping in HENGSHI, `alice` will be used as the login name in HENGSHI. For other details, refer to General Configuration.
Custom claims without mapping configuration	No mapping relationships are configured in the HENGSHI system	HENGSHI saves this type of information as user attributes. For example, if `abc=123` is not configured in HENGSHI, it will be saved as user attribute information.

JWT consists of three parts of information, concatenated with "." to form a JWT string. Below is an example:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0.PGA9DNa-B_4e4WS-fVG57tvxYe0dlu0r8O_Lw1vEtAQ

The first part is the header, in plain text: {"typ":"JWT","alg":"HS256"}, which is encoded using base64URL to become eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
The second part is the payload, in plain text: {"sub":"alice-subject","abc":"123","roles":["system admin","data admin","data analyst","data viewer","api admin"],"loginName":"alice"} (where loginName, roles, and abc are custom example information that can be added or modified as needed). After base64URL encoding, it becomes: eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0.
The third part is the signature, generated by concatenating the first part (header) + "." + the second part (payload). The information to be signed is: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0. After signing with the corresponding algorithm (in this example, HS256) and encoding with base64URL, the signature becomes: PGA9DNa-B_4e4WS-fVG57tvxYe0dlu0r8O_Lw1vEtAQ. The above explains the basic process of generating a JWT. For more details and implementation libraries, visit the JWT official website.

Java example dependency:

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>nimbus-jose-jwt</artifactId>
    <version>5.4</version>
</dependency>

Java example code:

java

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.JWSHeader;
import com.nimbusds.jose.JWSSigner;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.MACSigner;
import com.nimbusds.jose.crypto.RSAEncrypter;
import com.nimbusds.jose.crypto.RSASSASigner;
import com.nimbusds.jwt.JWTClaimsSet;
import com.nimbusds.jwt.SignedJWT;

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.NoSuchAlgorithmException;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;

public class Test {
    public static void main(String[] args) throws Exception {
        // HS256 HMAC signature
        hmacSign();
        System.out.println("------------------------------------------");
        // RS256 RSA signature
        rsaSign();
        System.out.println("------------------------------------------");
        // A128CBC-HS256 RSA-OAEP-256 encryption
        signAndEncrypt();
    }

    // RS256
    public static void rsaSign() throws NoSuchAlgorithmException, JOSEException {
        KeyPairGenerator kpg = KeyPairGenerator.getInstance("RSA");
        KeyPair kp = kpg.genKeyPair();
        RSAPrivateKey privateKey = (RSAPrivateKey) kp.getPrivate();
        RSAPublicKey publicKey = (RSAPublicKey) kp.getPublic();
        JWTClaimsSet claimsSet = getJwtClaimsSet();

        JWSSigner signer = new RSASSASigner(privateKey);
        SignedJWT signedJWT = new SignedJWT(new JWSHeader.Builder(JWSAlgorithm.RS256).type(JOSEObjectType.JWT).build(), claimsSet);
        signedJWT.sign(signer);
        String token = signedJWT.serialize();
        String url = "http://{host}:{port}?activeAuth=jwt-param&jwtParam=" + token;
        System.out.println(url);
        // Verification key configured in the HENGSHI system
        System.out.println("Verification key=" + Base64.getEncoder().encodeToString(publicKey.getEncoded()));
    }

    // HS256
    public static void hmacSign() throws Exception {
        JWTClaimsSet claimsSet = getJwtClaimsSet();
        String key = "4b117a14-c652-410a-83b2-9839c16e7ae1"; // HS256 key, must be greater than 32 characters
        SignedJWT signedJWT = new SignedJWT(new JWSHeader.Builder(JWSAlgorithm.HS256).type(JOSEObjectType.JWT).build(), claimsSet);
        JWSSigner signer = new MACSigner(key);
        signedJWT.sign(signer);

        String token = signedJWT.serialize();
        String url = "http://{host}:{port}?activeAuth=jwt-param&jwtParam=" + token;
        System.out.println(url);
        // Verification key configured in the HENGSHI system
        System.out.println("Verification key=" + key);
        /*
        Note: Different signature content results in different tokens. The token below is generated based on the content in the code above. If modified, the token will change accordingly.
        Generated token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0.PGA9DNa-B_4e4WS-fVG57tvxYe0dlu0r8O_Lw1vEtAQ
        Example request URL: http://{host}:{port}?activeAuth=jwt-param&jwtParam=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0.PGA9DNa-B_4e4WS-fVG57tvxYe0dlu0r8O_Lw1vEtAQ
         */
    }

    private static JWTClaimsSet getJwtClaimsSet() {
        List<String> roles = new ArrayList<>();
        roles.add("system admin"); // System Administrator
        roles.add("data admin"); // Data Administrator
        roles.add("data analyst"); // Data Analyst
        roles.add("data viewer"); // Data Viewer
        roles.add("api admin"); // API Administrator

        String loginName = "alice"; // Login name, unique

        JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
                .subject(loginName + "-subject") // JWT subject, required to be non-empty. If no login name mapping is configured, this value is used as the default login name. Must be unique and can be the same as the login name.
                //.issuer("https://c2id.com") // Issuer identifier, representing the unique identifier of the token issuer, usually an HTTP(S) URL. Not used in HENGSHI.
                .claim("roles", roles)
                /* Login name, unique. The key can be set to any name. It needs to be configured in HENGSHI's [JWT Parameter Authentication] method as a login name mapping. For example, here it should be configured as loginName.
                 * HENGSHI can also configure mappings for email, phone, roles, user groups, etc. For details, refer to the documentation. */
                .claim("loginName", loginName)
                .claim("abc", "123") // Additional claims can be added as needed, all saved as user attributes.
                //.expirationTime(new Date(new Date().getTime() + 60 * 1000)) // Validity period, set as needed.
                .build();
        return claimsSet;
    }

    public static void signAndEncrypt() throws Exception {
        KeyPairGenerator kpg = KeyPairGenerator.getInstance("RSA");

        KeyPair signkp = kpg.genKeyPair();
        RSAPrivateKey signPrivateKey = (RSAPrivateKey) signkp.getPrivate();
        RSAPublicKey signPublicKey = (RSAPublicKey) signkp.getPublic();
        // Verification key configured in the HENGSHI system
        System.out.println("Verification key=" + Base64.getEncoder().encodeToString(signPublicKey.getEncoded()));
        JWTClaimsSet jwtClaimsSet = getJwtClaimsSet();
        SignedJWT signedJWT = new SignedJWT(
                new JWSHeader.Builder(JWSAlgorithm.RS256).type(JOSEObjectType.JWT).build(),
                jwtClaimsSet);

        signedJWT.sign(new RSASSASigner(signPrivateKey));
        KeyPair encryptKP = kpg.genKeyPair();
        RSAPrivateKey encryptPrivateKey = (RSAPrivateKey) encryptKP.getPrivate();
        // Decryption key configured in the HENGSHI system
        System.out.println("Decryption key=" + Base64.getEncoder().encodeToString(encryptPrivateKey.getEncoded()));

        RSAPublicKey encryptPublicKey = (RSAPublicKey) encryptKP.getPublic();
        JWEObject jweObject = new JWEObject(
                new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128CBC_HS256).type(JOSEObjectType.JWT)
                        .contentType("JWT")
                        .build(),
                new Payload(signedJWT));

        jweObject.encrypt(new RSAEncrypter(encryptPublicKey));
        String token = jweObject.serialize();
        String url = "http://{host}:{port}?activeAuth=jwt-param&jwtParam=" + token;
        System.out.println(url);
    }
}

Feishu

Feishu authentication methods support QR code login, micro-app seamless login, and admin console seamless login.

Feishu authentication-related configurations include:

App ID, App Secret: Basic information of Feishu, refer to Feishu Configuration for Custom Apps for details.

Feishu Configuration for Custom Applications

Navigate to Developer Console -> Enterprise Custom Applications -> Click on Enterprise Custom Applications.
Fill in the application name and description.
In the list of enterprise custom applications, click to enter the newly created application, complete the application information, and edit the comprehensive information. Upload the application icon. You can optionally fill in the management backend homepage http://{host}:{port}?activeAuth=lark&larkLoginType=larkAdminBackend, which is used for system access without login from the Feishu management backend. The specific address can be modified as needed, while the parameters activeAuth and larkLoginType are fixed. If this feature is not required, you can leave it blank.
Configure application features, web pages, and fill in the desktop homepage and mobile homepage. The specific addresses can be modified as needed, while the parameters activeAuth and larkLoginType are fixed. Desktop homepage: http://{host}:{port}?activeAuth=lark&larkLoginType=desktop
Mobile homepage: http://{host}:{port}?activeAuth=lark&larkLoginType=app
Security settings: Configure the redirect URL. http://{host}:{port}/lark/callback
Permission management: Enable permissions such as obtaining user basic information (contact:user.base:readonly), user email information (contact:user.email:readonly), user ID (contact:user.employee_id:readonly), and user phone number (contact:user.phone:readonly). For optional permissions like obtaining user email information, user ID, and user phone number, Feishu will not return this information if they are not enabled.

Feishu Required Permissions Overview:

Permission Name	Code	Description
Obtain user basic information	contact:user.base:readonly
Obtain user's usable applications	admin:app.user_usable:readonly
Obtain user organizational structure information	contact:user.department:readonly
Obtain user email information	contact:user.email:readonly
Obtain user ID	contact:user.employee_id:readonly
Obtain user group information	contact:group:readonly
Obtain user ID via phone or email	contact:user.id:readonly
Obtain user phone number	contact:user.phone:readonly
Obtain user gender	contact:user.gender:readonly
Query user job level	contact:user.job_level:readonly
Query user's corporate email	mail:user_mailbox:readonly
Query personal email information	corehr:person.email:read
Obtain basic contact information	contact:contact.base:readonly
Read contact information as an application	contact:contact:readonly_as_app
Send and receive single or group messages	im:message	Required for Feishu message push
Send messages as an application	im:message:send_as_bot	Required for Feishu message push
Send batch messages to members of one or more departments	im:message:send_multi_depts	Required for Feishu message push
Send batch messages to multiple users	im:message:send_multi_users	Required for Feishu message push
Obtain and upload image or file resources	im:resource	Required for Feishu message push

You can quickly enable the required permissions by searching the following codes in Feishu permission configuration:

basic

contact:contact:readonly_as_app,contact:contact.base:readonly,admin:app.user_usable:readonly,contact:user.department:readonly,contact:user.email:readonly,contact:user.employee_id:readonly,contact:group:readonly,contact:user.id:readonly,contact:user.phone:readonly,contact:user.gender:readonly,contact:user.job_level:readonly,mail:user_mailbox:readonly,corehr:person.email:read,im:message,im:message:send_as_bot,im:message:send_multi_depts,im:message:send_multi_users,im:resource

Version management and release: Create a version, fill in the application version number, update notes, and select the scope of availability as required by Feishu. Apply for online release.
Application review: 8.1 Manual review: Go to Feishu management backend https://bc0nlvsmah.feishu.cn/admin/appCenter/audit, select the application to be reviewed, and proceed with the review. 8.2 Automatic review: Go to Feishu management backend, Application Management, https://bc0nlvsmah.feishu.cn/admin/appCenter/manage, select the application to set up automatic review, click configure, and enable the no-review feature.
Configure the App ID and App Secret of the Feishu custom application in the system.

For related Feishu authentication documentation, refer to:

Application Single Sign-On
View App ID and App Secret Go to Feishu Open Platform, select the specific application, and view the App ID and App Secret.
Feishu management backend https://bc0nlvsmah.feishu.cn/admin/appCenter/manage Single Sign-On to specific applications If the management backend homepage address is filled in the comprehensive information under credentials and basic information, you can access the application via Single Sign-On in the Feishu management backend.

Please note

Feishu documentation may change; refer to the official Feishu documentation for the latest updates.

General Configuration

Certain authentication methods (e.g., OAuth2, jwt-param, etc.) support mapping configurations for login names, email addresses, phone numbers, etc. For authentication methods with these configuration options, they have the same meaning.

Enable User Attribute Synchronization: Configure whether to synchronize user attributes.
Username Mapping: A specific field in the customer system will be used as the login name for users in the system. It must be unique across the system to ensure automatic association with the user upon each login.
Display Name Mapping: A specific field in the customer system will be used as the display name for users in the system.
Email Mapping: A specific field in the customer system will be used as the email for users in the system. It must be unique across the system to ensure automatic association with the user upon each login.
Phone Number Mapping: A specific field in the customer system will be used as the phone number for users in the system. It must be unique across the system.
Role Mapping: A specific field in the customer system will be used as the roles assigned to the user in the system. Role IDs or role identifiers can be passed. If not provided, the default role is Data Viewer. The correspondence between role identifiers and role names is as follows:
- system admin: System Administrator.
- data admin: Data Administrator.
- data analyst: Data Analyst.
- data viewer: Data Viewer.
- api admin: API Administrator.
Group Mapping: A specific field in the customer system will be used as the group to which the user belongs in the system. User group IDs or group names can be passed.
Organization Structure Mapping: The organizational structure in the customer system can be mapped to the HENGSHI system.
Enterprise ID Mapping: When logging in via tenant mode, this field can be used to map the enterprise ID in the system.
Enterprise Name Mapping: When logging in via tenant mode, this field can be used to map the enterprise name in the system.
Platform ID: This field stores the platform ID.
Enable SSO Expiration Synchronization: Configure whether to synchronize the expiration period in the session.
Session Expiration Mapping: The session expiration field, defaulting to exp.

For example, if the JSON passed from the customer system is as follows:

json

{
  "uniqueName": "zhangsan",
  // Unique identifier
  "nickname": "Zhang san",
  "name": "Zhang San",
  "given_name": "Zhang San",
  "family_name": "Zhang",
  "roles": [
    "data admin",
    // Role identifier
    "data analyst"
  ],
  "groups": [
    "group1",
    // User group name
    "group2"
  ],
  "email": "zhangsan@hengshi.com"
}

In HENGSHI, the login name mapping should be configured as uniqueName.
In HENGSHI, the username mapping should be configured as name.
In HENGSHI, the email mapping should be configured as email.
In HENGSHI, the role mapping should be configured as roles.
In HENGSHI, the group mapping should be configured as groups.

Authentication Method Integration Instructions

The HENGSHI SENSE system supports multiple authentication methods, allowing you to choose different methods based on various scenarios.
Regardless of the authentication method chosen, you can log in using the HENGSHI username and password. The login URL is: http://{host}:{port}/login.
The selection of HENGSHI authentication methods supports two approaches: configuration page selection and URL parameter passing. Choosing on the configuration page means it is the default authentication method. If no specific method is specified in the URL, the default method will be used. However, if a specific authentication method is specified in the URL, the URL method will take precedence. For example: If the authentication method configured is HENGSHI, but the URL specifies activeAuth=oauth2, then OAuth2 will be used for authentication. Example:

http://{host}:{port}/?activeAuth=oauth2#/

To specify the authentication method for a tenant via URL parameters, you need to pass tenantCode={tenantCode} or tenantId={tenantId}. Example:

http://{host}:{port}/?activeAuth=oauth2&tenantCode={tenantCode}#/

Direct Use of HENGSHI System in Browser

In scenarios where users use the HENGSHI system in a browser and there is only one authentication method, it is only necessary to configure the corresponding authentication method and select it.

iframe Embedding HENGSHI Pages Scenario

Users may directly use the HENGSHI SENSE system in a browser to create applications and then embed HENGSHI visualization pages into their systems using iframe, achieving single sign-on (SSO) for seamless login. In this scenario, an example using OAuth2 is provided:

When users use the HENGSHI SENSE system in a browser for visualization and embed the visualization pages via iframe, both processes achieve seamless login through the user's OAuth Server. In this case, it is only necessary to configure the OAuth authentication method, set reloadUser to false, and use the iframe embedding address http://{host}:{port}/?reloadUser=true#/. The purpose of reloadUser=true is to ensure that when users log out from the main site and switch users, HENGSHI will retrieve the currently logged-in user from the OAuth Server upon entering the HENGSHI page. When using the HENGSHI SENSE system in a browser for visualization, there is no scenario of logging out from the main site, so it is unnecessary to fetch the currently logged-in user from the OAuth Server every time.
When users use the HENGSHI SENSE system in a browser for visualization, they log in using HENGSHI SENSE's username and password, while iframe achieves seamless login through the OAuth Server.
2.1 Select the HENGSHI authentication method. Users log in using this method when visualizing with the HENGSHI SENSE system in a browser.
2.2 Configure the OAuth2 authentication method, set reloadUser to false, and use the iframe embedding address http://{host}:{port}/?activeAuth=oauth2&reloadUser=true#/ to achieve seamless login for visualization.

Mobile Micro-App Embedding in HENGSHI Pages

The mobile platform primarily supports DingTalk, WeCom, and Yunzhijia.
The usage of mobile micro-app embedding in HENGSHI pages is generally consistent with the scenario of embedding HENGSHI pages via iframe.
The difference lies in configuring multiple HENGSHI page addresses on the mobile micro-app management page. Taking WeCom as an example:

Select HENGSHI authentication, where users log in on the web using their HENGSHI username and password to create charts.
Configure the embedded address of HENGSHI on the WeCom custom app management page:
http://{host}:{port}/?activeAuth=wechat-work&wcwLoginType=oauth2#/,
allowing seamless access to HENGSHI on mobile or desktop without additional login.

Chart Controls

Indicators

Map

Table

Advanced Chart Calculations

Filter

Model Providers

Authentication Methods ​

Configure Base URL ​

Authentication Method Configuration ​

HENGSHI ​

LDAP ​

CAS ​

SAML2 ​

OAuth2 ​

Teams ​

DingTalk ​

DingTalk Configuration for Micro Apps ​

Enterprise WeChat ​

Enterprise WeChat Configuration for Custom Applications ​

CTR ​

Yunzhijia ​

JWT Request Parameters ​

JWT Basic Format Description ​

Feishu ​

Feishu Configuration for Custom Applications ​

General Configuration ​

Authentication Method Integration Instructions ​

Direct Use of HENGSHI System in Browser ​

iframe Embedding HENGSHI Pages Scenario ​

Mobile Micro-App Embedding in HENGSHI Pages ​

Authentication Methods

Configure Base URL

Authentication Method Configuration

HENGSHI

LDAP

CAS

SAML2

OAuth2

Teams

DingTalk

DingTalk Configuration for Micro Apps

Enterprise WeChat

Enterprise WeChat Configuration for Custom Applications

CTR

Yunzhijia

JWT Request Parameters

JWT Basic Format Description

Feishu

Feishu Configuration for Custom Applications

General Configuration

Authentication Method Integration Instructions

Direct Use of HENGSHI System in Browser

iframe Embedding HENGSHI Pages Scenario

Mobile Micro-App Embedding in HENGSHI Pages