---
url: /v6.2/auth-jwt-faq.md
---
# 认证与 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 最适合这类场景：

1. 你们自己的系统已经知道“当前登录用户是谁”
2. 希望把这个身份安全地带到 HENGSHI
3. 常见于嵌入、门户集成、SDK 集成，而不是让用户再单独走一遍 HENGSHI 登录页

典型入口长这样：

```text
?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 来配置登录后的默认角色，需要在配置文件里显式开启：

```properties
ENABLE_GROOVY_SCRIPT=true
```

配置后还需要重启服务生效。

## 认证集成时，怎么在“用哪种方式”之间快速判断？

可以先按这个思路分：

|诉求|更适合的方式|
|-|-|
|企业已经有标准认证中心，要走标准单点登录流程|LDAP / CAS / SAML2 / OAuth2|
|宿主系统已经完成登录，只想把当前用户身份带进嵌入页或 SDK|JWT 请求参数|
|只是为了管理员兜底或本地排障|HENGSHI 内置登录|

如果你本质上是在做嵌入集成，认证方案通常不该脱离嵌入入口一起讨论。

进一步阅读：

* [认证方式](authorization.md)
* [嵌入集成](embed-faq.md)
* [Copilot iframe SDK](copilot-sdk-iframe.md)
* [Copilot JS SDK](copilot-sdk-js.md)