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) - [CustomUserDetailsServiceImpl.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/CustomUserDetailsServiceImpl.java) - [ResourceServerAutoConfiguration.java](file://lemes-cloud/lemes-framework/lemes-framework-auth/src/main/java/com/lenovo/lemes/framework/auth/config/ResourceServerAutoConfiguration.java) - [CustomUserDetails.java](file://lemes-cloud/lemes-framework/lemes-framework-auth/src/main/java/com/lenovo/lemes/framework/auth/util/CustomUserDetails.java) - [CustomUserDetailsDTO.java](file://lemes-cloud/lemes-framework/lemes-framework-auth/src/main/java/com/lenovo/lemes/framework/auth/util/CustomUserDetailsDTO.java) - [LemesAuthProperties.java](file://lemes-cloud/lemes-framework/lemes-framework-auth/src/main/java/com/lenovo/lemes/framework/auth/config/LemesAuthProperties.java) - [SecurityConstants.java](file://lemes-cloud/lemes-framework/lemes-framework-auth/src/main/java/com/lenovo/lemes/framework/auth/constant/SecurityConstants.java) - [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)

目录 ​

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

引言 ​

本技术文档围绕用户权限管理系统展开，重点阐释认证与授权机制的实现原理，涵盖以下方面：

  • JWT 令牌管理与 OAuth2 集成
  • 基于角色的访问控制（RBAC）与菜单权限控制
  • 数据权限过滤与资源服务端鉴权
  • 用户管理 API 的完整接口说明
  • 在其他服务中集成认证与权限验证的最佳实践
  • 安全最佳实践与性能优化建议

该系统采用 Spring Boot + Spring Security + Spring Authorization Server + OAuth2 资源服务器模式，结合自定义用户详情模型与客户端属性配置，形成统一的认证与授权基础设施。

项目结构 ​

本项目采用多模块分层组织，权限相关能力主要分布在如下模块：

  • 权限服务（lemes-auth）：负责认证服务器、令牌签发与刷新、登录与登出接口
  • 权限框架（lemes-framework-auth）：提供资源服务器配置、用户详情模型、安全常量、客户端属性等
  • 通用业务模块（lemes-service-dm-common-common）：包含 OAuth 客户端配置实体，用于存储客户端信息

图表来源

章节来源

核心组件 ​

  • 应用入口与扫描路径

  • 认证服务器配置

    • 配置 OAuth2 授权端点转换器、认证提供者、令牌生成器与增强器、资源服务器的不透明令牌内省器、异常处理与放行路径。
    • 参考路径：AuthorizationServerConfig.java:1-152

  • 登录控制器

    • 提供密码登录、登出、刷新令牌与列出在线用户的接口；根据终端标识选择客户端属性，支持同账号多地登录场景。
    • 参考路径：SysLoginController.java:1-143

  • 用户详情加载

    • 通过 Feign 客户端从用户服务加载用户详情，构建包含菜单列表、权限集合、部门与上级等信息的自定义用户对象。
    • 参考路径：CustomUserDetailsServiceImpl.java:1-33

  • 资源服务器配置

  • 用户详情模型与 DTO

  • 认证属性与安全常量

  • OAuth 客户端实体

    • 存储 OAuth 客户端的关键信息，如客户端 ID、资源 ID、密钥、授权范围、授权类型、重定向地址、权限、有效期等。
    • 参考路径：OauthCliendetails.java:1-89

章节来源

架构总览 ​

系统采用“认证服务器 + 资源服务器 + 客户端应用”的三层架构：

  • 认证服务器：负责令牌签发、刷新与登出；支持多种授权模式（密码、刷新令牌等）
  • 资源服务器：对受保护资源进行鉴权，使用不透明令牌内省器校验令牌有效性
  • 客户端应用：通过 Basic 认证调用认证服务器获取令牌，或携带令牌访问受保护资源

图表来源

详细组件分析 ​

认证服务器配置（AuthorizationServerConfig） ​

  • 功能要点
    • 配置 OAuth2 授权端点的请求转换器，支持授权码、刷新令牌、客户端凭证与密码模式
    • 注册密码模式认证提供者与自定义成功/失败处理器
    • 配置令牌生成器与增强器，向访问令牌中注入用户相关信息
    • 配置资源服务器使用不透明令牌内省器，设置放行路径与异常处理
    • 提供密码编码器与认证服务器设置 Bean

图表来源

章节来源

登录控制器（SysLoginController） ​

  • 功能要点
    • 密码登录：根据终端标识选择客户端属性，支持同账号多地登录；若已存在有效授权则直接返回令牌，否则调用认证服务器获取
    • 登出：解析 Bearer 令牌，查找对应授权并移除
    • 刷新令牌：基于刷新令牌调用认证服务器刷新访问令牌
    • 列出在线用户：通过 Redis 键空间扫描当前登录用户

图表来源

章节来源

用户详情加载（CustomUserDetailsServiceImpl） ​

  • 功能要点
    • 通过 Feign 客户端加载用户详情 DTO
    • 构建包含用户 ID、用户名、菜单列表、密码、权限集合、姓名、API Token、部门与上级的自定义用户对象
    • 若未找到用户则抛出用户名不存在异常

图表来源

章节来源

资源服务器配置（ResourceServerAutoConfiguration） ​

  • 功能要点
    • 启用 Web 安全与方法级权限注解
    • 配置不透明令牌内省器与异常处理
    • 放行指定路径，其余请求均需认证

图表来源

章节来源

用户详情模型与 DTO（CustomUserDetails / CustomUserDetailsDTO） ​

  • 功能要点
    • 自定义用户详情类继承 Spring Security User，扩展用户 ID、菜单列表、API Token、部门与上级等字段
    • 用户详情 DTO 继承基础用户实体，新增权限集合与菜单列表字段

图表来源

章节来源

OAuth 客户端实体（OauthCliendetails） ​

  • 字段说明
    • 客户端 ID、资源 ID、客户端密钥、授权范围、授权类型、重定向地址、权限、访问令牌有效期、刷新令牌有效期、附加信息、自动授权标志等
  • 用途
    • 存储 OAuth 客户端配置，供认证服务器识别与校验客户端

图表来源

章节来源

依赖分析 ​

  • 组件耦合
    • 认证服务器配置依赖用户详情服务、不透明令牌内省器与放行路径配置
    • 登录控制器依赖认证属性配置、授权服务与认证服务器客户端
    • 资源服务器配置依赖不透明令牌内省器与放行路径配置
    • 用户详情加载依赖用户服务 Feign 客户端与自定义用户详情模型
  • 外部依赖
    • Spring Security、Spring Authorization Server、Spring Cloud OpenFeign、BCrypt 密码编码器

图表来源

章节来源

性能考虑 ​

[本节为通用性能建议，无需具体文件分析]

故障排查指南 ​

章节来源

结论 ​

本权限管理系统通过认证服务器与资源服务器的协同，实现了完善的 OAuth2 授权与令牌管理；结合自定义用户详情模型与客户端属性配置，满足多终端、多租户与多地登录的复杂场景需求。系统在安全性与可扩展性之间取得平衡，适合在微服务架构中作为统一的认证与授权基础设施。

[本节为总结性内容，无需具体文件分析]

附录 ​

用户管理 API 接口文档 ​

  • 密码登录

    • 方法与路径：POST /auth/pwdLogin
    • 请求头：TERMINAL（终端标识）
    • 参数：username（用户名）、password（密码）
    • 行为：根据终端选择客户端属性；若存在有效授权则直接返回令牌，否则调用认证服务器获取
    • 参考路径：SysLoginController.java:55-85

  • 登出

    • 方法与路径：DELETE /auth/logoff
    • 请求头：Authorization（Bearer 令牌）
    • 行为：解析令牌并移除对应授权
    • 参考路径：SysLoginController.java:87-103

  • 刷新令牌

    • 方法与路径：POST /auth/refreshToken
    • 请求头：TERMINAL（终端标识）
    • 参数：grant_type=refresh_token（刷新令牌）
    • 行为：调用认证服务器刷新访问令牌
    • 参考路径：SysLoginController.java:111-126

  • 列出在线用户

    • 方法与路径：GET /auth/listLoginUser
    • 权限：需要特定自定义权限
    • 行为：扫描 Redis 键空间，返回当前登录用户列表
    • 参考路径：SysLoginController.java:135-140

章节来源

集成指南（在其他服务中） ​

章节来源

安全最佳实践 ​

章节来源