English (US)

中文 (简体)

English (US)

中文 (简体)

Theme

Authentication Methods ​

When users log in to the HENGSHI SENSE system, the system needs to verify the entered username and password to ensure system security. HENGSHI SENSE provides multiple single sign-on authentication methods such as CAS, SAML2, and OAUTH2. In SSO (Single Sign-On), HENGSHI SENSE acts as the Service Provider (SP), providing the necessary services to users, and implements user identity verification through the Identity Provider (IDP). Before using the authentication service, please ensure that the IDP and SP can communicate with each other.

Configure Base URL ​

The Base URL plays a crucial role in login authentication. Please set the Base URL before configuring the authentication.

Authentication Method Configuration ​

Set the authentication method for user login in the system at System Settings -> Authentication Method. Currently supported methods include HENGSHI, LDAP, CAS, SAML2, OAUTH2, DingTalk, WeCom, CTR, CloudHome, JWT, Feishu, Qince, and more.

When users log in to the system through the authentication method, some user information is also synchronized to the system through configuration items, such as synchronizing user attributes and organizational structure 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's built-in user authentication system verifies identities through user information within the platform. Even if another authentication method is set, HENGSHI system administrators can still log in via the /login page.

LDAP ​

Users use an LDAP authentication server to store user information and can choose the LDAP authentication method when they want to log in to the HENGSHI SENSE system using the same authentication method. When using LDAP authentication, you need to check the LDAP configuration in System Settings -> Authentication Method and configure LDAP-related settings.

Basic LDAP configuration includes:

  • Protocol types: ldap and ldaps.
  • Host address.
  • Port.
  • Username.
  • Password.
  • Search base.
  • LDAP query.

Common LDAP 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 common configuration fields, please refer to the Common Configuration section.

CAS ​

Users use the CAS authentication server to store user information and can choose the CAS authentication method when they want to log in to the HENGSHI SENSE system using the same authentication method. When using CAS authentication, you need to check the CAS configuration in System Settings -> Authentication Method and configure CAS-related settings.

Basic CAS configuration includes:

  • Protocol type.
  • CAS server address.
  • Reload User.

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

SAML2 ​

Users use the SAML2 authentication server to store user information and can choose the SAML2 authentication method when they want to log in to the HENGSHI SENSE system using the same authentication method. When using SAML2 authentication, you need to check the SAML2 configuration in System Settings -> Authentication Method and configure SAML2-related settings.

SAML2 authentication-related configurations include:

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

Common configurations for SAML2 to synchronize user attribute information 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 Party ID, Enable SSO exp Session Validity Synchronization, Session Validity Mapping. For explanations and usage of common configuration fields, please refer to the Common Configuration section.

OAuth2 ​

Users use the Oauth2 authentication server to store user information and can choose the Oauth2 authentication method when they want to log in to the HENGSHI system using the same authentication method. When using Oauth2 authentication, you need to check the Oauth2 configuration in System Settings -> Authentication Method and configure the Oauth2 settings.

OAUTH2 authentication-related configurations include:

  • Client Id, which is the client Id registered with the Oauth Server. Some systems may call it App Id. Different Oauth Servers may have different names.
  • Client Secret, which is the client Secret registered with the Oauth Server. Some systems may call it App Secret.
  • Authorize Interface, when the system detects that the user is not logged in, it will redirect to this address. The user enters their username and password to log in to the Oauth Server. After a successful login, the Oauth Server will redirect to the redirect_uri passed by HENGSHI, along with the code parameter.
  • Token Interface, the HENGSHI system requests a Token from this interface using the code parameter.
  • User-info Interface, the HENGSHI system requests basic user information from this interface using the Token.
  • Logout Interface, when the HENGSHI system logs out, it redirects to this interface to log out from the Oauth Server. Some Oauth Servers do not implement this interface.
  • Logout Interface Append Redirect URI, defaults to true. Whether the HENGSHI system appends the address of the HENGSHI page visited before logging out to the Logout interface when logging out.
  • Logout Redirect Address Parameter Name, defaults to redirect_uri. When the HENGSHI system sends a logout request to the Oauth Server, it passes this parameter, and the Oauth Server redirects to this address after logging out.
  • Scope, defined by the Oauth Server, configured in the HENGSHI SENSE system. The HENGSHI system passes this when requesting the code parameter. Newer versions of the Oauth Server keycloack (19.0.2 and above) require the scope to be configured with the value 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, after the user logs in successfully, they will be redirected to this address. It is usually recorded in the session. In scenarios where multiple iframe embedded pages are open simultaneously, it needs to be configured to pass in the URL.
  • Validate Original URL, the original URL refers to the user's original request address before logging in. If set to true, it will check if the original URL starts with the base URL.
  • Reload User, whether to re-fetch the currently logged-in user from the Oauth Server every time the page is refreshed. For specific usage scenarios, see Authentication Method Integration Instructions.

Logout-related instructions and examples (the following URLs are for example purposes only):

  • If the Logout Interface is not configured, only HENGSHI will be logged out.
  • If the Logout Interface http://logout.com is configured and Logout Interface Append Redirect URI is set to true, the logout redirect URL will be concatenated according to the Logout Redirect Address Parameter Name. The concatenated URL will be http://logout.com?redirect_uri=http://hengshi.com&activeAuth=oauth2&tenantId=xxxx. The redirect_uri will be encoded. For demonstration purposes, it is shown in plain text here. Whether the parameter name is redirect_uri depends on the Logout Redirect Address Parameter Name configuration.
  • In newer versions of keycloak, the logout parameter redirect_uri has changed. For the change description. If the Logout Interface is configured and Logout Interface Append Redirect URI is set to false, keycloak requires user confirmation to log out. If Logout Interface Append Redirect URI is set to true and the Logout Redirect Address Parameter Name is post_logout_redirect_uri, the logout behavior does not require user confirmation. The parameters and behaviors of keycloak may vary by version. For details, please refer to the keycloak documentation.

Common configurations for OAuth2 to synchronize user attribute 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 party ID, enable SSO session expiration synchronization, session expiration mapping. For explanations and usage of common configuration fields, please refer to the Common Configuration section.

Teams ​

Integration can be achieved through OAuth2 authentication. Teams obtains configuration information through the following steps:

  1. Add an application 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 application has been registered in Entra ID Microsoft. The application overview page will now be displayed. Record the "Application (client) ID" information and configure it in the "Client ID" field of the HengShi Oauth2 authentication method.

  2. Add Web authentication

    1. Under "Manage" in the left pane, select "Authentication".
    2. Select "Add platform > Web".
    3. Enter the application's redirect URL. For example, {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.

  3. Create a client secret

    1. Under "Manage" in the left pane, select "Certificates and 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, except immediately after creation. Be sure to save the password upon creation before leaving the page). Configure this secret in the "Client Secret" field of the HengShi Oauth2 authentication method.

  4. Obtain the configuration information required for the Oauth Client and configure HengShi Oauth authentication.

    1. Configure the "Application (client) ID" recorded in step [1.5] in the "Client ID" of the HengShi Oauth authentication.
    2. Configure the "client secret value" recorded in step [3.2] in the "Client Secret" of the HengShi Oauth authentication.
    3. Under "Overview" in the left pane, select "Endpoints" to view the relevant information. Configure the "OAuth 2.0 authorization endpoint (v2)" in the "Authorize interface" of the HengShi Oauth authentication. Configure the "OAuth 2.0 token endpoint (v2)" in the "Token interface" of the HengShi Oauth authentication. Open the URL under "OpenID Connect metadata document": Configure the "userinfo_endpoint" in the "User-info interface" of the HengShi Oauth authentication. Configure openid in the "Scope" of the HengShi Oauth authentication.

  5. At this point, the necessary information for integration through the OAuth2 authentication method has been configured. For more detailed configuration, please refer to the following materials:

    1. For HengShi Oauth2 configuration instructions, please refer to the OAuth2 section.
    2. For Teams-related explanations, please refer to the official documentation.

DingTalk ​

DingTalk authentication methods support QR code login and microapp免登 (microapp login without password).

DingTalk authentication-related configurations include:

Configuration ItemRequiredDescription
AppKeyYesBasic information of the DingTalk microapp, refer to the DingTalk Configure Microapp section for retrieval.
AppSecretYesBasic information of the DingTalk microapp, refer to the DingTalk Configure Microapp section for retrieval.
CorpIdNoThis information is required if the administrator needs to log in without password in the DingTalk application management backend. CorpId, SSOsecret can be obtained from the DingTalk Configure Microapp section.
SSOsecretNoThis information is required if the administrator needs to log in without password in the DingTalk application management backend. CorpId, SSOsecret can be obtained from the DingTalk Configure Microapp section.
Login MethodYesConfigure the default login method, which takes effect when no method is specified in the URL. authCode is for microapp免登 (microapp login without password), and scanning QR code is for QR code login.
Sync FrequencyNoConfigure the synchronization frequency for the organization structure, in minutes, with 0 meaning no synchronization. If organization structure synchronization is needed, AppKey and AppSecret must be configured, and the application must have the address book permission in the permission management.
AgentIdNoRequired for scenarios such as subscription and alert message push. Refer to DingTalk Work Notification for retrieval.

DingTalk's general configurations for synchronizing user attributes include 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.

Configuring DingTalk Micro App ​

The following describes how to create and configure a micro app on the DingTalk developer platform.

  1. Obtain DingTalk's CorpId and SSOSecret

    Obtain DingTalk CorpId and SSOSecret from the Development Experience Account Management in DingTalk.

    https://open-dev.dingtalk.com/fe/old?hash=%23%2FcorpAuthInfo#/corpAuthInfo

    DingTalk CorpId and SSOSecret.png

  2. Click to create an application in DingTalk Developer Backend -> Application Development -> H5 Micro App. Create Application

  3. In the basic information, you can view and obtain the AppKey and AppSecret. These two pieces of information need to be synchronized to the corresponding configuration fields on the DingTalk configuration page of the HENGSHI SENSE system. DingTalk App Credentials

  4. Add Application Capabilities

    Add Application Capabilities

  5. Web H5 Application Configuration

    Application H5 Configuration

    Configuration ItemFormatDescription
    Application Home Addresshttp://{host}:{port}/?activeAuth=dingtalk&dtLoginType=authCode&corpId={corpId}dtLoginType=authCode
    PC Home Addresshttp://{host}:{port}/?activeAuth=dingtalk&dtLoginType=authCode&corpId={corpId}dtLoginType=authCode
    Admin Backend Addresshttp://{host}:{port}/?activeAuth=dingtalk&dtLoginType=code&corpId={corpId}dtLoginType=code

    Please note

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

  6. Security Settings

    Permission Management

    Configuration ItemDescription
    Server Outbound IPFill in the server's outbound IP (can be queried via https://www.ip138.com/, or obtained from the network administrator).
    Redirect URL (Callback Domain)HENGSHI SENSE service baseURL.
    In-App Login AddressFill in as needed.

  7. Permission Management

    The currently known required permissions are as follows:

    Permission InformationPermission Point Code
    Read Permission for Department Information in Address Bookqyapi_get_department_list
    Read Permission for Member Informationqyapi_get_member
    Read Permission for Personal Information in Address BookContact.User.Read
    Enterprise Employee Mobile Number InformationfieldMobile
    Personal Information such as EmailfieldEmail

    Please note

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

    Permission Management

  8. Version Management and Publishing

    You can set the scope of application publishing as needed, only people within the scope can see the application.

Please note

The images related to DingTalk micro app documentation may change, refer to DingTalk's official documentation for the latest information.

WeCom ​

WeCom authentication supports QR code login and microapp login without password.

Configuration related to WeCom authentication includes:

  1. CorpID, AgentId, Secret: Basic information of WeCom, refer to the section WeCom Custom App Configuration for obtaining these details.
  2. Login Method: Configures the default login method, which is used when no specific method is specified in the URL. OAuth is for login without password, and QR code is for login by scanning a QR code.
  3. Scope:
    • snsapi_base: Silent authorization, which can obtain basic member information (UserId).
    • snsapi_privateinfo: Manual authorization, which can obtain detailed member information including phone number, email, etc. For more details, please refer to the WeCom developer documentation section on Authentication.

Common configurations for WeCom authentication, used for synchronizing user attribute information, include username mapping, display name mapping, email mapping, and phone number mapping. For explanations and usage of common configuration fields, please refer to the section Common Configuration.

Configure Custom Application for WeChat Work ​

  1. Go to WeChat Work App Management -> Apps -> Custom, and click "Create App".
  2. Configure the app logo, app name, app description, and visibility scope.
  3. Configure the application.
    1. Enter the AgentId and Secret into the corresponding fields on the WeChat Work configuration page in the HENGSHI SENSE system.
    2. Configure the app homepage, such as http://local.hengshi.org:8080?activeAuth=wechat-work&wcwLoginType=oauth2&tenantCode={tenantCode}. Here, activeAuth and wcwLoginType are fixed values, which enable login-free access to the HENGSHI app when clicked in WeChat Work. If using a tenant, you need to add the tenantCode or tenantId parameter.
    3. Configure the trusted domain in the webpage authorization and JS-SDK.
    4. If you need the web QR code login feature, configure the callback domain in the WeChat Work authorization login.

For related documentation on WeChat Work authentication methods, please refer to:

Note

The WeChat Work documentation may change, please refer to the official WeChat Work documentation.

CTR ​

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

Yunzhijia ​

If you use the Kingdee Yunzhijia app and perform reimbursement approval and report analysis tasks in Yunzhijia, you can configure Yunzhijia authentication to access the corresponding report content on Yunzhijia.

The entry point for the report is to create an app entry in Yunzhijia. Based on the integration API provided by Yunzhijia, perform an SSO authentication, directly configure the report URL in the Yunzhijia app, and open the report without logging in within the Yunzhijia app.

Configuration Method:

  1. Apply to become a system administrator on Yunzhijia (www.yunzhijia.com), or be invited by others and set as a system administrator.

  2. After becoming a system administrator, go to the lightweight app management page via the Management Center -> App Center -> Lightweight App Management.

  3. Select to create a new app, fill in the information on the opened page, and the URL in the red box is the URL of the HENGSHI SENSE system, with activeAuth=yunzhijia appended at the end. If a tenant is using it, you need to fill in the tenantCode or tenantId parameter, for example, http://192.168.3.226:8080/?activeAuth=yunzhijia&tenantCode=tenant1#/publish.

  4. After saving, an APPId and APPSecret will be generated.

  5. In the HENGSHI SENSE system, configure the APP ID and APPSecret in Settings -> Authentication Methods -> YUN ZHI JIA.

JWT Request Parameters ​

JWT request parameters refer to the process where, during user access to the system, user basic information is signed/encrypted according to the JWT specification and transmitted to the server via URL, balancing security and convenience.

Configuration related to JWT request parameter authentication includes:

  • JWT Token name.
  • Signature verification algorithm, consistent with HENGSHI SENSE configuration when the client signs.
  • Signature verification key, consistent with HENGSHI SENSE configuration when the client signs. For HS256 algorithm, the client and HENGSHI SENSE configuration should be consistent. For RS256 algorithm, the client uses a private key to sign, and the public key is filled in the HENGSHI SENSE configuration.
  • The signature verification key uses base64 decoding.
  • Decryption method, consistent with HENGSHI SENSE configuration when the client encrypts.
  • Decryption algorithm, consistent with HENGSHI SENSE configuration when the client encrypts.
  • Decryption key, the client uses a public key to encrypt, and the private key is filled in the HENGSHI SENSE configuration.
  • 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 the user after login. By default, the user's role after login is Data Viewer.

JWT request parameters related reference materials.

Common configurations for JWT request parameters to synchronize user attribute 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 party ID, enabling SSO exp session validity synchronization, session validity mapping, groovy script, etc. For explanations and usage of common configuration fields, please refer to the Common Configuration section.

JWT Basic Format Explanation ​

Claims in the JWT standard:

ClaimMeaningRequiredProcessing Logic and Restrictions
issJWT IssuerNoNone
subJWT SubjectYesNon-empty and unique. If there is no mapping configuration for loginName/email, HENGSHI will use this value as the user's unique identifier. If there is a mapping configuration for loginName/email, this value will be ignored. It is recommended to use the loginName/email mapping configuration, and the sub value should be the same as the loginName/email value.
expJWT Expiration TimeNoIf expired, the JWT becomes invalid.

Custom Claims:

ClaimMeaningProcessing Logic and Restrictions
Custom Claims with Mapping ConfigurationConfigured mapping relationship in HENGSHI systemHENGSHI will save the mapped information to the corresponding user field based on the mapping relationship. For example, if loginName=alice and the loginName mapping is configured as loginName in HENGSHI, alice will be saved as the loginName in HENGSHI. For other configurations, refer to General Configuration.
Custom Claims without Mapping ConfigurationNo mapping relationship configured in HENGSHI systemHENGSHI will save this type of information in the user attributes. For example, if abc=123 and there is no mapping configuration in HENGSHI, it will be saved as user attribute information.

A JWT consists of three parts of information, and these three parts of text are concatenated together with "." to form the JWT string. Here is an example:

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

Java example dependency library:

    <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 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 longer 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 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 above code. If modified, the token will also change.
        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, JWT requires it to be non-empty. If there is no login name mapping configuration, this value will be used as the login name by default. It must be unique and can be the same as the login name.
                //.issuer("https://c2id.com") //Issuer identity, represents 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, and the login name mapping needs to be configured in HENGSHI's [JWT parameter authentication] method. Here, the login name mapping should be configured as loginName.
                 * In HENGSHI, email, phone, roles, user groups, etc., can also be configured. For details, please refer to the documentation.*/
                .claim("loginName", loginName)
                .claim("abc", "123")       //Claims can be added as needed, and they will all be saved as user attributes
                //.expirationTime(new Date(new Date().getTime() + 60 * 1000)) //Expiration time, 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 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 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 login without password, and admin backend login without password.

Feishu authentication-related configurations include:

Configuring a Self-Built App in Lark ​

  1. Go to the Developer Console -> Enterprise Self-Built Apps -> Click on Enterprise Self-Built Apps.

  2. Fill in the app name and app description.

  3. In the list of enterprise self-built apps, click into the app you just created to complete the app information and edit the comprehensive information. Upload the app icon. You can optionally fill in the admin backend homepage http://{host}:{port}?activeAuth=lark&larkLoginType=larkAdminBackend, which is used for entering the system without login from the Lark admin backend. The specific address can be modified as needed, and the parameters activeAuth and larkLoginType are fixed. If this is not required, you can leave it blank.

  4. Configure app features, web pages, fill in the desktop homepage and mobile homepage. The specific addresses can be modified as needed, and 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

  5. Security settings, configure the redirect URL. http://{host}:{port}/lark/callback

  6. Permission management, enable permissions: Read contacts as app (contact:contact:readonly_as_app); Get user email information (contact:user.email:readonly); Get user user ID (contact:user.employee_id:readonly); Get user phone number (contact:user.phone:readonly), etc. (refer to the table for details) Among them, getting user email information, getting user user ID, and getting user phone number are optional permissions. If not enabled, Lark will not return this information.

​ Lark Required Permissions List:

Permission NameCodeDescription
Get user's available appsadmin:app.user_usable:readonly
Get user's organizational structure informationcontact:user.department:readonly
Get user email informationcontact:user.email:readonly
Get user user IDcontact:user.employee_id:readonly
Get group informationcontact:group:readonly
Get user ID by phone number or emailcontact:user.id:readonly
Get user phone numbercontact:user.phone:readonly
Get user gendercontact:user.gender:readonly
Query user job levelcontact:user.job_level:readonly
Query user's corporate emailmail:user_mailbox:readonly
Query personal email informationcorehr:person.email:read
Get basic contact informationcontact:contact.base:readonly
Read contacts as appcontact:contact:readonly_as_app
Get and send single chat, group messagesim:messageRequired for Lark message push
Send messages as appim:message:send_as_botRequired for Lark message push
Send messages to members of one or more departments in bulkim:message:send_multi_deptsRequired for Lark message push
Send messages to multiple users in bulkim:message:send_multi_usersRequired for Lark message push
Get and upload images or file resourcesim:resourceRequired for Lark message push

You can search for the following codes in the Lark permission configuration to quickly enable the required permissions:

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

​

  1. Version management and release, create a version, fill in the app version number and update description as required by Lark, and select the available range. Apply for online release.

  2. App review. 8.1 Manual review: Go to the Lark admin backend https://bc0nlvsmah.feishu.cn/admin/appCenter/audit, select the app to be reviewed for review. 8.2 Automatic review: Go to the Lark admin backend, app management, https://bc0nlvsmah.feishu.cn/admin/appCenter/manage Select the app to be set for automatic review, click configure, and enable the no-review feature.

  3. Configure the App ID and App Secret of the self-built Lark app in the system.

For documentation related to Lark authentication methods, please refer to:

  • App Login-Free
  • View App ID, App Secret Go to the Lark Open Platform, select the specific app, and view the App ID and App Secret.
  • Lark admin backend https://bc0nlvsmah.feishu.cn/admin/appCenter/manage login-free entry to the specific app If the admin backend homepage address is filled in the comprehensive information of credentials and basic information, you can enter the app without login from the Lark admin backend.

Please note

Lark documentation may change, please refer to the official Lark documentation.

General Configuration ​

Some authentication methods (e.g., OAuth2, jwt-param, etc.) support mapping configurations for login names, emails, phone numbers, etc. Under these authentication methods, these configurations have the same meaning.

  • Enable User Attribute Synchronization: Configure whether to synchronize user attributes.

  • Username Mapping: A field in the customer's system will be used as the login name of the user in the system, requiring uniqueness across the system. The purpose is to automatically associate the user with each login.

  • Display Name Mapping: A field in the customer's system will be used as the display name of the user in the system.

  • Email Mapping: A field in the customer's system will be used as the email of the user in the system, requiring uniqueness across the system. The purpose is to automatically associate the user with each login.

  • Phone Number Mapping: A field in the customer's system will be used as the phone number of the user in the system, requiring uniqueness across the system.

  • Role Mapping: A field in the customer's system will be used as the roles the user has in the system. Role IDs or role identifiers can be passed. If not passed, the default is data viewer. The role identifiers and role names correspond 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 field in the customer's system will be used as the groups the user belongs to in the system. Group IDs or group names can be passed.

  • Organization Structure Mapping: The organization structure in the customer's system can be mapped to the HENGSHI system.

  • Enterprise ID Mapping: This field can be used to map the enterprise ID in the system when logging in with a tenant method.

  • Enterprise Name Mapping: This field can be used to map the enterprise name in the system when logging in with a tenant method.

  • Platform Party ID: This field stores the platform party ID.

  • Enable SSO exp Session Validity Synchronization: Whether to synchronize the validity period in the session.

  • Session Validity Mapping: The session validity field, defaulting to exp.

As a JSON example, if the JSON passed by the customer's system is as follows:

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

The login name mapping in HENGSHI should be configured as uniqueName. The username mapping in HENGSHI should be configured as name. The email mapping in HENGSHI should be configured as email. The role mapping in HENGSHI should be configured as roles. The user group mapping in HENGSHI should be configured as groups.

Authentication Method Integration Instructions ​

  1. The HENGSHI SENSE system supports multiple authentication methods. Different authentication methods can be selected for different scenarios.
  2. Regardless of the chosen authentication method, you can log in with your HENGSHI username and password. The login address is: http://{host}:{port}/login.
  3. The selection of the HENGSHI authentication method supports both configuration page selection and URL parameter passing. Configuration page selection means it is the default authentication method. When no specific method is specified in the URL, this authentication method will be used. If a specific authentication method is specified in the URL, the method in the URL will be prioritized. For example, if the authentication method configuration is set to HENGSHI but the URL specifies activeAuth=oauth2, OAuth2 will be used for authentication. Example:
http://{host}:{port}/?activeAuth=oauth2#/
  1. To specify the authentication method via URL parameter for a tenant, you need to pass tenantCode={tenantCode} or tenantId={tenantId}. Example:
http://{host}:{port}/?activeAuth=oauth2&tenantCode={tenantCode}#/

Direct Use of HENGSHI System in Browser Scenario ​

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

iframe Embedding HENGSHI Pages Scenarios ​

Users may directly use the HENGSHI SENSE system in the browser to create applications, and then use iframe to embed HENGSHI visualization pages into the client's system, achieving seamless login through SSO. In this scenario, taking OAuth2 as an example:

  1. Both the chart creation in the browser using the HENGSHI SENSE system and the iframe embedding of visualization pages are achieved through the user's OAuth Server for seamless login. Therefore, it is only necessary to configure the OAuth authentication method, set reloadUser to false, and the iframe embedding address to http://{host}:{port}/?reloadUser=true#/. The purpose of reloadUser=true is that after logging out from the client's main site and switching users, when entering the HENGSHI page, HENGSHI will re-fetch the currently logged-in user from the OAuth Server. When using the HENGSHI SENSE system to create charts in the browser, there will be no situation of logging out from the main site, so it is not necessary to fetch the currently logged-in user from the OAuth Server every time.

  2. Users use the HENGSHI SENSE system in the browser to create charts with HENGSHI username and password login, while the iframe uses the OAuth Server for seamless login.

    2.1 Select HENGSHI authentication as the authentication method. Users use this method to log in when creating charts using the HENGSHI SENSE system in the browser.

    2.2 Configure the OAuth2 authentication method, set reloadUser to false, and the iframe embedding address to http://{host}:{port}/?activeAuth=oauth2&reloadUser=true#/. This allows users to achieve seamless login when viewing charts.

Mobile Micro-App Embedding Scenario in HENGSHI Pages ​

Mobile platforms primarily support DingTalk, WeChat Work, and CloudHome. The usage of embedding HENGSHI pages in mobile micro-apps is largely consistent with the scenario of embedding HENGSHI pages using iframes. The difference lies in configuring multiple HENGSHI page addresses on the mobile micro-app management page. Taking WeChat Work as an example:

  1. Select HENGSHI authentication, where users log in using their HENGSHI username and password on the web to create charts.
  2. Configure the HENGSHI embedding address on the WeChat Work custom app management page: http://{host}:{port}/?activeAuth=wechat-work&wcwLoginType=oauth2#/, allowing access to HENGSHI without login on both mobile and desktop platforms.

HENGSHI SENSE Platform User Manual

Copyright © 2016-2025 hengshi.com