DM-ROW 接口文档

Appearance

安全认证 ​

**本文引用的文件** - [LemesAuthApplication.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/LemesAuthApplication.java) - [AuthorizationServerConfig.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/config/AuthorizationServerConfig.java) - [SysLoginController.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/controller/SysLoginController.java) - [PasswordAuthenticationProvider.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/password/PasswordAuthenticationProvider.java) - [CustomUserDetailsServiceImpl.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/CustomUserDetailsServiceImpl.java) - [bootstrap.yml](file://lemes-cloud/lemes-auth/src/main/resources/bootstrap.yml) - [OauthCliendetails.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/tools/entity/auth/OauthCliendetails.java) - [auth.yaml](file://lemes-cloud/src/devops/k8s/service/base/auth.yaml) - [lemes-auth.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-auth.yaml)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件面向安全工程师与系统管理员，系统性梳理 DeviceMate 项目的安全认证体系，覆盖 JWT 令牌管理（通过 OAuth2 授权服务器发放访问令牌与刷新令牌）、OAuth2 集成（密码模式、客户端凭证模式等）与权限控制策略。文档解释用户认证流程、角色权限模型与资源访问控制机制，并阐述密码加密策略、会话管理与安全日志记录。同时提供安全配置最佳实践、漏洞防护与合规建议，以及 API 安全防护、数据传输加密与敏感信息保护方案。

项目结构 ​

DeviceMate 的认证子系统位于 lemes-cloud/lemes-auth 模块，采用 Spring Boot + Spring Security + Spring Authorization Server 构建，提供 OAuth2 授权服务器能力与统一认证入口。前端通过终端标识区分不同客户端，后端根据配置生成访问令牌与刷新令牌，并支持注销与刷新操作。

图表来源

章节来源

核心组件 ​

  • 授权服务器配置：集中定义 OAuth2 授权端点、令牌端点、资源服务器、CSRF 关闭、跨域放行路径等。
  • 登录控制器：提供密码登录、注销、刷新令牌接口；按终端区分客户端并支持多终端共享登录策略。
  • 密码认证提供者：实现 OAuth2 密码模式认证，校验客户端授权类型与作用域，生成访问令牌与刷新令牌。
  • 用户详情服务：通过远程调用加载用户信息、菜单、权限等，构建 Spring Security 用户主体。
  • 运行时配置：定义 Nacos 注册发现、令牌有效期、管理端点暴露、日志配置等。

章节来源

架构总览 ​

下图展示从客户端到授权服务器再到资源服务器的整体认证与授权流程，包括令牌发放、刷新与注销的关键步骤。

图表来源

详细组件分析 ​

授权服务器配置 ​

  • 授权端点与令牌端点：启用自定义转换器链，支持授权码、密码、客户端凭证、刷新令牌等多种模式；设置认证成功/失败处理器。
  • 资源服务器：使用不透明令牌（Opaque Token）自省，配置访问拒绝与未认证入口。
  • 安全过滤：关闭 CSRF，允许内联框架，按白名单放行部分路径。
  • 令牌生成：委托式生成器组合访问令牌与刷新令牌生成器，并注入自定义令牌增强器。
  • 密码编码：BCrypt 编码器用于密码存储与比对。

图表来源

章节来源

登录与会话管理 ​

  • 密码登录：根据终端标识选择客户端配置，支持“同账号多地登录”策略；若存在有效授权则直接返回现有令牌，否则调用授权服务器换取新令牌。
  • 注销：解析访问令牌，查询授权记录并删除，实现即时失效。
  • 刷新：校验刷新令牌有效性，调用授权服务器换取新令牌并对旧刷新令牌进行清理。

图表来源

章节来源

密码认证提供者 ​

  • 客户端校验：确保客户端已认证且支持当前授权模式。
  • 作用域校验：仅允许在客户端授权范围内申请作用域。
  • 用户认证：委派给 AuthenticationManager 进行用户名/密码校验。
  • 令牌生成：生成访问令牌与可选刷新令牌，保存授权记录并返回认证结果。

图表来源

章节来源

用户详情与权限模型 ​

  • 用户详情加载：通过远程客户端调用用户服务，返回包含菜单、权限列表、部门、上级等信息的用户详情对象。
  • 权限授予：基于用户权限字符串数组构建 Authority 列表，供 Spring Security 使用。
  • 角色/权限映射：权限字符串通常映射为细粒度的访问控制项，结合资源服务器的自省与拦截器实现资源级授权。

图表来源

章节来源

客户端与令牌配置 ​

  • 终端区分：通过请求头中的终端标识选择对应客户端配置，支持不同令牌有效期与共享策略。
  • 令牌有效期：访问令牌与刷新令牌的有效期在配置中定义，支持按客户端维度调整。
  • 共享登录：当客户端配置允许共享登录或特殊用户例外时，为每个会话生成唯一客户端 ID，避免互相影响。

章节来源

客户端实体与配置 ​

  • 客户端实体：包含客户端 ID、密钥、是否共享登录等字段，用于授权服务器侧的客户端校验与令牌发放策略。
  • 与认证服务集成：认证服务通过该实体读取客户端属性，决定令牌有效期与共享策略。

章节来源

依赖分析 ​

  • 应用入口：启用服务发现与 Feign 客户端，默认扫描 com.lenovo.lemes 包。
  • 授权服务器：集中配置安全过滤链、令牌端点转换器、认证提供者与资源服务器。
  • 控制器：依赖授权服务与远程用户服务，协调令牌发放、刷新与注销。
  • 配置：Nacos 注册发现、令牌有效期、管理端点暴露、日志级别等。

图表来源

章节来源

性能考虑 ​

  • 令牌生成与存储：访问令牌与刷新令牌生成采用委托式生成器，建议在高并发场景下评估令牌生成成本与存储压力。
  • 用户详情远程调用：用户详情加载依赖远程调用，应关注延迟与重试策略，必要时引入本地缓存。
  • 作用域与客户端校验：在认证阶段严格校验作用域与客户端授权类型，避免无效请求进入后续流程。
  • 日志与监控：合理设置日志级别，避免在生产环境输出敏感信息；结合指标监控令牌发放与认证成功率。

故障排查指南 ​

  • 认证失败：检查用户名/密码是否正确，确认客户端是否支持密码模式与授权范围。
  • 令牌无效：确认访问令牌是否过期或被注销，检查资源服务器自省配置与令牌存储状态。
  • 刷新失败：确认刷新令牌是否有效且未被清理，核对客户端密钥与端点请求头格式。
  • 注销异常：确认传入的访问令牌格式正确，授权记录是否存在且可删除。
  • 配置问题：核对 Nacos 配置、端口暴露与 Kubernetes 服务定义，确保认证服务可被网关与前端访问。

章节来源

结论 ​

DeviceMate 的认证体系以 Spring Authorization Server 为核心，结合自定义令牌生成器与认证提供者，实现了灵活的 OAuth2 授权与令牌管理。通过终端区分客户端配置、密码模式认证与资源服务器自省，系统在保证安全性的同时兼顾了易用性与可扩展性。建议在生产环境中强化日志脱敏、令牌存储安全与网络隔离，并持续优化远程调用性能与监控告警。

附录 ​

安全配置最佳实践 ​

  • 传输安全：强制使用 HTTPS，禁用明文传输；在网关层统一终止 TLS 并向后端转发。
  • 令牌安全：短令牌有效期与定期刷新；刷新令牌仅在必要时发放；注销后立即失效。
  • 密码策略：使用强哈希算法（如 BCrypt）存储密码；限制登录尝试次数与速率。
  • 权限最小化：基于作用域与权限字符串进行资源级授权；避免过度授权。
  • 配置安全：密钥与证书集中管理；避免硬编码敏感信息；启用配置加密。

漏洞防护与合规 ​

  • OWASP Top 10：输入验证、注入防护、会话固定、敏感数据泄露、安全配置错误。
  • 合规要求：遵循所在区域的数据保护法规（如 GDPR、网络安全法），实施数据生命周期管理与审计日志。

API 安全防护要点 ​

  • 身份认证：统一使用 OAuth2 Bearer 令牌；禁止在 URL 或 Cookie 中传递令牌。
  • 授权控制：基于角色/权限的细粒度访问控制；资源服务器自省与拦截器配合。
  • 请求限制：速率限制、配额控制与熔断降级；防止暴力破解与滥用。
  • 审计日志：记录关键操作（登录、注销、令牌刷新、权限变更）与异常事件。

数据传输加密与敏感信息保护 ​

  • 传输加密：TLS 1.2+，禁用弱密码套件；证书自动续期与轮换。
  • 存储加密：令牌与会话信息在存储层加密；密钥轮换与访问控制。
  • 敏感信息：日志脱敏、参数过滤与最小披露原则；避免在日志中输出密码、令牌与密钥。