# op-idp

**Repository Path**: liyuncc/op-idp

## Basic Information

- **Project Name**: op-idp
- **Description**: OP-IDP 是一个基于 Spring Authorization Server 自研的 OAuth2/OIDC 身份认证平台（对标 Auth0/Keycloak），提供统一登录、单点登录（SSO）、统一登出（SLO）、多因素认证（MFA）与管理后台，定位私有化单租户交付，开箱即用。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://liyuncong.cn
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2023-11-29
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OP-IDP - 身份认证平台

> 版本：v1.0.0  
> 最后更新：2026-09-12  
> OAuth2 / OIDC 统一身份认证平台（Identity Provider）

## 项目概述

**op-idp = 身份认证中心（Identity Provider）**，负责 **认证（Authentication）** 与 **身份（Identity）**，不负责业务权限（Authorization）。

核心使命：
1. **确认用户是谁（Who you are）**
2. **安全地发放 Token（ID Token / Access Token / Refresh Token）**

定位为**私有化单租户交付**的授权服务器，不做 SaaS 多租户。

### 核心特性

- 标准合规：基于 Spring Authorization Server 完整实现 OAuth2.0 / OIDC 核心规范
- 安全可靠：Token 安全、密钥安全、会话安全、审计可追溯
- 单点登录（SSO）：auth-ui 与 console 共享 AS Session，支持统一登出（OIDC RP-Initiated Logout + Front-Channel SLO）
- 可扩展：支持多种登录方式（密码 / MFA / 第三方联邦登录）、Token 策略
- 专业体验：对标 Authing / Okta / Keycloak 的用户体验

---

## 项目结构

```
op-idp/
├── op-idp-server          # OAuth2/OIDC 授权服务器（后端，DDD 分层）
├── op-idp-auth-ui         # 用户门户（登录、注册、授权确认、账号中心）
├── op-idp-console         # 管理后台（用户、客户端、策略、RBAC 管理）
├── op-idp-shared          # 共享包（API 封装、工具、常量、类型）
└── docs/                  # 项目文档（架构 / API / 产品 / 安全 / 运维）
```

---

## 模块说明

### op-idp-server（后端授权服务器）

**定位**：身份认证中心的核心引擎（Identity Provider Core / Authorization Server）

**技术栈**：
- Spring Boot 3.5.5 + Spring Authorization Server 1.5.2（JDK 21）
- Spring Security 6.5.3 / Spring Data JPA / Spring Data Redis
- Spring Session Data Redis（会话持久化，支持多副本共享与 SLO 广播）
- MySQL 8.0+ / Redis 7.0+
- JWT（RS256），Thymeleaf（服务端错误页）

**核心功能**：
- 协议层：`/authorize`、`/token`、`/userinfo`、`/connect/logout`（OIDC RP-Initiated Logout）、`/oauth2/jwks`、`/.well-known/openid-configuration`
- 认证与会话：密码登录（Username/Email/Phone）、MFA（TOTP）、第三方登录（Gitee 已集成）、Session 持久化（Redis）
- 单点登出：Front-Channel Logout 广播（iframe 通知各 RP），Back-Channel Logout 待实施
- Token 策略：`idp_token_policy` 命名策略，客户端经 `token_policy_id` 引用，运行时动态覆盖
- 用户与身份：四表 IdP 架构（`idp_user` / `idp_user_account` / `idp_user_credentials` / `idp_federated_identity`）
- RBAC：`idp_user_role` / `idp_user_permission` 角色权限体系，管理员由 `IDP_ADMIN` 角色判定
- 管理 API：提供给 op-idp-console 的 `/api/v1/*` REST 接口

**部署**：Docker 容器，端口 `9000`

**详细文档**：[op-idp-server 产品蓝图](./docs/product/OP_IDP_SERVER_PRODUCT_BLUEPRINT.md) | [op-idp-server README](./op-idp-server/README.md)

---

### op-idp-auth-ui（用户认证门户）

**定位**：身份认证中心的用户侧产品层（Identity Experience Layer）

**技术栈**：
- Vue 3 + Vite + TypeScript（`<script setup>`）
- reka-ui + Tailwind CSS（shadcn-vue 风格）
- vue-router + vue-i18n + vee-validate + zod
- 状态管理：模块级单例（未引入 Pinia）
- 认证方式：OAuth2 Authorization Code + PKCE（Public Client），Token 存 sessionStorage

**面向用户**：普通用户（C 端）

**核心功能**：

| 模块 | 页面 |
|------|------|
| 认证（/auth） | Login、Register、ForgotPassword、ResetPassword、VerifyEmail、VerifyPhone |
| MFA | MfaVerify、MfaSetup |
| 授权 | Consent（授权确认）、AuthCallback（回调换 Token） |
| 设备码 | DeviceActivate、DeviceActivated |
| 登出 | LogoutSuccess、LogoutCallback、FrontLogout（SLO 广播页） |
| 账号中心 | Dashboard、Profile、AccountSettings、ChangePassword |
| 会话/授权 | Sessions、AuthorizedApps、LoginHistory、SecurityLogs、AccountBinding |

**部署**：nginx 静态文件，根路径 `/`；开发端口 `3001`

**详细文档**：[op-idp-auth-ui 产品蓝图](./docs/product/OP_IDP_AUTH_UI_PRODUCT_BLUEPRINT.md) | [op-idp-auth-ui README](./op-idp-auth-ui/README.md)

---

### op-idp-console（管理后台）

**技术栈**：
- Nuxt 3（SPA 模式，`ssr: false`）+ TypeScript
- reka-ui + shadcn-nuxt + Tailwind CSS v4
- vue-i18n（中英双语已落地）
- vue-sonner（toast）+ @tanstack/vue-table（表格）

**面向用户**：管理员（B 端）

**核心功能**：

| 模块 | 页面 |
|------|------|
| Dashboard | 统计（stats / system-info / recent-logins） |
| 用户管理 | users（列表 / 详情 / 表单）、重置密码、会话管理 |
| 客户端管理 | clients（列表 / 详情 / 表单） |
| 授权记录 | consents |
| 密钥管理 | jwks（列表 / 详情 / 轮换） |
| Token 策略 | token-policies（列表 / 表单） |
| 登录日志 / 审计日志 | login-logs / audit-logs |
| 管理员与角色 | admins / roles（RBAC） |
| 系统设置 | settings（appearance / display / notifications / profile） |

**部署**：nginx 静态文件，子路径 `/console/`；开发端口 `3002`

**详细文档**：[op-idp-console 产品蓝图](./docs/product/OP_IDP_CONSOLE_PRODUCT_BLUEPRINT.md) | [op-idp-console README](./op-idp-console/README.md)

---

### op-idp-shared（共享包）

**用途**：公共代码复用（开发时依赖，不独立部署）

**内容**：
- API 封装（axios 实例、请求/响应拦截器，`src/api/*`）
- 工具函数（JWT 解析、日期格式化、存储、Cookie、PKCE，`src/utils/*`）
- 常量（OAuth2 配置、响应码、Scopes，`src/constants/*`）
- TypeScript 类型（各 API 模块的 request/response 类型，`src/api/types/*`）

**分发**：开发通过 `file:` 本地依赖（`@op-idp/shared: file:../op-idp-shared`），不发布 npm

**详细文档**：[op-idp-shared README](./op-idp-shared/README.md)

---

## 开发环境快速开始

### 前置要求

- JDK 21+
- Node.js 18+
- MySQL 8.0+
- Redis 7.0+

### 端口约定

| 服务 | 端口 | 说明 |
|------|------|------|
| op-idp-server | 9000 | 后端授权服务器 |
| op-idp-auth-ui | 3001 | 用户认证门户 |
| op-idp-console | 3002 | 管理后台 |

### 1. 后端启动

```bash
cd op-idp-server

# 配置数据库连接（application-dev.yaml / application-cloud.yaml）
# 初始化数据库（执行 resources/db/*.sql 建表脚本）
mysql -u root -p op_idp < src/main/resources/db/idp_user.sql
# ... 其余脚本

mvn spring-boot:run
# 访问 http://localhost:9000
```

> 数据初始化说明：`application.yaml` 中 `spring.jpa.generate-ddl: false`，表结构由 `src/main/resources/db/*.sql` 脚本维护，种子数据（客户端、管理员、URI）由 `DataInitializer` + `SeedDataProperties` 注入。

### 2. auth-ui 启动

```bash
cd op-idp-auth-ui
npm install
npm run dev
# 访问 http://localhost:3001
```

### 3. console 启动

```bash
cd op-idp-console
npm install
npm run dev
# 访问 http://localhost:3002/console/
```

> console 通过 Vite proxy 将 `/api`、`/oauth2`、`/.well-known`、`/logout`、`/connect` 代理到后端 9000 端口。

### 4. 共享包

auth-ui 与 console 的 `package.json` 均通过 `"@op-idp/shared": "file:../op-idp-shared"` 本地引用，无需 `npm link`。

---

## 关键功能说明

### OAuth2 / OIDC 授权流程

```
业务系统 → /authorize → auth-ui 登录 → MFA（可选）→ Consent（可选）→ 回跳 redirect_uri → /token 换 Token
```

- 支持 Authorization Code + PKCE、Refresh Token、Client Credentials
- `auth-ui` 自身为特殊 client（Public Client + PKCE），与 console 共享 AS Session 实现 SSO

### 统一登出与 SSO

- 全端走 OIDC RP-Initiated Logout（`/connect/logout`，`id_token_hint` + `post_logout_redirect_uri` 白名单）
- Front-Channel Logout 广播：登出时通过 iframe 通知各 RP（auth-ui / console）清理本地状态
- 跨 tab 同步：`storage` 事件监听 + `op_idp_front_logout` 标记

### Token 策略

- 客户端通过 `token_policy_id` 引用 `idp_token_policy` 策略，运行时覆盖 `tokenSettings`，删除后回退客户端配置
- Access Token：默认 15 分钟（JWT / Opaque 可配）
- Refresh Token：默认 7 天，支持轮换与复用检测

### 安全特性

- 三条安全链：AS 链（OAuth2 无状态 JWT，Order=1）、auth-ui 链（Session+CSRF，Order=2）、API 链（纯 JWT，Order=3）
- 登录失败 Redis 计数：5 次锁定 15 分钟
- CSRF 双重 Token 机制（Cookie + Header）
- 密码 BCrypt 加密，密码历史表

---

## 部署

生产部署方式：**Docker Compose + Nginx 统一容器**，单域名多路径：

- `/` → auth-ui 静态文件
- `/console/` → console 静态文件
- `/api`、`/oauth2`、`/.well-known`、`/logout`、`/connect` → 反向代理后端 9000

详细说明见 [部署指南](./docs/operations/DEPLOYMENT_GUIDE.md)。

---

## 相关文档

### 产品文档
- [op-idp 职责边界说明](./docs/product/OP_IDP_RESPONSIBILITY_BOUNDARY.md)
- [op-idp-server 产品蓝图](./docs/product/OP_IDP_SERVER_PRODUCT_BLUEPRINT.md)
- [op-idp-auth-ui 产品蓝图](./docs/product/OP_IDP_AUTH_UI_PRODUCT_BLUEPRINT.md)
- [op-idp-console 产品蓝图](./docs/product/OP_IDP_CONSOLE_PRODUCT_BLUEPRINT.md)

### 架构文档
- [ARCHITECTURE.md](./docs/architecture/ARCHITECTURE.md) - 系统架构设计
- [DATABASE_DESIGN.md](./docs/architecture/DATABASE_DESIGN.md) - 数据库设计（真实 24 张表）
- [KEY_AND_TOKEN_LIFECYCLE.md](./docs/architecture/KEY_AND_TOKEN_LIFECYCLE.md) - 密钥与 Token 生命周期
- [API_VERSIONING.md](./docs/architecture/API_VERSIONING.md) - API 版本策略

### 安全文档
- [SECURITY_POLICY.md](./docs/security/SECURITY_POLICY.md)
- [THREAT_MODEL.md](./docs/security/THREAT_MODEL.md)
- [PRIVACY_AND_DATA_GOVERNANCE.md](./docs/security/PRIVACY_AND_DATA_GOVERNANCE.md)

### API 文档
- [API_REFERENCE.md](./docs/api/API_REFERENCE.md)
- [ERROR_HANDLING_GUIDE.md](./docs/api/ERROR_HANDLING_GUIDE.md)
- [INTEGRATION_GUIDE.md](./docs/api/INTEGRATION_GUIDE.md)

### 运维文档
- [DEPLOYMENT_GUIDE.md](./docs/operations/DEPLOYMENT_GUIDE.md)
- [DOCKER_IMAGE_OPTIMIZATION.md](./docs/operations/DOCKER_IMAGE_OPTIMIZATION.md) - Docker 镜像优化方案
- [DOCKER_IMAGE_ANALYSIS.md](./docs/operations/DOCKER_IMAGE_ANALYSIS.md) - Docker 镜像分析手段

### 设计文档
- [DDD_ARCHITECTURE_DESIGN.md](./op-idp-server/DDD_ARCHITECTURE_DESIGN.md) - 后端 DDD 分层设计
- [RESPONSE_SEMANTICS_SPECIFICATION.md](./docs/architecture/RESPONSE_SEMANTICS_SPECIFICATION.md) - 三种安全链的响应格式约定
- [IDP_TECHNICAL_BLUEPRINT.md](./docs/architecture/IDP_TECHNICAL_BLUEPRINT.md) - 整体技术方案
- [FRONT_BACK_CHANNEL_LOGOUT.md](./docs/review/FRONT_BACK_CHANNEL_LOGOUT.md) - 统一登出方案

完整索引见 [DOCUMENT_NAVIGATION.md](./DOCUMENT_NAVIGATION.md)。

> AI生成