Hadess实战：集成企业微信实现统一认证登录

1. 项目概述：为什么我们需要Hadess与企业微信的集成？

如果你在一家规模稍大的公司待过，或者负责过内部系统的运维，大概率对“账号密码满天飞”的场景深有体会。财务系统一套账号、CRM系统一套账号、内部Wiki又是一套，员工入职要开一堆账户，离职了还得一个个去禁用，繁琐不说，安全风险也高。统一身份认证（SSO）就是来解决这个痛点的，它让你用一个账号（通常是公司主账号）就能登录所有授权应用。

而企业微信，作为国内企业办公的“国民级”应用，几乎成了员工数字身份的入口。它的通讯录天然就是企业的组织架构。如果能将内部自研或第三方系统的登录认证，与企业微信的账号体系打通，无疑是性价比最高、用户体验最好的方案之一。员工无需记忆新密码，扫码或一键即可登录，管理员也能在企业微信后台统一管理账号的生命周期。

Hadess正是在这个背景下进入我们视野的。它不是一个大众熟知的开源项目，但在特定的技术圈子里，它被看作是一个轻量、灵活、可插拔的统一认证与权限管理中间件。你可以把它理解为一个“认证路由中心”。它的核心价值在于，通过简单的配置和适配，能将各种后端应用（如OA、CRM、知识库）的登录请求，转发到像企业微信、钉钉、LDAP、CAS这样的标准认证源进行校验，并在认证成功后，将用户身份信息安全地传递给业务系统。

所以，“Hadess实战教程 - 支持企业微信集成，实现统一认证登录”这个标题，瞄准的就是那些希望快速、低成本为内部系统接入企业微信扫码登录，但又不想深陷企业微信API开发细节的开发和运维工程师。接下来，我将以一个完整的实战项目为例，拆解从零开始，利用Hadess搭建一个支持企业微信扫码登录的统一认证门户的全过程。

2. 核心架构与方案选型背后的思考

在动手之前，我们先厘清几个关键概念和为什么这么选。这能帮你避开后期很多坑。

2.1 Hadess、OAuth 2.0与企业微信扫码登录的关系

首先，企业微信提供的是一种标准的OAuth 2.0授权流程。简单来说，OAuth 2.0是一种授权协议，允许用户授权第三方应用（在这里就是我们的业务系统）获取其在企业微信中的基本信息，而无需提供密码。

那么Hadess扮演什么角色？它扮演了“第三方应用”和“认证服务器”之间的代理与适配层。对于你的业务系统（比如一个内部的报表平台）来说，它只需要和Hadess对接，使用Hadess提供的简单登录接口。而Hadess则负责：

1. 引导用户跳转到企业微信的官方登录页。
2. 处理企业微信回调的授权码（code）。
3. 用授权码向企业微信换取用户身份信息（access_token和userid）。
4. 将企业微信返回的原始用户信息，转换成业务系统能识别的格式（比如JWT Token或简单的用户ID），再返回给业务系统。

这样做的好处是解耦。你的业务系统不需要关心企业微信的API如何调用、参数如何组装、回调地址如何配置这些繁琐且易变的细节。所有与认证协议相关的复杂性都被封装在Hadess中。未来如果你想增加钉钉登录、飞书登录，只需要在Hadess中新增一个配置，业务系统代码几乎无需改动。

2.2 环境与工具准备清单

工欲善其事，必先利其器。以下是本次实战所需的核心组件，我会解释每一项的必要性。

1. Hadess服务端：我们将从官方Git仓库获取最新稳定版的发行包（通常是JAR文件）。选择JAR包而非源码编译，是为了快速部署。Hadess基于Java开发，因此需要JDK 8或11环境。我推荐使用OpenJDK 11，它在性能和兼容性上比较均衡。
2. 企业微信管理后台：这是配置的源头。你需要拥有一个企业微信的企业账号，并且有管理员权限，以便创建应用、配置可信域名、获取关键密钥。
3. 一台具有公网IP或域名的服务器：这是最关键也是最容易出错的一环。企业微信的回调（redirect_uri）要求必须是备案过的域名，且支持HTTPS。对于开发和测试，你有两个选择：
   • 方案A（推荐用于测试）：使用内网穿透工具（如ngrok、frp）将你本地开发机的服务临时映射到一个公网HTTPS域名。ngrok会提供一个随机的xxx.ngrok.io域名，自带HTTPS，非常适合调试OAuth回调。
   • 方案B（生产环境）：使用云服务器，配置你自己的域名并申请SSL证书（Let‘s Encrypt免费证书即可）。
4. 配置文件：Hadess的核心是一个application.yml（或application.properties）文件，所有与企业微信的集成配置都在这里。
5. 一个用于测试的简单Web应用：为了演示完整流程，我们需要一个最简化的业务系统。我用一个Spring Boot写的、只有一个页面的应用来演示，它只做一件事：从Hadess获取用户信息并显示。

注意：很多人在第一步就卡住了，因为他们试图在纯本地环境（localhost）下调试企业微信登录，这是行不通的。企业微信的安全策略强制要求回调地址为公网可访问的HTTPS域名。请务必提前准备好方案A或B。

3. 企业微信侧关键配置详解

登录企业微信管理后台（https://work.weixin.qq.com），这是所有配置的起点。很多参数配置错误，会导致后续流程完全走不通。

3.1 自建应用的创建与基础信息获取

进入“应用管理” -> “自建应用” -> “创建应用”。创建一个用于测试的应用，比如叫“Hadess统一认证测试”。

创建成功后，进入应用详情页，你需要记录下三个核心参数，它们相当于这个应用的“身份证”：

• AgentId （应用ID/AgentId）：每个应用唯一的编号。在后续的OAuth请求中，它用于指定用户要登录哪个应用。
• CorpId （企业ID）：你所在公司的唯一标识。所有应用共享同一个CorpId。
• Secret （应用密钥）：这是最重要的敏感信息，相当于应用的密码。用于在后台接口调用时验证身份。务必妥善保管，不要泄露到前端代码或Git仓库中。

3.2 配置“企业微信授权登录”与可信域名

这是打通登录流程的最关键配置。在应用详情页，找到“开发者接口”栏目下的“企业微信授权登录”。

1. 设置授权回调域：点击“设置授权回调域”。这里填写的，是你运行Hadess服务的域名（不需要带http://或https://，也不需要路径）。例如，如果你用ngrok，地址是https://abc123.ngrok.io，那么这里就填写abc123.ngrok.io。这个配置告诉企业微信：“我只接受来自这个域名的回调请求，其他来源的一律拒绝。” 所以，如果你的Hadess服务最终部署的域名变了，这里必须同步更新。
2. 配置网页授权可信域名（如果需要）：如果你集成的业务系统是网页版，并且需要在网页内使用JS-SDK（如分享、拍照等），还需要配置“网页授权可信域名”。对于单纯的扫码登录，第一步的授权回调域已经足够。

实操心得：经常有同学反馈“扫码后提示redirect_uri参数错误”。90%的原因出在这里。请仔细核对：

• 回调域配置的域名，是否与Hadess服务实际可被公网访问的域名完全一致（包括子域名）？
• Hadess服务配置的回调地址路径（如/hadess/auth/callback），是否拼接在域名之后，构成了一个完整的、可访问的URL？
• 该URL是否已经正确填写到Hadess的配置文件中？

4. Hadess服务部署与核心配置解析

拿到企业微信的参数后，我们来部署和配置Hadess。

4.1 服务启动与基础配置

假设你已经下载了hadess-boot-2.x.x.jar。我们可以通过一个简单的命令启动它，并指定配置文件：

java -jar hadess-boot-2.x.x.jar --spring.config.location=application.yml

现在来看application.yml的核心内容。一个最小化的、针对企业微信的配置如下：

server: port: 8080 # Hadess服务本身运行的端口 servlet: context-path: /hadess # 建议给Hadess加个上下文路径，避免与业务系统冲突 hadess: auth: # 认证提供者列表，这里我们配置企业微信 providers: wecom: # 提供一个自定义的key，比如‘wecom’，在登录时会用到 type: wechat_enterprise # 指定类型为企业微信 enabled: true client-id: ${WECOM_CORP_ID} # 替换为你的企业CorpId client-secret: ${WECOM_AGENT_SECRET} # 替换为你的应用Secret agent-id: ${WECOM_AGENT_ID} # 替换为你的应用AgentId redirect-uri: https://your-public-domain.com/hadess/auth/callback/wecom # 重点！这个redirect-uri必须和企业微信后台配置的回调域名匹配，且路径是Hadess定义的回调端点 scopes: # 申请的权限范围 - userinfo # 用户信息映射：将企业微信返回的字段，映射到Hadess统一的用户模型 attribute-mapping: userId: userid # 企业微信返回的userid，映射到userId属性 name: name avatar: avatar mobile: mobile email: email # 会话与Token配置（简化示例） session: store-type: jwt # 使用JWT作为无状态会话凭证，适合分布式部署 jwt: secret: your-very-strong-jwt-secret-key-here # 必须改为强密钥 expiration: 7200 # token有效期2小时

关键点解析：

• redirect-uri：这个URL是用户在企业微信授权后，企业微信服务器将浏览器重定向回来的地址。它必须精确匹配你在企业微信后台配置的“授权回调域”所衍生的完整地址。格式为：https://[你的域名]/[hadess上下文路径]/auth/callback/[provider-key]。Hadess内置了/auth/callback/{provider}这个端点来处理回调。
• attribute-mapping：这是Hadess非常实用的一个功能。不同认证源返回的用户信息格式千差万别。通过这个映射，你可以将它们统一成userId，name等标准字段。业务系统只需要从Hadess获取这些标准字段，无需关心底层是企业微信还是钉钉。
• client-secret等敏感信息：强烈建议不要明文写在配置文件中。如上例所示，使用${}占位符，通过环境变量（WECOM_CORP_ID）或配置中心来注入，提升安全性。

4.2 登录流程的端点与交互

配置完成后，Hadess会提供几个标准的HTTP端点：

1. 发起登录：GET /hadess/auth/authorize/wecom。当你的业务系统需要登录时，只需将用户引导至这个地址。Hadess会自动构建正确的参数，并将用户重定向到企业微信的官方扫码/登录页面。
2. 处理回调：POST /hadess/auth/callback/wecom。这个端点由Hadess内部处理，开发者无需干预。它负责接收企业微信传来的code，并用code、secret等去换取用户信息。
3. 获取当前用户信息：GET /hadess/auth/userinfo。在用户通过Hadess登录成功后，业务系统可以携带Hadess颁发的会话Cookie或JWT Token（根据配置）来调用这个接口，获取统一的用户信息（即attribute-mapping映射后的结果）。
4. 退出登录：GET /hadess/auth/logout。用于销毁Hadess侧的会话。

整个流程对于业务系统来说，变得极其简单：跳转到Hadess登录地址 -> 等待回调（业务系统无需处理）-> 从Hadess获取用户信息。

5. 业务系统（客户端）集成实战

现在，我们从一个业务系统（客户端）的角度，看看如何与Hadess对接。假设我们有一个简单的内部报表系统，地址是https://report.internal.com。

5.1 前端登录跳转与状态检查

在你的报表系统登录页，放置一个“企业微信扫码登录”的按钮。这个按钮的点击事件，就是跳转到Hadess的授权端点。

<!-- 报表系统登录页 login.html --> <button onclick="loginWithWeCom()">企业微信扫码登录</button> <script> function loginWithWeCom() { // 构建Hadess的授权URL，其中‘wecom’是我们在Hadess配置中定义的provider key const hadessAuthUrl = 'https://hadess.yourcompany.com/hadess/auth/authorize/wecom'; // 可以附加一个‘redirect_uri’参数，告诉Hadess登录成功后跳转回报表系统的哪个页面 const returnTo = encodeURIComponent('https://report.internal.com/dashboard'); window.location.href = `${hadessAuthUrl}?redirect_uri=${returnTo}`; } </script>

用户点击后，页面跳转到Hadess，Hadess再跳转到企业微信。用户扫码授权后，企业微信回调到Hadess，Hadess处理完毕，最终将用户重定向回你指定的returnTo地址（例如报表系统首页）。

5.2 后端会话校验与用户信息获取

用户被重定向回你的报表系统（https://report.internal.com/dashboard）时，如何知道他已经登录了呢？关键在于Hadess会在同一个浏览器上下文中设置一个会话Cookie（如果使用Session管理）或通过URL Fragment传递一个JWT Token（如果使用JWT）。

方案一：Cookie/Session方案（适用于Hadess与业务系统同域或已处理跨域）如果Hadess服务（hadess.yourcompany.com）和你的报表系统（report.internal.com）在主域上可以设置成相同（如通过Nginx代理到同一域下），那么Hadess设置的会话Cookie可以被报表系统读到。报表系统的后端只需要在用户访问时，携带这个Cookie去调用Hadess的/auth/userinfo接口。

// 报表系统后端（Spring Boot示例）的一个拦截器或Controller方法中 @GetMapping("/dashboard") public String dashboard(HttpServletRequest request, HttpServletResponse response) { // 1. 从请求中获取Hadess的会话Cookie (假设Cookie名为 HADESS_SESSION) String sessionId = getCookieValue(request, "HADESS_SESSION"); if (sessionId == null) { // 没有会话，重定向到登录 return "redirect:/login"; } // 2. 调用Hadess的用户信息接口（内部网络调用，可走HTTP） RestTemplate restTemplate = new RestTemplate(); HttpHeaders headers = new HttpHeaders(); headers.add("Cookie", "HADESS_SESSION=" + sessionId); // 将会话Cookie传给Hadess HttpEntity<?> entity = new HttpEntity<>(headers); try { ResponseEntity<Map> userInfoResponse = restTemplate.exchange( "https://hadess.yourcompany.com/hadess/auth/userinfo", HttpMethod.GET, entity, Map.class ); Map<String, Object> userInfo = userInfoResponse.getBody(); // 3. 将用户信息（如userId, name）存入当前系统的会话中 request.getSession().setAttribute("currentUser", userInfo); return "dashboard"; } catch (HttpClientErrorException e) { // 4. 如果Hadess返回401等错误，说明会话无效，清理本地并重定向登录 return "redirect:/login"; } }

方案二：JWT Token方案（更通用，适合跨域）如果在Hadess中配置了JWT，流程会略有不同。Hadess在认证成功后，可以将JWT Token作为参数附加在重定向回业务系统的URL上（例如https://report.internal.com/dashboard#token=eyJhbGciOi...）。业务系统的前端JavaScript需要解析这个Token（例如从URL的hash中获取），然后将其存储在本地（如LocalStorage），并在后续每次调用业务系统API时，放在Authorization请求头中（Bearer <token>）。业务系统的后端则需要验证这个JWT Token的签名和有效性。

注意事项：JWT方案虽然无状态、易扩展，但需要业务系统后端具备验证JWT的能力（知道Hadess用于签名的secret）。同时，要妥善处理Token的存储与传输安全，防止XSS攻击导致Token泄露。

5.3 用户身份同步与本地账号处理

第一次通过Hadess登录的用户，在企业微信侧有身份，但在你的报表系统数据库里可能还没有对应的本地账号。这里需要一个简单的“首次登录同步”逻辑。

当你的后端从Hadess拿到用户信息（主要是userId，即企业微信的userid）后，去本地用户表查询。如果不存在，则有两种策略：

1. 自动创建：根据从Hadess获取的姓名、部门等信息，自动在本地创建一个禁用状态或基础权限的账号。适用于对账号信息要求不高的内部工具。
2. 引导补充：跳转到一个“信息补全”页面，让用户确认或补充必要信息（如工号、所属团队等），然后再创建本地账号。适用于需要更丰富用户属性的系统。

无论哪种方式，建议将企业微信的userid作为唯一关联标识存储在本地用户表中，这样下次登录时就能直接匹配。

6. 生产环境部署、安全与高可用考量

将这套方案用于生产环境，除了功能跑通，还需要考虑更多。

6.1 网络与域名架构建议

一个清晰、安全的网络架构能减少很多麻烦。推荐以下部署模式：

用户浏览器 | | (HTTPS) v [ 互联网 ] ----> [ 负载均衡器 (Nginx/云LB) ] | | (内部HTTP/HTTPS) v -------------------------- | | v v [ 业务系统集群 ] [ Hadess认证集群 ] (report.yourcompany.com) (auth.yourcompany.com)

• 使用统一的父域名：例如，Hadess服务部署在auth.yourcompany.com，各个业务系统使用子域，如report.yourcompany.com,wiki.yourcompany.com。这有助于Cookie在子域之间共享（如果采用Cookie方案），简化配置。
• 负载均衡与SSL终结：在入口处使用Nginx或云负载均衡器，统一处理SSL证书、流量分发和静态资源。Hadess服务和各个业务系统部署在内部网络，通过负载均衡器暴露。
• 配置企业微信回调地址：在企业微信后台，授权回调域填写auth.yourcompany.com。这样，所有通过这个认证门户的登录请求都是合法的。

6.2 安全加固配置清单

安全无小事，尤其是认证系统。

1. HTTPS everywhere：确保从外网到负载均衡器，再到内部服务间的通信，全部使用HTTPS。特别是Hadess与企业微信、Hadess与业务系统之间的回调。
2. 敏感信息管理：绝对不要将CorpSecret等硬编码在代码或配置文件中。使用环境变量、云厂商的密钥管理服务（如KMS）或专业的配置中心（如Apollo, Nacos）来管理。
3. Hadess自身安全：
   • 修改默认密钥：JWT的签名密钥、Cookie的加密密钥等，必须使用强随机字符串替换默认值。
   • 控制管理端点：如果Hadess有管理API，确保其访问IP受到严格限制，或通过额外的认证保护。
   • 日志与审计：开启Hadess的访问日志和审计日志，记录所有登录成功/失败事件，便于事后追溯。
4. 防CSRF与重放攻击：确保业务系统在涉及敏感操作时，有自己的CSRF Token机制。OAuth 2.0流程中的state参数由Hadess生成和验证，可以有效防止CSRF，但业务系统自身的表单仍需保护。
5. 权限最小化：在企业微信后台创建应用时，只申请必要的API权限（如“读取通讯录”可能只需要“获取成员基本信息”的权限，而非全部）。

6.3 监控、日志与故障排查指南

系统上线后，可观测性至关重要。

• 监控指标：
  • Hadess服务的存活状态（HTTP健康检查端点）。
  • 登录请求的QPS、成功率、平均响应时间。
  • 企业微信API调用的失败率（可能预示Secret过期或网络问题）。
• 关键日志：在Hadess的配置中，调高认证相关日志的级别（如DEBUG），以便在出现问题时，能清晰看到OAuth流程走到了哪一步，参数是什么，错误信息是什么。
• 常见故障排查树：
  • 扫码后提示“redirect_uri参数错误”：
    • [ ] 检查企业微信后台“授权回调域”配置的域名，是否与Hadess配置文件中redirect-uri的域名部分完全一致（注意http/https、www非www）。
    • [ ] 检查redirect-uri的完整URL是否可被公网访问。
    • [ ] 检查Hadess服务启动时，配置文件中的redirect-uri参数是否正确加载。
  • 扫码授权后，页面白屏或报错“无效的code”：
    • [ ] 检查Hadess日志，看是否成功用code换取了access_token。失败可能因为：1)CorpSecret错误或已重置；2) 网络问题导致调用企业微信API超时；3) code被重复使用或已过期。
    • [ ] 检查Hadess服务的时间是否与标准时间同步（NTP）。时间偏差过大可能导致签名错误。
  • 业务系统调用/auth/userinfo返回401：
    • [ ] 检查浏览器到业务系统，再到Hadess的请求链路中，会话Cookie或JWT Token是否成功携带。
    • [ ] 检查Hadess的会话存储（如Redis）是否正常，会话是否已过期。
    • [ ] 如果是JWT，检查业务系统验证JWT时使用的secret是否与Hadess签发的secret一致。

7. 扩展思考：从单点登录到统一权限管理

Hadess解决了“你是谁”（认证）的问题，但企业内通常还有“你能做什么”（授权）的问题。将Hadess作为统一认证中心后，可以很自然地将其扩展为权限控制的基石。

思路一：集成RBAC模型在Hadess中，或者在其关联的数据库中，可以建立角色（Role）和权限（Permission）表。当从企业微信获取到用户信息（特别是部门信息department）后，可以根据预设的规则（如“部门ID为5的成员自动拥有‘财务角色’”），在登录过程中为用户分配角色。然后，Hadess在颁发给业务系统的用户信息中，不仅包含userId和name，还可以包含一个roles或permissions的列表字段。

业务系统收到这个列表后，就可以在自己的拦截器或注解中，进行界面元素和API接口的权限控制了。这样，权限的集中管理就在Hadess层面完成，各业务系统无需重复维护一套复杂的权限逻辑。

思路二：作为API网关的认证前置在微服务架构下，你可以将Hadess部署在API网关（如Spring Cloud Gateway, Kong）之后。所有到达业务API的请求，先经过网关，网关调用Hadess的一个轻量级验证端点（例如/auth/verify）来校验请求中的Token是否有效。无效则直接返回401，有效则网关将解析出的用户信息（如userId）以HTTP头（如X-User-Id）的形式转发给下游业务服务。这样，每个业务服务就完全无需处理认证逻辑，只需关心收到的请求头中的用户身份即可。

踩坑心得：在扩展权限时，切忌一开始就设计得过于复杂。建议从最简单的“基于部门的角色映射”开始，跑通流程。权限数据的变化频率远低于认证，要考虑到数据同步的延迟问题。例如，一个员工刚调换了部门，他在企业微信中的信息已经更新，但Hadess中的角色映射可能有一个缓存周期（比如5分钟）。在这5分钟内，他访问系统可能还是旧部门的权限。你需要根据业务对实时性的要求，来设计缓存策略和同步机制。