# zest-auth

**Repository Path**: zestcc/zest-auth

## Basic Information

- **Project Name**: zest-auth
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zest Auth

Zest 生态**统一多租户与权限治理层**：管控面 Admin + 可嵌入 SDK（离线 Bundle / 在线同步）。

## 架构

```text
zest-auth/
├── zest-auth-common           # ApiResponse、Bundle Schema、异常
├── zest-auth-spi              # Identity / ConfigTransport / TenantResolver SPI
├── zest-auth-core             # AuthRuntime、JWT、AuthHttpClient、权限评估
├── zest-auth-starter          # Spring Boot 一键接入
├── plugins/
│   ├── zest-auth-identity-local   # JWT + 本地用户解析
│   ├── zest-auth-identity-sso     # ZestSSO 插件（SPI 扩展点）
│   ├── zest-auth-identity-ldap    # LDAP/AD 认证插件
│   ├── zest-auth-identity-github  # GitHub OAuth2 登录插件
│   ├── zest-auth-identity-google  # Google OAuth2 登录插件
│   ├── zest-auth-identity-saml    # SAML 2.0 SP 插件
│   ├── zest-auth-config-file      # 离线 Bundle 文件
│   ├── zest-auth-config-http      # 在线 HTTP 拉取
│   ├── zest-auth-alert-monitor    # 告警 SPI（打通 zest-monitor）
│   └── zest-auth-metrics-prometheus # Prometheus Micrometer SPI
├── zest-auth-admin            # 管控面（8095，单 jar + 内嵌 UI）
├── zest-auth-admin-ui         # Vue3 + Element Plus
└── zest-auth-demo             # SDK 示范应用（8096）
```

## Admin 完整能力

| 模块 | 功能 |
|------|------|
| 租户 | CRUD、允许产品 |
| 用户 | CRUD、角色绑定、重置密码、强制改密、自定义属性、CSV 导出 |
| 团队/组织 | 树形层级 CRUD、成员角色、团队负责人、邀请码、主团队 |
| 角色 | CRUD、权限绑定、团队上下文角色 |
| 权限 | CRUD（product/resource/action）、资源级权限、拒绝规则 |
| 产品 | 注册、角色映射规则 |
| Bundle | 预览 / 发布 / 历史版本 / 回滚 |
| SDK Token | 生成 / 吊销（`X-Auth-Token`） |
| OAuth2 | 授权服务器（Authorization Code / Client Credentials）、授权码流程、同意页 |
| 试验场 | SDK 接入向导（就绪检查 + YAML 片段）+ 在线探测 + Demo 联调验证 |
| 审计日志 | Admin 写操作自动记录 + 列表查询、团队/资源上下文 |
| 权限矩阵 | 角色 × 权限可视化矩阵（可勾选编辑，变更后需发布 Bundle） |
| 矩阵自动同步 | 系统设置中开启后，权限矩阵勾选变更自动发布 Bundle |
| SSO 联调 | 管控台「SDK 设置 → ZestSSO 联调」配置 Issuer / Client / Redirect |
| 社交登录 | GitHub / Google OAuth2 登录 + 账号绑定 |
| SAML 2.0 SP | 企业 SAML SSO，支持 SP-initiated 和 IdP-initiated |
| 登录安全 | 登录限流（内存/Redis）、密码策略、MFA（TOTP）、异动监测 |
| 会话管理 | Token 版本化、SPI 会话存储（内存/Redis）、主动吊销 |
| 品牌配置 | 名称、Logo、主色、登录页标题/背景/页脚自定义 |
| LDAP/AD | LDAP 和 Active Directory 认证 |
| 密码无感 | Magic Link 无密码登录 |
| 用户模拟 | 管理员模拟登录用户、审计追溯 |
| Webhook | SPI 事件钩子、Webhook 通知 |
| API 限流 | SPI API 频率限制（支持内存/Redis） |
| 配置导入导出 | JSON 配置全量导出/导入 |
| CORS 配置 | 可配置跨域来源、方法、凭证、缓存时间 |
| 监控告警 | Prometheus Micrometer 指标 + Alert SPI |

## SSO 联调（ZestSSO）

Demo 模块可选启用 SSO 插件：

```yaml
# application-zest-sso.yml（见 application-zest-sso.example.yml）
zest.sso.client.enabled: true
zest.sso.client.issuer: http://127.0.0.1:9000
```

| 端点 | 说明 |
|------|------|
| `GET /api/demo/sso/status` | SSO 联调状态 |
| `GET /api/demo/sso/authorize` | 浏览器 OIDC 跳转（PKCE）→ IdP 登录 |
| `GET /api/demo/sso/callback` | IdP 回调，签发 SDK JWT 后跳转 success 页 |
| `POST /api/demo/sso/login` | `{ "idToken": "..." }` → SDK JWT（集成测试 / 脚本用） |

管控台 **SDK 设置 → ZestSSO 联调** 可保存 Issuer / Client ID / Redirect URI，并一键打开 Demo 登录入口。

冒烟：`scripts/sso-integration-smoke.ps1`（含 WireMock E2E 单测）

## 双模 SDK

| 模式 | 配置 | 说明 |
|------|------|------|
| offline | `zest.auth.mode=offline` | 本地 Bundle + BCrypt 离线登录 |
| online | `zest.auth.mode=online` | 定时拉取 + 远程登录；Admin 冷启动不可达时 fallback classpath Bundle |
| hybrid | `zest.auth.mode=hybrid` | **推荐生产**：在线优先，Admin 不可达时可降级离线 |

### 导入即用（Starter 内置）

| 端点 | 说明 |
|------|------|
| `POST /zest-auth/login` | 登录拿 JWT（`zest.auth.controller.enabled=true`，默认开） |
| `GET /zest-auth/me` | 当前用户 |
| `GET /zest-auth/product-roles` | 产品角色映射 |
| `GET /zest-auth/health` | mode / bundleVersion / adminReachable |

仅引入 `zest-auth-starter` 依赖即可使用上述端点；开发环境 JWT Secret 默认与 Admin 对齐。

### 业务接入零配置异常处理

引入 `zest-auth-starter` 后自动注册 `AuthExceptionHandler`，`@RequirePermission` 失败统一返回 401/403。

## 快速开始

### 方式 A：零 MySQL（推荐本地试用）

无需安装 MySQL，使用 H2 嵌入式数据库：

```powershell
cd zest-auth
powershell -ExecutionPolicy Bypass -File .\scripts\dev-h2-up.ps1
```

- 控制台：http://localhost:8095（`admin` / `admin123`）
- H2 控制台：http://localhost:8095/h2-console（JDBC URL 见 `application-dev-h2.yml`）
- 数据持久化：`./data/zest_auth_dev.mv.db`（相对启动目录）

> `dev-h2` 仅用于本地开发，生产请使用 MySQL。

### 方式 B：MySQL

```sql
CREATE DATABASE zest_auth DEFAULT CHARSET utf8mb4;
```

```bash
cd zest-auth
mvn install -DskipTests
java -jar zest-auth-admin/target/zest-auth-admin-1.0.0-SNAPSHOT.jar
```

- 控制台：http://localhost:8095
- 默认账号：`admin` / `admin123`

```powershell
# 一键 Quickstart（编译 + 单测 + 结构门禁）
powershell -ExecutionPolicy Bypass -File .\scripts\quickstart.ps1
```

### Docker Compose 一键栈

需本机已安装 Docker Desktop：

```powershell
# 构建并启动 MySQL + Admin(8095) + Demo(8096)
powershell -ExecutionPolicy Bypass -File .\scripts\compose-up.ps1 -Build

# 仅启动（已构建镜像）
powershell -ExecutionPolicy Bypass -File .\scripts\compose-up.ps1
```

- Admin：http://localhost:8095（`admin` / `admin123`）
- Demo SSO 浏览器登录：http://localhost:8096/api/demo/sso/authorize（需 ZestSSO IdP 与 Demo 中 `zest.sso.client.*` 配置一致）

Compose 定义见 `deploy/docker-compose.yml`。

## 业务接入

```xml
<dependency>
  <groupId>cn.zest.auth</groupId>
  <artifactId>zest-auth-starter</artifactId>
  <version>1.0.0-SNAPSHOT</version>
</dependency>
```

配置见 `zest-auth-starter/src/main/resources/application-zest-auth.example.yml`  
生态接入详见 [docs/INTEGRATION.md](docs/INTEGRATION.md)  
**注意**：`zest.auth.jwt.secret` 须与 Admin 的 `zest.auth.admin.sdk-jwt-secret` 一致。

```java
@Autowired AuthRuntime authRuntime;
@Autowired AuthHttpClient authHttpClient;  // 远程 API 封装

@RequirePermission("order:create")
public void createOrder() { ... }
```

## SDK 开放 API（在线能力）

| 接口 | 说明 |
|------|------|
| `GET /api/v1/bundle?sinceVersion=` | 增量拉取 Bundle |
| `POST /api/v1/auth/login` | 远程登录（返回 SDK JWT） |
| `POST /api/v1/auth/verify` | 校验 Token |
| `POST /api/v1/auth/check` | 权限检查 |
| `GET /api/v1/auth/me` | 当前主体 |

请求头：`X-Auth-Token: <SDK Token>`

## 与 ZestSSO

Zest Auth **不替代 IdP**，提供 Bundle 契约 + 权限 SDK。ZestSSO 通过 `zest-auth-identity-sso` 插件接入。

## 端口

| 组件 | 端口 |
|------|------|
| Admin | 8095 |
| Demo | 8096 |
| Admin UI dev | 5295 |
| 默认账号 | `admin` / `admin123` |

## CORS 配置

Admin 内置可配置 CORS，通过 `application.yml` 调整：

```yaml
zest:
  auth:
    admin:
      cors-enabled: true                    # 是否启用 CORS（默认 true）
      cors-allowed-origins: ""              # 允许的来源，空则允许所有；逗号分隔
      cors-allowed-methods: "GET,POST,PUT,DELETE,PATCH,OPTIONS"
      cors-allow-credentials: true          # 是否允许携带凭证
      cors-max-age: 3600                    # 预检缓存时间（秒）
```

生产环境建议配置明确的 `cors-allowed-origins`，如 `https://admin.example.com`。

## 社交登录插件

Zest Auth 通过 SPI 插件支持多种社交/企业登录方式：

| 插件 | 身份提供商 | 配置前缀 |
|------|-----------|---------|
| identity-github | GitHub OAuth App | `zest.auth.identity.github` |
| identity-google | Google OAuth 2.0 | `zest.auth.identity.google` |
| identity-ldap | LDAP / Active Directory | `zest.auth.identity.ldap` |
| identity-saml | SAML 2.0 IdP（如 Okta、Azure AD） | `zest.auth.identity.saml` |
| identity-sso | ZestSSO OIDC | `zest.sso.client` |

社交/企业登录回调统一由 `POST /api/auth/social/{provider}/callback` 处理，支持自动账号关联和新用户创建。

## OAuth2 授权服务器

Zest Auth 内建 OAuth2 授权服务器支持：

- **授权码模式**（Authorization Code）：支持 PKCE
- **客户端凭证模式**（Client Credentials）
- **OIDC Discovery**：`/.well-known/openid-configuration`
- **同意页面**：用户首次授权需在同意页确认
- **Token 管理**：Admin UI 可查看和吊销已签发的 Token