Authentication and JWT
Authentication problems get mixed together very easily: is login integration misconfigured, was the wrong auth method chosen, or is JWT simply the wrong fit for the scenario? This page separates those boundaries first.
Which authentication methods does HENGSHI support? Can multiple methods coexist?
Yes. Multiple authentication methods can coexist.
Besides the built-in login, HENGSHI supports LDAP, CAS, SAML2, OAuth2, JWT request parameters, and methods such as DingTalk, WeChat Work, and Feishu. In practice, the URL can activate the desired auth method, for example:
?activeAuth=oauth2?activeAuth=jwt-param&jwtParam=...
That is why many integration projects can keep different login paths for different entry points instead of forcing every entry to use only one global auth path.
What if external authentication is misconfigured and nobody can log in?
Do not panic. System administrators can still fall back to the built-in HENGSHI login page to repair the configuration.
Go directly to:
http(s)://<hengshi-host>/#/login- or, while troubleshooting, access the service node directly such as
http://localhost:8080/#/login
If a reverse proxy is also in the path and you suspect Base URL or proxy configuration is part of the problem, bypass the proxy first and recover access through the service address.
When is JWT request-parameter auth the right choice?
JWT is best when:
- Your own system already knows who the current user is
- You want to carry that identity into HENGSHI securely
- The scenario is usually embedding, portal integration, or SDK integration rather than asking the user to go through a separate HENGSHI login flow
A typical entry looks like:
?activeAuth=jwt-param&jwtParam={signed or encrypted JWT string}If your frontend already integrates with the HENGSHI SDK, you can also prepare login state through the JWT login API before loading the page or SDK.
What is JWT good at, and what is it not good at?
JWT is good at "the external system has already authenticated the user, and now needs to pass that identity into HENGSHI."
It is not a full replacement for an enterprise SSO platform. For example, it does not automatically solve:
- how the external login page itself should work
- how identity-source sync should be designed end to end
- every logout-linkage requirement
If your real requirement is "unified enterprise login portal, unified logout, unified user lifecycle management," standard methods such as LDAP, CAS, SAML2, or OAuth2 are usually a better fit.
What is most often missed when configuring JWT?
The most common miss is that signing, verification, encryption, and decryption settings do not match on both sides.
The key items are:
- JWT token name
- verification algorithm
- verification key
- whether Base64 decoding is expected
- encryption/decryption algorithms and keys
If the client side and HENGSHI side do not match, the URL may look correct but authentication will still fail.
Which JWT fields matter most?
At minimum, pay close attention to:
sub: an important fallback unique identifierexp: expiration time; once expired, the token is invalid- mapped custom claims such as
loginName,email, androles
If a claim is mapped in HENGSHI, it is written into the corresponding user field. If a claim is not mapped, it is stored as user attributes instead.
So many "JWT login succeeds but user attributes look wrong" cases are really mapping problems, not transport problems.
Is Groovy script in JWT auth enabled by default?
No.
Since 5.1, page-level Groovy script is disabled by default for security reasons. If you truly need JWT Groovy script to set default roles after login, enable it explicitly in the configuration:
ENABLE_GROOVY_SCRIPT=trueA service restart is required after the change.
How do I choose the right auth method quickly?
A practical shortcut:
| Requirement | Better fit |
|---|---|
| The enterprise already has a standard identity center and wants standard SSO | LDAP / CAS / SAML2 / OAuth2 |
| The host system already authenticated the user and only needs to pass identity into the embedded page or SDK | JWT request parameters |
| You need an admin fallback path or local troubleshooting entry | Built-in HENGSHI login |
If the real problem is part of embedding integration, the auth decision usually should not be discussed separately from the embed entry path.
Further reading: