English (US)

中文 (简体)

English (US)

中文 (简体)

Theme

Authentication Methods ​

When users log in to the HENGSHI SENSE system, the system needs to verify the username and password entered 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 an important role in login authentication. Please set the Base URL before configuring authentication.

Authentication Method Configuration ​

Set the authentication method for user login in the system under System Settings -> Authentication Method. Currently supported methods include HENGSHI, LDAP, CAS, SAML2, OAUTH2, DingTalk, WeCom, CTR, CloudHome, JWT Request Parameters, 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 including ldap and ldaps.
  • Host address.
  • Port.
  • Username.
  • Password.
  • Search base.
  • LDAP query.

General 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 party 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 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 exp 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 session expiration synchronization, Session Expiration Mapping. For explanations and usage of common configuration fields, please refer to the Common Configuration section.

OAuth2 ​

Users can use an OAuth2 authentication server to store user information and choose the OAuth2 authentication method to log in to the HENGSHI system. When using OAuth2 authentication, you need to check the OAuth2 configuration in System Settings -> Authentication Method and set up the OAuth2-related configuration.

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 for this.
  • 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 will enter 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 address accessed by HENGSHI before logging out should be appended to the Logout interface.
  • Post-Logout Redirect URI Parameter Name, defaults to redirect_uri. This is the parameter passed by the HENGSHI system to the OAuth Server when requesting to log out. After logging out, the OAuth Server redirects to this address.
  • 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 keycloak (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 a successful login, the system will redirect 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 reload the current 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 illustrative 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 post-logout redirect URL will be concatenated according to the Post-Logout Redirect URI 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; here, it is shown in plain text for demonstration purposes. Whether the parameter name is redirect_uri depends on the Post-Logout Redirect URI Parameter Name configuration.
  • In newer versions of keycloak, the logout parameter redirect_uri has changed. For details, see 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 Post-Logout Redirect URI Parameter Name is post_logout_redirect_uri, the logout action 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, enabling SSO session expiration synchronization, and session expiration mapping. For explanations and usage of common configuration fields, please refer to the Common Configuration section.

Teams ​

Can be integrated via OAuth2 authentication.
Teams obtains configuration information through the following steps:

  1. Add 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 be displayed. Record the "Application (client) ID" information and configure it to the "Client ID" field in HengShi Oauth2 authentication.

  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 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 at the time of creation. Be sure to save the password when creating it and do not leave the page). Configure this secret to the "Client Secret" field in HengShi Oauth2 authentication.

  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] to the "Client ID" in HengShi Oauth authentication.
    2. Configure the "client secret value" recorded in step [3.2] to the "Client Secret" in 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)" to the "Authorize interface" in HengShi Oauth authentication. Configure the "OAuth 2.0 token endpoint (v2)" to the "Token interface" in HengShi Oauth authentication. Open the URL under "OpenID Connect metadata document":
      Configure the "userinfo_endpoint" to the "User-info interface" in HengShi Oauth authentication. Configure openid to the "Scope" in HengShi Oauth authentication.

  5. At this point, the necessary information for integration via OAuth2 authentication 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 supports QR code login and microapp login-free.

DingTalk authentication-related configurations include:

Configuration ItemRequiredDescription
AppKeyYesBasic information of the DingTalk microapp, refer to the DingTalk Microapp Configuration section for retrieval
AppSecretYesBasic information of the DingTalk microapp, refer to the DingTalk Microapp Configuration section for retrieval
CorpIdNoRequired if the administrator needs to log in without password in the DingTalk app management backend. CorpId, SSOsecret can be obtained from the DingTalk Microapp Configuration section.
SSOsecretNoRequired if the administrator needs to log in without password in the DingTalk app management backend. CorpId, SSOsecret can be obtained from the DingTalk Microapp Configuration section.
Login MethodYesConfigure the default login method, which takes effect when no method is specified in the URL. authCode is for microapp login-free, and scanning QR code is for QR code login
Sync FrequencyNoConfigure the synchronization frequency of the organization structure, in minutes, 0 means 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

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

DingTalk Micro App Configuration ​

Below 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 (it is 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

WeChat Work ​

WeChat Work authentication supports QR code login and microapp login without password.

Configuration related to WeChat Work authentication includes:

  1. CorpID, AgentId, Secret: Basic information of WeChat Work, refer to the section WeChat Work Configuration for Custom Applications for details.
  2. Login Method: Configures the default login method, which is used when no 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 and email. For more details, please refer to the WeChat Work developer documentation Authentication section.

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

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}. The activeAuth and wcwLoginType are fixed values, allowing for seamless login when clicking the HENGSHI app within WeChat Work. If using a tenant, you need to add the tenantCode or tenantId parameter.
    3. Configure the trusted domain in the Web 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:

Please note

The WeChat Work documentation may change, so refer to the official WeChat Work documentation for the most accurate information.

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's URL address 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 "New App" and fill in the information on the opened page. 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 signature verification algorithm is HS256. For RS256, 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 after user login, with the default role being data viewer.

JWT request parameters related reference materials.

General 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 general configuration fields, please refer to the General 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 is invalid.

Custom Claims:

ClaimMeaningProcessing Logic and Restrictions
Custom claims with mapping configurationConfigured mapping relationship in the HENGSHI systemHENGSHI will save the information to the corresponding user field based on the mapping relationship, e.g., loginName=alice, if the loginName mapping is configured as loginName in HENGSHI, alice will be used as the loginName in HENGSHI. For other configurations, refer to General Configuration.
Custom claims without mapping configurationNo mapping relationship configured in the HENGSHI systemHENGSHI will save this type of information in the user attributes, e.g., abc=123, if there is no mapping configuration in HENGSHI, it will be saved in the user attributes.

JWT consists of three parts of information, and these three parts of text are concatenated with "." to form the JWT string. Below 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 is 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, which can be added or modified as needed), and after base64URL encoding, it is eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0.
  3. The third part is the signature, the information to be signed is obtained from the header of the first part + "." + the payload of the second part, which is eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0, and after signing with the corresponding signature algorithm (HS256 in this example), and then base64URL encoding, the signature is PGA9DNa-B_4e4WS-fVG57tvxYe0dlu0r8O_Lw1vEtAQ.

This is the 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 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 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 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 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, required by JWT, if no login name mapping is configured, this value will be used as the login name by default. 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, need to configure login name mapping in HENGSHI [JWT parameter authentication] method, here should configure login name mapping as loginName
                 * In HENGSHI, you can also configure email, phone, roles, user groups, etc. For details, please refer to the documentation*/
                .claim("loginName", loginName)
                .claim("abc", "123")       //Claims can be added as needed, all will 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 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 login without password, and admin backend login without password.

Feishu authentication-related configurations include:

Configure Lark Custom App ​

  1. Go to the Developer Console -> Enterprise Custom App -> Click on Enterprise Custom App.

  2. Fill in the app name and app description.

  3. In the list of enterprise custom 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. (for details, refer to the table) 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.

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. User group IDs or user 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 from 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"
}

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 user group mapping 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. Selecting on the configuration page means it is the default authentication method. When no specific method is specified in the URL, this method will be used for authentication. 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 selects HENGSHI, but the URL specifies activeAuth=oauth2, OAuth2 will be used for authentication. Example:
    http://{host}:{port}/?activeAuth=oauth2#/
  4. 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, it is necessary to 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 the HENGSHI visualization page 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 the visualization page 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 is 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 Choose HENGSHI authentication as the authentication method. Users use this method to log in when creating charts with 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 devices 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 is that multiple HENGSHI page addresses will be configured 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 http://{host}:{port}/?activeAuth=wechat-work&wcwLoginType=oauth2#/ on the WeChat Work custom app management page, allowing access to HENGSHI without login on both mobile and desktop devices.

HENGSHI SENSE Platform User Manual

Copyright © 2016-2024 hengshi.com