# test-sso

**Repository Path**: pytaq/test-sso

## Basic Information

- **Project Name**: test-sso
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用户中心项目详解

## 一、项目概述

### 1.1 项目简介
这是一个基于 Spring Boot 3+、Java 21 构建的完整单点登录（SSO）解决方案，采用 OAuth2.0+OIDC+JWT+Redis 技术栈，实现了认证中心与资源服务器分离的架构。

### 1.2 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.2.5 | 基础框架 |
| Java | 21 | 编程语言 |
| Spring Authorization Server | 1.2.4 | OAuth2 认证服务器 |
| Spring Security OAuth2 Resource Server | 6.2.4 | OAuth2 资源服务器 |
| MyBatis-Plus | 3.5.7 | ORM 框架 |
| MySQL | 8.0+ | 关系数据库 |
| Redis | 5.x+ | 缓存/黑名单存储 |
| Thymeleaf | 3.x | 模板引擎 |

## 二、项目架构

```
test-sso/
├── user-center-auth/          # 认证中心 (9000端口)
├── user-center-manage/        # 用户管理中心 (9001端口)
└── pom.xml                    # 父POM
```

### 2.1 系统架构图

```
┌─────────────────────────────────────────────────────────┐
│                        用户浏览器                         │
└────────────────┬────────────────────────────────────────┘
                 │
        ┌────────▼────────┐
        │  管理中心(9001) │ ← OAuth2 客户端 + 资源服务器
        │  (User Manage)  │
        └────────┬────────┘
                 │ OAuth2/OIDC 流程
        ┌────────▼────────┐
        │ 认证中心(9000)  │ ← Spring Authorization Server
        │  (Auth Server)  │
        └────────┬────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
┌───▼───┐   ┌──▼───┐    ┌──▼───┐
│ Redis │   │ MySQL│    │ MySQL │
│(9000)│   │(Auth)│    │(Mang)│
└───────┘   └──────┘    └──────┘
```

## 三、模块详解

### 3.1 user-center-auth（认证中心）

#### 3.1.1 核心职责
- 用户认证与授权
- OAuth2/OIDC 协议实现
- JWT 令牌签发与管理
- 客户端注册与管理
- 令牌黑名单（Redis）

#### 3.1.2 项目结构
```
user-center-auth/
├── src/main/java/com/gwj/usercenter/
│   ├── UserCenterAuthApplication.java      # 启动类
│   ├── config/
│   │   ├── AuthorizationServerConfig.java  # OAuth2 授权服务器配置
│   │   ├── CommonSecurityConfig.java       # 通用安全配置
│   │   ├── ClientRegistrationConfig.java   # 客户端注册初始化
│   │   ├── DataInitializer.java            # 数据初始化
│   │   ├── OAuth2TokenCustomizerConfig.java # JWT 自定义
│   │   └── RedisConfig.java                # Redis 配置
│   ├── controller/
│   │   ├── AuthController.java             # 认证控制器（登出）
│   │   └── HomeController.java             # 首页控制器
│   ├── entity/
│   │   └── AuthUser.java                   # 用户实体
│   ├── filter/
│   │   └── JwtBlacklistFilter.java         # JWT 黑名单过滤器
│   ├── mapper/
│   │   └── AuthUserMapper.java             # MyBatis Mapper
│   ├── security/
│   │   └── AuthUserDetailsService.java     # 用户详情服务
│   └── service/
│       └── JwtBlacklistService.java        # JWT 黑名单服务
├── src/main/resources/
│   ├── application.yml                     # 配置文件
│   ├── mapper/                             # MyBatis XML
│   └── templates/
│       └── login.html                      # 登录页
├── sql/
│   └── user_center_auth.sql                # 数据库脚本
└── pom.xml
```

#### 3.1.3 核心配置类

**AuthorizationServerConfig**
- 配置 OAuth2 授权端点
- 配置两个 SecurityFilterChain（@Order 1 和 @Order 2）
- 配置 JWT 签名密钥（动态生成 RSA）
- 配置客户端存储、授权存储

**CommonSecurityConfig**
- 配置 AuthenticationManager
- 配置 PasswordEncoder（BCrypt）

**ClientRegistrationConfig**
- 初始化 OAuth2 客户端（user-center-manage）

**DataInitializer**
- 初始化默认用户（admin/admin123, user/user123）
- 自动更新已存在用户的密码

#### 3.1.4 OAuth2 端点

| 端点 | 说明 |
|------|------|
| `/oauth2/authorize` | 授权端点 |
| `/oauth2/token` | 令牌端点 |
| `/oauth2/introspect` | 令牌自省端点 |
| `/oauth2/revoke` | 令牌撤销端点 |
| `/.well-known/openid-configuration` | OIDC 发现端点 |
| `/oauth2/jwks` | JWKS 公钥端点 |

#### 3.1.5 核心服务

**JwtBlacklistService**
- 将已撤销的令牌加入 Redis 黑名单
- 检查令牌是否在黑名单中
- 自动过期机制（与 JWT 过期时间一致）

**AuthUserDetailsService**
- 实现 Spring Security UserDetailsService
- 从数据库加载用户信息

---

### 3.2 user-center-manage（用户管理中心）

#### 3.2.1 核心职责
- OAuth2 客户端，通过认证中心登录
- 资源服务器，提供用户、角色、权限管理 API
- 基于 JWT 进行访问控制

#### 3.2.2 项目结构
```
user-center-manage/
├── src/main/java/com/gwj/usercenter/
│   ├── UserCenterManageApplication.java    # 启动类
│   ├── config/
│   │   ├── SecurityConfig.java             # 安全配置
│   │   ├── DataInitializer.java            # 数据初始化
│   │   ├── GlobalExceptionHandler.java     # 全局异常处理
│   │   ├── JwtAuthenticationEntryPoint.java # JWT 认证失败处理
│   │   └── RedisConfig.java                # Redis 配置
│   ├── controller/
│   │   ├── HomeController.java             # 首页控制器
│   │   ├── UserController.java             # 用户管理
│   │   ├── RoleController.java             # 角色管理
│   │   └── PermissionController.java       # 权限管理
│   ├── dto/
│   │   ├── ApiResponse.java                # 统一响应格式
│   │   ├── UserCreateRequest.java
│   │   ├── UserUpdateRequest.java
│   │   ├── UserResponse.java
│   │   ├── RoleCreateRequest.java
│   │   ├── RoleResponse.java
│   │   ├── PermissionCreateRequest.java
│   │   └── PermissionResponse.java
│   ├── entity/
│   │   ├── SysUser.java                    # 用户表
│   │   ├── SysRole.java                    # 角色表
│   │   ├── SysPermission.java              # 权限表
│   │   ├── SysUserRole.java                # 用户-角色关联
│   │   ├── SysRolePermission.java          # 角色-权限关联
│   │   ├── SysMenu.java                    # 菜单表
│   │   └── SysOrg.java                     # 组织表
│   ├── filter/
│   │   └── JwtBlacklistFilter.java         # JWT 黑名单过滤器
│   ├── mapper/
│   │   ├── SysUserMapper.java
│   │   ├── SysRoleMapper.java
│   │   ├── SysPermissionMapper.java
│   │   ├── SysUserRoleMapper.java
│   │   ├── SysRolePermissionMapper.java
│   │   ├── SysMenuMapper.java
│   │   └── SysOrgMapper.java
│   └── service/
│       ├── UserService.java
│       ├── RoleService.java
│       ├── PermissionService.java
│       └── JwtBlacklistService.java
├── src/main/resources/
│   ├── application.yml                     # 配置文件
│   ├── mapper/                             # MyBatis XML
│   └── templates/
│       └── index.html                      # 首页
├── sql/
│   └── user_center_manage.sql              # 数据库脚本
└── pom.xml
```

#### 3.2.3 核心配置类

**SecurityConfig**
- 配置 OAuth2 客户端登录
- 配置 OAuth2 资源服务器（JWT 验证）
- 配置路径访问权限
- 配置登出（重定向到认证中心）
- 添加 JWT 黑名单过滤器

#### 3.2.4 REST API

**用户管理**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/users` | 获取用户列表 |
| GET | `/api/users/{id}` | 获取用户详情 |
| POST | `/api/users` | 创建用户 |
| PUT | `/api/users/{id}` | 更新用户 |
| DELETE | `/api/users/{id}` | 删除用户 |

**角色管理**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/roles` | 获取角色列表 |
| POST | `/api/roles` | 创建角色 |

**权限管理**
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/permissions` | 获取权限列表 |
| POST | `/api/permissions` | 创建权限 |

#### 3.2.5 数据库表结构

**sys_user** - 用户表
**sys_role** - 角色表
**sys_permission** - 权限表
**sys_user_role** - 用户-角色关联表
**sys_role_permission** - 角色-权限关联表
**sys_menu** - 菜单表
**sys_org** - 组织表

---

## 四、核心功能详解

### 4.1 单点登录（SSO）流程

```
1. 用户访问 http://localhost:9001
   ↓
2. 管理中心检测未认证，重定向到:
   http://localhost:9000/oauth2/authorization/user-center-auth
   ↓
3. 认证中心重定向到登录页 /login
   ↓
4. 用户输入账号密码（admin/admin123）
   ↓
5. 认证中心验证成功，生成授权码
   ↓
6. 重定向回管理中心回调地址:
   http://localhost:9001/login/oauth2/code/user-center-auth?code=xxx
   ↓
7. 管理中心用授权码换取 access_token + id_token
   ↓
8. 管理中心用 access_token 获取用户信息
   ↓
9. 用户登录成功，进入管理后台首页
```

### 4.2 JWT 黑名单机制

#### 工作原理
1. 用户登出时，令牌加入 Redis 黑名单
2. 黑名单 Key: `jwt:blacklist:{token}`
3. 黑名单过期时间 = JWT 剩余过期时间
4. 每次请求检查令牌是否在黑名单中

#### 实现细节
- 两个服务共享同一个 Redis 实例
- 两个服务都有相同的 JwtBlacklistFilter
- 登出流程：管理中心登出 → 重定向到认证中心登出

### 4.3 令牌自定义

**OAuth2TokenCustomizerConfig**
- 可自定义 JWT 的 claims
- 添加额外的用户信息到令牌

---

## 五、配置说明

### 5.1 认证中心配置 (application.yml)

```yaml
server:
  port: 9000

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/user_center_auth
    username: root
    password: 123456
  data:
    redis:
      host: localhost
      port: 6379
```

### 5.2 管理中心配置 (application.yml)

```yaml
server:
  port: 9001

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/user_center_manage
    username: root
    password: 123456
  data:
    redis:
      host: localhost
      port: 6379
  security:
    oauth2:
      client:
        registration:
          user-center-auth:
            client-id: user-center-manage
            client-secret: manage-secret
            authorization-grant-type: authorization_code
            redirect-uri: http://localhost:9001/login/oauth2/code/user-center-auth
        provider:
          user-center-auth:
            issuer-uri: http://localhost:9000
```

---

## 六、快速启动

### 6.1 前置要求
- JDK 21+
- Maven 3.6+
- MySQL 8.0+
- Redis 5.x+

### 6.2 数据库初始化

1. 创建数据库
```sql
CREATE DATABASE user_center_auth CHARACTER SET utf8mb4;
CREATE DATABASE user_center_manage CHARACTER SET utf8mb4;
```

2. 执行 SQL 脚本
```bash
# 认证中心数据库
mysql -u root -p user_center_auth < user-center-auth/sql/user_center_auth.sql

# 管理中心数据库
mysql -u root -p user_center_manage < user-center-manage/sql/user_center_manage.sql
```

### 6.3 启动服务

```bash
# 1. 启动认证中心
cd user-center-auth
mvn spring-boot:run

# 2. 启动管理中心（新终端）
cd user-center-manage
mvn spring-boot:run
```

### 6.4 访问

| 服务 | URL | 说明 |
|------|-----|------|
| 管理中心 | http://localhost:9001 | 自动重定向到认证中心 |
| 认证中心 | http://localhost:9000 | 登录页面 |

### 6.5 测试账号
| 用户名 | 密码 | 说明 |
|--------|------|------|
| admin | admin123 | 管理员 |
| user | user123 | 普通用户 |

---

## 七、技术亮点

### 7.1 架构优势
- **解耦** - 认证中心与业务系统分离
- **可扩展** - 可接入更多 OAuth2 客户端
- **标准协议** - OAuth2.0 + OIDC，兼容性好

### 7.2 安全特性
- **JWT 签名** - RSA 非对称加密
- **令牌黑名单** - 支持即时撤销
- **BCrypt 密码** - 安全的密码哈希
- **CSRF 保护** - 防止跨站请求伪造

### 7.3 开发体验
- **MyBatis-Plus** - 简化 CRUD
- **统一响应** - ApiResponse 包装
- **全局异常** - 统一异常处理
- **数据初始化** - 自动初始化测试数据

---

## 八、扩展建议

### 8.1 功能扩展
- [ ] 添加 OAuth2 客户端管理页面
- [ ] 实现刷新令牌机制
- [ ] 添加记住我功能
- [ ] 实现权限细粒度控制
- [ ] 添加审计日志

### 8.2 架构优化
- [ ] 配置中心（Nacos/Apollo）
- [ ] 服务注册发现
- [ ] 网关统一入口
- [ ] 分布式事务
- [ ] 链路追踪

---

## 九、常见问题

### Q1: 为什么两个服务都有 JwtBlacklistFilter？
A: 两个服务都是资源服务器，都需要验证 JWT。共享 Redis 黑名单可以确保令牌在任何地方都被正确拒绝。

### Q2: RSA 密钥每次重启都会变化吗？
A: 是的，当前实现是动态生成的。生产环境建议使用持久化的密钥对。

### Q3: 如何添加新的 OAuth2 客户端？
A: 在认证中心数据库的 `oauth2_registered_client` 表中插入新记录，或修改 ClientRegistrationConfig 自动初始化。

---

## 十、总结

该项目是一个完整的企业级单点登录解决方案，展示了 Spring Authorization Server 的最佳实践，包括：
- OAuth2/OIDC 标准协议实现
- JWT 令牌管理与撤销
- 认证中心与资源服务器分离
- 基于 RBAC 的权限管理
- Redis 集成与应用

适合作为学习 OAuth2.0、Spring Security、SSO 的参考项目，也可作为生产环境的基础架构进行二次开发。