# panda-auth

**Repository Path**: JXPanda/panda-auth

## Basic Information

- **Project Name**: panda-auth
- **Description**: 一个专注于身份验证和授权的开源项目，提供安全、灵活的认证解决方案，适用于多种应用场景。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Panda Auth

Panda Auth 是一个基于 Spring Security OAuth2 的响应式认证授权框架，专为 Spring Boot/WebFlux 应用设计。

## 模块介绍

### module-auth
核心认证模块，提供完整的 OAuth2 认证授权功能：

- **认证策略**：支持密码模式、验证码模式、微信小程序、微信开放平台等多种认证方式
- **Token 管理**：JWT Token 生成、刷新、交换
- **用户注册**：自动注册、绑定注册模式
- **端点**：OAuth2 令牌端点、JWK Set 端点、Token 交换端点

### module-auth-foundation
基础模型模块，包含：

- **实体模型**：Account、AccountAuth、AccountTenant、ClientRegistration、ClientRegistrationGrant
- **身份模型**：IdentityExtraction、IdentityIdentifier、IdentityResolution、RegistrationResult
- **仓储接口**：各实体对应的 Repository 接口
- **策略接口**：身份提取、标准化、解析、注册策略接口

### module-auth-resource-server
资源服务器支持模块，提供：

- **JWT Claims 注解**：便捷获取 JWT 声明中的用户信息
  - `@JwtClaimsSub` - subject
  - `@JwtClaimsUserId` - 用户 ID
  - `@JwtClaimsStaffId` - 员工 ID
  - `@JwtClaimsAccountId` - 账户 ID
  - `@JwtClaimsClientId` - 客户端 ID
  - `@JwtClaimsUsername` - 用户名
  - `@JwtClaimsEmail` - 邮箱
  - `@JwtClaimsPhone` - 手机号
  - `@JwtClaimsRoles` - 角色
  - `@JwtClaimsDataPermissions` - 数据权限
  - `@JwtClaimsScope` - 范围
- **配置属性**：资源服务器相关配置

Resource Server 推荐配置：

```yaml
panda:
  spring:
    auth:
      resource-server:
        jwk-set-uri: https://usercenter.example.com/usercenter/.well-known/jwks/starwalls.json
        issuer-uri: starship-usercenter
        audiences:
          - starwalls
        # 可省略；为空时默认复用 audiences 校验 clientId claim。
        client-ids:
          - starwalls
        validate-client-id-claim: true
```

资源服务会同时校验 JWT 签名、issuer、audience、过期时间，以及 Usercenter 写入的 `clientId` claim，避免 A 应用 Token 被误用于 B 应用。

### launcher
模拟启动器，用于测试和演示：

- **SQLite 模拟存储**：基于 SQLite 的内存模拟用户存储
- **模拟控制器**：提供当前用户信息查询接口

## 快速开始

### 添加依赖

```kotlin
// build.gradle.kts
implementation("com.jxpanda:panda-auth:版本号")
```

### 配置 application.yaml

```yaml
panda:
  spring:
    auth:
      # 开启 JWT Token
      token:
        jwt:
          enable: true
          issuer: your-issuer
          algorithm: ES384
      endpoint:
        oauth-token: /oauth2/token
        register: /oauth2/register
        token-exchange: /oauth2/exchange
        enable-jwk-set: true
        jwk-set: /.well-known/jwks.json
```

### 配置客户端注册

```yaml
panda:
  spring:
    auth:
      registration:
        local:
          - client-id: local-client
            client-secret: secret
            grant-type: password
            scope: read write
```

## 功能特性

### 支持的认证方式

| 认证方式 | 说明 |
|---------|------|
| password | 用户名密码认证 |
| captcha | 验证码认证 |
| wechat_mini_program | 微信小程序认证 |
| wechat_open_platform | 微信开放平台认证 |

### 支持的 Grant Type

- `password` - 密码模式
- `client_credentials` - 客户端凭证模式
- `refresh_token` - 刷新 Token
- `authorization_code` - 授权码模式（开发中）

### Token 交换

支持基于已认证的 JWT 交换到指定客户端或租户上下文的新访问令牌。

### 用户注册模式

- **自动注册**：自动创建用户
- **绑定注册**：需要绑定到已有账户

## 示例

### 获取 Access Token

```bash
curl -X POST http://localhost:8080/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=local-client" \
  -d "username=user@example.com" \
  -d "password=your-password"
```

### 刷新 Token

```bash
curl -X POST http://localhost:8080/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=local-client" \
  -d "refresh_token=your-refresh-token"
```

### Token 交换

```bash
curl -X POST http://localhost:8080/oauth2/exchange \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"target-client","tenant_id":"target-tenant"}'
```

## 许可证

本项目基于 Apache License 2.0 许可证开源。