DM-ROW 接口文档

Appearance

认证授权体系 ​

**本文引用的文件** - [SecurityConfig.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/config/SecurityConfig.java) - [CustomUserDetailsServiceImpl.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/CustomUserDetailsServiceImpl.java) - [PasswordAuthenticationConverter.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/password/PasswordAuthenticationConverter.java) - [PasswordAuthenticationProvider.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/password/PasswordAuthenticationProvider.java) - [PasswordDaoAuthenticationProvider.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/password/PasswordDaoAuthenticationProvider.java) - [CustomAuthenticationSuccessHandler.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/handler/CustomAuthenticationSuccessHandler.java) - [CustomeAuthenticationFailureHandler.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/handler/CustomeAuthenticationFailureHandler.java) - [CustomOAuth2AccessTokenGenerator.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/CustomOAuth2AccessTokenGenerator.java) - [CustomOAuth2RefreshTokenGenerator.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/CustomOAuth2RefreshTokenGenerator.java) - [CustomOAuth2TokenCustomizer.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/CustomOAuth2TokenCustomizer.java)

目录 ​

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

引言 ​

本文件系统化梳理 DeviceMate 项目的认证授权体系，围绕 Spring Security 与 Spring Authorization Server 的集成进行深入解析。内容涵盖：

  • 自定义密码认证提供者与转换器
  • 用户详情服务实现与密码校验策略
  • OAuth2 授权服务器配置要点（授权码、客户端凭证、密码模式）
  • JWT 令牌生成与定制机制（访问令牌与刷新令牌）
  • 认证拦截器、异常处理与成功/失败回调
  • 密码安全策略（加密存储、强度与历史）

目标是帮助开发者快速理解并正确扩展认证授权能力。

项目结构 ​

DeviceMate 的认证授权主要集中在 lemes-cloud 子模块中，其中：

  • 认证授权核心实现位于 lemes-cloud/lemes-auth
  • 业务侧安全配置位于各业务模块的 common-server 中
  • 用户详情服务通过 Feign 调用系统用户服务获取用户信息

图表来源

章节来源

核心组件 ​

  • 忽略路径配置：集中管理无需鉴权的接口白名单，便于统一放行静态资源与公开接口。
  • 用户详情服务：从系统用户服务拉取用户信息，构建 Spring Security 的 UserDetails，并注入菜单、权限等上下文。
  • 密码模式转换器与提供者：负责将表单参数转换为认证对象，并完成客户端认证、作用域校验、用户名密码校验与令牌签发。
  • DAO 密码提供者：覆盖密码匹配逻辑，使用工具类进行比对。
  • 令牌生成与定制：访问令牌采用引用型格式并携带自定义声明；刷新令牌按客户端配置生成；令牌定制器注入用户权限、用户标识与用户名。
  • 成功/失败回调：统一输出 JSON 结构的响应体，便于前端消费。

章节来源

架构总览 ​

下图展示认证授权在系统中的交互关系与职责划分：

图表来源

详细组件分析 ​

用户详情服务实现 ​

  • 职责：根据用户名从系统用户服务加载用户信息，封装为自定义 UserDetails，包含用户标识、账号、菜单、权限、姓名、部门、上级等。
  • 关键点：当用户不存在时抛出用户名未找到异常；权限列表由后端返回并转换为 Spring Security 的 Authority 列表。

图表来源

章节来源

密码模式认证流程 ​

  • 参数转换：从请求中提取 grant_type、scope、username、password，并校验格式与必填项；同时要求已通过客户端认证。
  • 客户端与作用域校验：确保客户端允许该授权类型且请求的作用域在注册范围内。
  • 用户名密码校验：委托 AuthenticationManager 执行，内部使用 DAO 提供者的密码匹配逻辑。
  • 令牌签发：生成访问令牌与可选刷新令牌，保存授权信息，返回令牌与附加参数。

图表来源

章节来源

令牌生成与定制机制 ​

  • 访问令牌生成：采用引用型格式，生成唯一值并设置签发时间与过期时间；支持自定义声明上下文。
  • 刷新令牌生成：按客户端配置的过期时间生成，仅在客户端允许且非公共客户端时发放。
  • 令牌定制：向访问令牌声明中注入用户权限集合、用户标识与用户名，便于资源服务端快速鉴权与授权。

图表来源

章节来源

认证拦截器与回调 ​

  • 成功回调：将访问令牌、刷新令牌与附加参数统一包装为标准响应体，便于前端直接使用。
  • 失败回调：记录失败日志并返回统一的错误响应体，避免泄露敏感信息。

图表来源

章节来源

OAuth2 授权模式支持说明 ​

  • 授权码模式：由授权服务器与资源服务器协同实现，此处重点为密码模式与客户端凭证模式的实现。
  • 客户端凭证模式：在令牌定制阶段会跳过用户信息注入，仅返回客户端维度的令牌。
  • 密码模式：通过用户名/密码换取访问令牌与刷新令牌，支持作用域选择与客户端认证。

章节来源

依赖关系分析 ​

  • 组件内聚性：认证提供者聚合了转换器、用户详情服务、令牌生成器与授权保存，职责清晰。
  • 外部依赖：用户详情服务依赖系统用户服务；令牌生成依赖客户端令牌设置；回调依赖统一响应封装。
  • 可能的耦合点：密码匹配逻辑与用户详情服务解耦于 DAO 提供者；令牌定制器与用户详情模型存在强依赖，需保证字段一致性。

图表来源

性能考量 ​

  • 令牌生成：访问令牌采用引用型格式并携带自定义声明，建议在资源服务端缓存必要的用户权限集合，减少频繁查询。
  • 授权保存：授权记录保存在授权服务端，建议结合缓存与异步落库策略降低延迟。
  • 用户详情：用户详情服务应具备限流与熔断保护，避免认证风暴影响整体可用性。
  • 密码匹配：DAO 提供者使用工具类进行密码匹配，建议在高并发场景下优化匹配算法与数据库索引。

故障排查指南 ​

  • 用户名未找到：确认用户详情服务返回的用户标识是否存在；检查用户名大小写与特殊字符。
  • 认证失败：查看失败回调日志，定位用户名或密码错误；检查客户端认证信息是否完整。
  • 令牌签发失败：核对客户端令牌设置与授权类型配置；确认令牌生成器与定制器正常工作。
  • 作用域无效：确保请求的作用域在客户端注册范围内；避免传递多余空格或重复作用域。

章节来源

结论 ​

DeviceMate 的认证授权体系以 Spring Security 与 Spring Authorization Server 为基础，结合自定义转换器、提供者与令牌生成器，实现了灵活可控的密码模式认证与令牌签发。通过用户详情服务与 DAO 提供者分离职责，配合统一的成功/失败回调与令牌定制，既满足业务需求又便于扩展与维护。建议在生产环境中进一步完善用户详情服务的稳定性、令牌缓存策略与密码强度校验机制。

附录 ​

  • 忽略路径配置：集中管理无需鉴权的接口白名单，便于统一放行静态资源与公开接口。
  • 密码安全策略建议：
    • 密码加密存储：使用强哈希算法与足够迭代次数，避免明文或弱加密。
    • 密码强度验证：长度、复杂度与常见弱口令检测。
    • 密码历史记录：限制新密码与历史密码的相似度，防止循环修改。

章节来源