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 authentication.

Authentication Method Configuration ​

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

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 uniformly explained 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.

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 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.

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 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 related 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 finds that the user is not logged in, it will redirect to this address, where the user enters their username and password to log in with the Oauth Server. After a successful login, the Oauth Server will redirect to the redirect_uri passed by HENGSHI and add the code parameter.
  • Token Interface, the HENGSHI system requests the Token through the code parameter to this interface.
  • User-info Interface, the HENGSHI system requests the user's basic information through the Token to this interface.
  • Logout Interface, when the HENGSHI system logs out, it redirects to this interface to log out with the Oauth Server. Some Oauth Servers do not implement this interface.
  • Logout Interface Concatenate Redirect URI, default is true, whether the HENGSHI system should concatenate the address of the HENGSHI page visited before logging out to the Logout interface when logging out.
  • Logout Redirect Address Parameter Name, default is redirect_uri, passed by the HENGSHI system when making a logout request to the Oauth Server, and the Oauth Server redirects to this address after logging out.
  • Scope, defined by the Oauth Server, configured in the HENGSHI SENSE system, and passed by the HENGSHI system when requesting the code parameter. New 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, such as the Url entered by the user is http://{host}:{port}/apps/1/dashboard/1, after the user logs in successfully, they will be redirected to this address. It is generally recorded in the session, and in scenarios where multiple iframe embedded pages are opened simultaneously, it needs to be configured to pass in the url.
  • Verify Original URL, the original URL refers to the user's original request address before logging in. If true is selected, it will check whether the original URL starts with the base URL.
  • Reload User, whether to re-obtain 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 only):

  • If the Logout Interface is not configured, only HENGSHI will be logged out.
  • Configure the Logout Interface http://logout.com, and Logout Interface Concatenate Redirect URI is true, then it will concatenate the redirect URL after logout according to the Logout Redirect Address Parameter Name, after concatenation it will be http://logout.com?redirect_uri=http://hengshi.com&activeAuth=oauth2&tenantId=xxxx, the redirect_uri will be encoded, here it is displayed in plain text for demonstration purposes, whether the parameter name is redirect_uri is subject to the Logout Redirect Address Parameter Name configuration.
  • The redirect_uri parameter for logout in the new version of keycloak has changed, Change Description. If the Logout Interface is configured, and Logout Interface Concatenate Redirect URI is false, keycloak requires the user to click to confirm logout. If Logout Interface Concatenate Redirect URI is true, and 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, please refer to the keycloak documentation for details.

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.

DingTalk ​

DingTalk authentication supports QR code login and microapp login-free.

DingTalk authentication-related configurations include:

Configuration ItemRequiredDescription
AppKeyYesBasic information of DingTalk microapp, refer to the DingTalk Microapp Configuration section for retrieval
AppSecretYesBasic information of 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 refer to the DingTalk Microapp Configuration section for retrieval.
SSOsecretNoRequired if the administrator needs to log in without password in the DingTalk app management backend. CorpId, SSOsecret refer to the DingTalk Microapp Configuration section for retrieval.
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 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.

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 App Configuration

    App H5 Configuration

    Configuration ItemFormatDescription
    App Homepage URLhttp://{host}:{port}/?activeAuth=dingtalk&dtLoginType=authCode&corpId={corpId}dtLoginType=authCode
    PC Homepage URLhttp://{host}:{port}/?activeAuth=dingtalk&dtLoginType=authCode&corpId={corpId}dtLoginType=authCode
    Admin Backend URLhttp://{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 the 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

Enterprise WeChat ​

Enterprise WeChat authentication supports QR code login and micro app login without password.

The relevant configurations for Enterprise WeChat authentication include:

  1. Enterprise ID, AgentId, Secret: Basic information of Enterprise WeChat, refer to the section Enterprise WeChat Custom App Configuration for obtaining.
  2. Login Method: This configures the default login method, which takes effect when no method is specified in the URL. OAuth is for password-free login, and QR code is for login by scanning a QR code.

The general configurations for Enterprise WeChat authentication, used 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 section General Configuration.

Configure WeChat Work Custom Application ​

  1. Enter WeChat Work Application Management -> Applications -> Custom, and click to create an application.
  2. Configure the application logo, application name, application description, and visibility scope.
  3. Configure the application.
    1. Fill in the AgentId and Secret into the corresponding fields on the WeChat Work configuration page in the HENGSHI SENSE system.
    2. Configure the application homepage, such as http://local.hengshi.org:8080?activeAuth=wechat-work&wcwLoginType=oauth2&tenantCode={tenantCode}. The activeAuth and wcwLoginType are fixed values, which can enable single sign-on when clicking the HENGSHI application in 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, please refer to the official WeChat Work documentation.

CTR ​

CTR is a customized authentication method for clients, which is integrated with the client's self-developed SSO system.

Cloud Home ​

If you use the Kingdee Cloud Home app and perform expense reimbursement approval and report analysis work in Cloud Home, you can access the corresponding report content by configuring Cloud Home authentication.

The entry for the report is to create an app entry in Cloud Home. According to the integration API provided by Cloud Home, perform an SSO authentication, directly configure the report's URL address in the Cloud Home app, and open the report without logging in within the Cloud Home app.

Configuration Method:

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

  2. After becoming a system administrator, enter the light app management page through the Management Center -> App Center -> Light App Management.

  3. Select to create a new app, 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 added 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, the 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 of signing/encrypting user basic information according to the JWT specification and passing it to the server via URL when users access the system, balancing security and convenience.

Configuration related to JWT request parameter authentication includes:

  • JWT Token name.
  • Signature algorithm, consistent with HENGSHI configuration when the client signs.
  • Signature key, consistent with HENGSHI configuration when the signature algorithm is HS256. For RS256, the client uses the private key to sign, and the public key is filled in the HENGSHI configuration.
  • The signature key uses base64 decoding.
  • Decryption method, consistent with HENGSHI configuration when the client encrypts.
  • Decryption algorithm, consistent with HENGSHI configuration when the client encrypts.
  • Decryption key, the client uses the public key to encrypt, and the private key is filled in the HENGSHI 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, with the default role being data viewer.

JWT request parameters related reference materials.

Common configurations for JWT request parameters to synchronize 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 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.

Basic Format Explanation of JWT ​

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, as in the example where loginName=alice, if the loginName mapping configuration in HENGSHI is loginName, then alice will be used as the loginName in HENGSHI. For other references, see General Configuration.
Custom claims without mapping configurationNo mapping relationship configured in the HENGSHI systemHENGSHI will save this type of information in the user attributes, as in the example where abc=123, if 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 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 that can be added or modified as needed), and after base64URL encoding it is eyJzdWIiOiJhbGljZS1zdWJqZWN0IiwiYWJjIjoiMTIzIiwicm9sZXMiOlsic3lzdGVtIGFkbWluIiwiZGF0YSBhZG1pbiIsImRhdGEgYW5hbHlzdCIsImRhdGEgdmlld2VyIiwiYXBpIGFkbWluIl0sImxvZ2luTmFtZSI6ImFsaWNlIn0.
  3. The third part is the signature, obtained by concatenating the header of the first part with the payload of the second part, the information to be signed 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.

The above is a basic explanation of the JWT generation process. For more details and implementation libraries, you can further understand through 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 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, different tokens. The following token 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. 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, 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-free, and admin background login-free.

Feishu authentication-related configurations include:

Configure Lark Custom App ​

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

  2. Fill in the app name and app description.

  3. In the Enterprise Custom App list, click to enter the newly created app, 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 functions, web pages, fill in the desktop and mobile homepage. The specific address 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, user user ID, and user phone number are optional permissions. If not enabled, Lark will not return this information.

General Configuration ​

Some authentication methods (such as OAuth2, jwt-param, etc.) support mapping configurations for login names, emails, phone numbers, etc. Under these authentication methods with such configurations, these settings 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 in the system, requiring uniqueness across the system, with the purpose of automatically associating with the user upon each login.

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

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

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

  • Role Mapping: A field in the customer's system will be used as the role(s) the user possesses in the system, which can pass role IDs or role identifiers. 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 group(s) the user belongs to in the system, which can pass user group IDs or user group names.

  • 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.

Using 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, it 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#/
  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, simply configure the corresponding authentication method and select it.

iframe Embedding HENGSHI Pages Scenario ​

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 role 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 using HENGSHI SENSE's username and password for login, while the iframe uses the OAuth Server for seamless login.

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

    2.2 It is necessary to 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 HENGSHI Page Scenarios ​

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 self-built 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