认证与 JWT
认证相关问题很容易被混成一团：到底是登录打通没配好、认证方式选错了，还是 JWT 本身不适合当前场景。这页先把最常见的判断边界讲清楚。
HENGSHI 支持哪些认证方式？能同时支持多种吗？
支持，而且可以同时保留多种认证方式。
HENGSHI 除了内置登录外，还支持 LDAP、CAS、SAML2、OAuth2、JWT 请求参数，以及钉钉、企业微信、飞书等多种方式。实际访问时，可以通过 URL 参数选择希望激活的认证方式，例如：
?activeAuth=oauth2?activeAuth=jwt-param&jwtParam=...
这也是为什么很多集成场景里，系统可以同时给不同入口保留不同的登录方式，而不是“一改认证方式，所有入口都只能走同一种”。
外部认证配错了，已经登不上了怎么办？
先不要慌，系统管理员仍然可以回退到 HENGSHI 内置登录页修复配置。
直接访问：
http(s)://<hengshi-host>/#/login- 排障时也可以临时直接访问服务节点地址，例如
http://localhost:8080/#/login
如果前面还挂了反向代理，而你怀疑 Base URL 或代理本身也配错了，就优先直接绕过代理去服务地址排障。
什么时候更适合用 JWT 请求参数？
JWT 最适合这类场景：
- 你们自己的系统已经知道“当前登录用户是谁”
- 希望把这个身份安全地带到 HENGSHI
- 常见于嵌入、门户集成、SDK 集成，而不是让用户再单独走一遍 HENGSHI 登录页
典型入口长这样：
?activeAuth=jwt-param&jwtParam={签名或加密后的 JWT 字符串}如果你们的前端已经和 HENGSHI SDK 集成，也可以先通过 JWT 登录接口准备登录态，再加载页面或 SDK。
JWT 适合解决什么，不适合解决什么？
JWT 更适合解决**“外部系统已经认证完毕，把用户身份传进来”**的问题。
它不太适合拿来代替一整套完整的 SSO 平台能力，例如：
- 不负责外部登录页本身怎么做
- 不负责外部身份源的组织同步策略设计
- 不自动解决所有退出登录联动问题
如果你的真实诉求是“统一走企业级登录门户、统一登出、统一用户生命周期管理”，通常还是应该优先看 LDAP / CAS / SAML2 / OAuth2 这类标准认证方式。
配 JWT 时最容易漏掉什么？
最常漏的是签名、验签、加解密配置两边不一致。
重点包括：
- JWT Token 名称
- 验签算法
- 验签密钥
- 是否需要 base64 解码
- 加密 / 解密算法与密钥
如果客户端和 HENGSHI 两边算法或密钥不一致，就算 URL 格式看起来没问题，也不会认证成功。
JWT 里哪些字段最关键？
至少要重点确认：
sub：用户唯一标识的重要兜底字段exp：过期时间，过期后 token 无效- 你在 HENGSHI 里做了映射的自定义声明，例如
loginName、email、roles
如果某个声明配置了映射，HENGSHI 会把它写入对应用户字段；没有映射的声明，则会作为用户属性保存。
所以很多“JWT 登录成功了，但用户属性没同步对”的问题，本质上不是 token 没传过来，而是映射关系没有配对。
JWT 里的 Groovy script 是默认可用的吗？
不是。
从 5.1 开始，出于安全考虑，页面上填写的 Groovy script 默认关闭。如果你确实需要通过 JWT 里的 Groovy script 来配置登录后的默认角色，需要在配置文件里显式开启：
ENABLE_GROOVY_SCRIPT=true配置后还需要重启服务生效。
认证集成时，怎么在“用哪种方式”之间快速判断？
可以先按这个思路分：
| 诉求 | 更适合的方式 |
|---|---|
| 企业已经有标准认证中心，要走标准单点登录流程 | LDAP / CAS / SAML2 / OAuth2 |
| 宿主系统已经完成登录，只想把当前用户身份带进嵌入页或 SDK | JWT 请求参数 |
| 只是为了管理员兜底或本地排障 | HENGSHI 内置登录 |
如果你本质上是在做嵌入集成，认证方案通常不该脱离嵌入入口一起讨论。
进一步阅读：