# OneAuthCenter

**Repository Path**: csuffyy/one-auth-center

## Basic Information

- **Project Name**: OneAuthCenter
- **Description**: 基于 .NET 8 的企业级 OAuth 2.0 / OpenID Connect 认证中心
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 16
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OneAuthCenter - 认证中心

[![Gitee](https://img.shields.io/badge/Gitee-C71D23?style=flat&logo=gitee&logoColor=white)](https://gitee.com/caragana-esculenta/one-auth-center)
[![.NET](https://img.shields.io/badge/.NET-9.0-512BD4?style=flat&logo=dotnet&logoColor=white)](https://dotnet.microsoft.com/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

基于 .NET 9 的企业级 OAuth 2.0 / OpenID Connect 认证中心，采用 DDD 分层架构实现。

## 🔗 仓库地址

- **Gitee**: https://gitee.com/caragana-esculenta/one-auth-center

## 🏗️ 项目架构

本项目采用经典的四层架构设计，并提供客户端集成库：

```
OneAuthCenter/
├── src/                               # 源代码目录
│   ├── Extensions/                    # 🆕 扩展包源（Extensions Packages）
│   │   ├── OneAuthCenter.Client/      # 客户端集成库（可独立发布为 NuGet 包）
│   │   │   ├── Options/               # 配置选项
│   │   │   ├── Extensions/            # 扩展方法
│   │   │   └── README.md              # 客户端使用文档
│   │   └── README.md                  # 扩展包说明
│   │
│   ├── examples/                      # 🆕 集成示例项目
│   │   ├── OrdersApi/                 # 订单 API 示例
│   │   └── README.md                  # 示例使用说明
│   │
│   └── NoUI/                          # 后端项目（无UI）
│       ├── OneAuthCenter.Domain/      # 领域层
│       │   ├── Entities/              # 实体模型
│       │   │   ├── User.cs            # 用户实体
│       │   │   ├── Client.cs          # OAuth 客户端实体
│       │   │   ├── RefreshToken.cs    # 刷新令牌实体
│       │   │   ├── AuthorizationCode.cs # 授权码实体
│       │   │   ├── Scope.cs           # 作用域实体
│       │   │   └── UserConsent.cs     # 用户同意记录实体
│       │   └── Repositories/          # 仓储接口
│       │       ├── IUserRepository.cs
│       │       ├── IClientRepository.cs
│       │       ├── IRefreshTokenRepository.cs
│       │       ├── IAuthorizationCodeRepository.cs
│       │       ├── IScopeRepository.cs
│       │       └── IUserConsentRepository.cs
│       │
│       ├── OneAuthCenter.Application/ # 应用层
│       │   ├── DTOs/                  # 数据传输对象
│       │   │   ├── Auth/              # 认证相关 DTO
│       │   │   ├── OAuth/             # OAuth 相关 DTO
│       │   │   ├── Client/            # 客户端相关 DTO
│       │   │   └── User/              # 用户相关 DTO
│       │   └── Services/              # 服务接口和实现
│       │       ├── ITokenService.cs   # JWT Token 服务接口
│       │       ├── IAuthService.cs    # 认证服务接口
│       │       ├── IOAuthService.cs   # OAuth 服务接口
│       │       ├── IClientService.cs  # 客户端服务接口
│       │       ├── IUserService.cs    # 用户服务接口
│       │       └── Implementations/   # 服务实现
│       │
│       ├── OneAuthCenter.Infrastructure/ # 基础设施层
│       │   ├── Data/                  # 数据访问
│       │   │   ├── AuthDbContext.cs   # EF Core 数据库上下文
│       │   │   └── DbInitializer.cs   # 数据库初始化器
│       │   ├── Configuration/         # 配置类
│       │   │   └── DatabaseSettings.cs # 数据库配置
│       │   ├── Extensions/            # 扩展方法
│       │   │   └── ServiceCollectionExtensions.cs
│       │   ├── Repositories/          # 仓储实现
│       │   │   ├── UserRepository.cs
│       │   │   ├── ClientRepository.cs
│       │   │   ├── RefreshTokenRepository.cs
│       │   │   ├── AuthorizationCodeRepository.cs
│       │   │   ├── ScopeRepository.cs
│       │   │   └── UserConsentRepository.cs
│       │   └── Services/              # 基础设施服务
│       │       └── TokenService.cs    # JWT Token 生成和验证
│       │
│       └── OneAuthCenter.API/         # API 层（表现层）
│           ├── Controllers/           # API 控制器
│           │   ├── AuthController.cs  # 认证控制器
│           │   ├── OAuthController.cs # OAuth 2.0 控制器
│           │   ├── ClientController.cs # 客户端管理控制器
│           │   └── UserController.cs  # 用户管理控制器
│           ├── Program.cs             # 应用程序入口
│           └── appsettings.json       # 配置文件（含 Swagger 配置）
│
├── database-examples/                 # 数据库配置示例
├── README.md                          # 项目说明文档
├── SETUP.md                           # 安装配置指南
├── DATABASE_CONFIG.md                 # 数据库配置指南
├── PROJECT_STRUCTURE.md               # 项目结构详解
├── IDENTITYSERVER_CONCEPTS.md         # IdentityServer4 核心概念详解
├── JWT_CERTIFICATE.md                 # JWT 证书配置指南
├── CORS_TOKEN_CONFIG.md               # CORS 和 Token 配置指南
└── CHANGELOG.md                       # 更新日志
```

## ✨ 核心功能

### 📦 客户端集成库（OneAuthCenter.Client）

- ✅ **一行代码集成认证** - `builder.Services.AddOneAuthCenter()`
- ✅ **3 种配置方式**
  - 代码配置（适合开发环境）
  - 配置文件（适合生产环境）
  - 带 Scope 验证（快速配置）
- ✅ **自动 JWT 验证**
  - 自动从认证中心获取 JWKS
  - 自动验证 Token 签名
  - 自动验证 Issuer 和 Audience
- ✅ **灵活的授权策略**
  - 基于 Scope 的授权
  - 基于 Role 的授权
  - 自定义策略
- ✅ **开箱即用的示例**
  - OrdersApi 示例项目
  - 完整的使用文档
  - 最佳实践指南
- 📖 详见 [客户端集成文档](src/Extensions/OneAuthCenter.Client/README.md)

### 🔐 认证功能
- ✅ 用户注册与登录
- ✅ **JWT Token 生成和验证（完全模仿 IdentityServer4）**
  - 🔐 开发环境自动生成密钥并保存到 `tempkey.rsa`（类似 IdentityServer4 的 `tempkey.jwk`）
  - 🔐 应用重启后自动加载密钥，Token 不会失效
  - 🔐 动态 Issuer - 自动从 HTTP 请求获取（无需配置）
  - 🔐 生产环境使用证书文件（RSA 签名）
  - 📖 详见 [JWT 证书配置指南](JWT_CERTIFICATE.md)
- ✅ **完整的 Scope 权限验证**
  - ✅ OpenID Connect 标准 scopes（openid, profile, email, phone, address）
  - ✅ UserInfo 端点根据 scope 返回对应信息
  - ✅ Token 中包含 scope claims
  - 📖 详见 [IdentityServer4 核心概念](IDENTITYSERVER_CONCEPTS.md)
- ✅ 刷新令牌机制
- ✅ **完整的 Token 可用性验证**
  - ✅ Access Token 黑名单机制（JWT 撤销）
  - ✅ Refresh Token 撤销和过期检查
  - ✅ Token 唯一标识符 (jti claim)
  - ✅ 自动清理过期的黑名单记录
  - 📖 详见 [CORS 和 Token 配置指南](CORS_TOKEN_CONFIG.md)
- ✅ 令牌撤销和登出

### 🎫 OAuth 2.0 支持
- ✅ 授权码流程 (Authorization Code Flow)
- ✅ 客户端凭证流程 (Client Credentials Flow)
- ✅ 密码流程 (Resource Owner Password Credentials Flow)
- ✅ 刷新令牌流程 (Refresh Token Flow)
- ✅ PKCE 支持 (Proof Key for Code Exchange)

### 🌐 OpenID Connect 支持
- ✅ ID Token 生成
- ✅ UserInfo 端点
- ✅ Discovery 端点 (/.well-known/openid-configuration)
- ✅ **JWKS 端点** (/.well-known/jwks.json) - 公钥发布
- ✅ **Token Revocation 端点** (/oauth/revocation) - RFC 7009
- ✅ **Token Introspection 端点** (/oauth/introspect) - RFC 7662
- ✅ **End Session 端点** (/oauth/endsession) - 标准登出

### 👥 用户管理
- ✅ 用户 CRUD 操作
- ✅ 角色管理
- ✅ 密码修改
- ✅ 用户状态管理

### 📱 客户端管理
- ✅ OAuth 客户端注册
- ✅ 客户端配置管理
- ✅ 密钥重置
- ✅ 授权类型和作用域配置

### 🔒 安全特性
- ✅ **RSA 非对称加密签名**（类似 IdentityServer4）
  - 开发环境自动生成临时密钥
  - 生产环境支持证书文件
  - 支持 JWKS 公钥发布
- ✅ **BCrypt 密码哈希**（自适应、防彩虹表）
- ✅ **JWT Token 黑名单机制**（超越 IdentityServer4）
- ✅ PKCE (Proof Key for Code Exchange)
- ✅ 用户同意管理
- ✅ 令牌过期和轮换
- ✅ 客户端凭证验证
- ✅ 标准 Token 撤销和自省

## 🚀 快速开始

### 前置要求
- .NET 9 SDK
- 数据库（支持以下任意一种）：
  - SQL Server (或 SQL Server LocalDB) - 默认
  - MySQL / MariaDB
  - PostgreSQL
  - SQLite
  - Oracle Database
- Visual Studio 2022 或 JetBrains Rider

### 安装步骤

1. **克隆或打开项目**
   ```bash
   cd OneAuthCenter
   ```

2. **配置数据库连接**
   
   编辑 `OneAuthCenter.API/appsettings.json`，选择要使用的数据库：
   ```json
   {
     "DatabaseSettings": {
       "DatabaseType": "SqlServer",  // 可选: SqlServer, MySql, PostgreSql, Sqlite
       "ConnectionStrings": {
         "SqlServer": "Server=(localdb)\\mssqllocaldb;Database=OneAuthCenterDb;Trusted_Connection=True;MultipleActiveResultSets=true",
         "MySql": "Server=localhost;Database=OneAuthCenterDb;User=root;Password=yourpassword;",
         "PostgreSql": "Host=localhost;Database=OneAuthCenterDb;Username=postgres;Password=yourpassword;",
         "Sqlite": "Data Source=OneAuthCenter.db"
       }
     }
   }
   ```
   
   💡 **详细的数据库配置指南请查看 [DATABASE_CONFIG.md](DATABASE_CONFIG.md)**

3. **创建数据库迁移**
   ```bash
   cd src/NoUI/OneAuthCenter.API
   dotnet ef migrations add InitialCreate --project ../OneAuthCenter.Infrastructure
   ```

4. **应用数据库迁移**
   ```bash
   dotnet ef database update --project ../OneAuthCenter.Infrastructure
   ```

5. **运行项目**
   ```bash
   dotnet run --project src/NoUI/OneAuthCenter.API
   ```
   
   **首次启动会发生什么？**
   ```
   ✓ 使用 SQL Server 数据库
   ✓ 生成新的开发密钥并保存到 tempkey.rsa
   ✓ 使用开发环境 RSA 密钥签名（临时密钥，仅用于开发）
   ✓ CORS: 允许所有来源访问（AllowAll 模式）
   ```
   
   **后续启动：**
   ```
   ✓ 使用 SQL Server 数据库
   ✓ 从 tempkey.rsa 加载开发密钥
   ✓ 使用开发环境 RSA 密钥签名（临时密钥，仅用于开发）
   ✓ CORS: 允许所有来源访问（AllowAll 模式）
   ```
   
   > 💡 **提示**: 应用重启后 Token 不会失效，这是因为密钥被保存在 `tempkey.rsa` 文件中。

6. **访问 Swagger UI**
   
   打开浏览器访问：`https://localhost:5001` 或 `http://localhost:5000`

## 🆚 与 IdentityServer4 对比

| 特性 | IdentityServer4 | OneAuthCenter |
|------|----------------|--------------|
| **开发密钥** | tempkey.jwk | tempkey.rsa |
| **自动生成** | ✅ | ✅ |
| **自动加载** | ✅ | ✅ |
| **动态 Issuer** | ✅ | ✅ |
| **Discovery 端点** | ✅ | ✅ |
| **JWKS 端点** | ✅ | ✅ |
| **Token Introspection** | ✅ | ✅ |
| **Token Revocation** | ✅ | ✅ |
| **PKCE** | ✅ | ✅ |
| **Scope 验证** | ✅ | ✅ |
| **零配置启动** | ✅ | ✅ |
| **免费开源** | ❌ (商业授权) | ✅ (MIT) |
| **中文文档** | ❌ | ✅ |
| **多数据库** | ❌ | ✅ (5种) |

## 🗄️ 数据库支持

OneAuthCenter 支持多种数据库，通过配置文件即可切换：

| 数据库 | 状态 | 推荐场景 |
|--------|------|---------|
| SQL Server | ✅ 默认 | 企业级应用 |
| MySQL | ✅ 支持 | Web 应用 |
| PostgreSQL | ✅ 支持 | 企业级应用 |
| SQLite | ✅ 支持 | 开发/测试/小型应用 |
| Oracle Database | ✅ 支持 | 企业级应用 |

**快速切换数据库**：
```json
{
  "DatabaseSettings": {
    "DatabaseType": "MySql"  // 修改这里即可切换
  }
}
```

详细配置说明请查看 [DATABASE_CONFIG.md](DATABASE_CONFIG.md)

## 📚 API 端点

### 认证 API (`/api/auth`)
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/refresh` - 刷新令牌
- `POST /api/auth/revoke` - 撤销令牌
- `POST /api/auth/logout` - 用户登出

### OAuth 2.0 API (`/oauth`)
- `GET /oauth/authorize` - OAuth 授权端点
- `POST /oauth/consent` - 用户同意端点
- `POST /oauth/token` - Token 端点
- `GET /oauth/.well-known/openid-configuration` - OpenID Connect 发现端点

### 用户管理 API (`/api/user`)
- `GET /api/user/me` - 获取当前用户信息
- `GET /api/user/userinfo` - OpenID Connect UserInfo 端点
- `GET /api/user` - 获取所有用户（需管理员权限）
- `GET /api/user/{id}` - 获取指定用户
- `PUT /api/user/{id}` - 更新用户信息
- `DELETE /api/user/{id}` - 删除用户（需管理员权限）
- `POST /api/user/change-password` - 修改密码

### 客户端管理 API (`/api/client`)
- `GET /api/client` - 获取所有客户端（需管理员权限）
- `GET /api/client/{clientId}` - 获取指定客户端（需管理员权限）
- `POST /api/client` - 创建客户端（需管理员权限）
- `PUT /api/client/{clientId}` - 更新客户端（需管理员权限）
- `DELETE /api/client/{clientId}` - 删除客户端（需管理员权限）
- `POST /api/client/{clientId}/reset-secret` - 重置客户端密钥（需管理员权限）

## 🔧 配置说明

### JWT 配置
```json
{
  "JwtSettings": {
    "AccessTokenExpirationMinutes": 60,
    "RefreshTokenExpirationDays": 7,
    "SigningCertificate": {
      "UseTestCertificate": true  // 开发环境自动生成临时密钥
    }
  }
}
```

> **📌 说明**：
> - ✅ 使用 **RSA 非对称加密签名**（类似 IdentityServer4）
> - ✅ `Issuer` 和 `Audience` **动态获取**，无需配置
> - ✅ 开发环境自动生成 `tempkey.rsa` 文件（重启后密钥不变）
> - 📖 详见 [JWT 证书配置指南](JWT_CERTIFICATE.md)

## 📝 使用示例

### 1. 用户注册
```http
POST /api/auth/register
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "Password123!",
  "fullName": "测试用户"
}
```

### 2. 用户登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "username": "testuser",
  "password": "Password123!"
}
```

响应：
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "DRgb4TvHZe1qJZQbZ...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "openid profile email"
}
```

### 3. OAuth 2.0 授权码流程

**步骤 1：获取授权码**
```http
GET /oauth/authorize?
  response_type=code
  &client_id=client_app
  &redirect_uri=https://client.example.com/callback
  &scope=openid profile email
  &state=xyz
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
Authorization: Bearer {access_token}
```

**步骤 2：交换授权码获取令牌**
```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=授权码
&redirect_uri=https://client.example.com/callback
&client_id=client_app
&client_secret=client_secret
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

### 4. 刷新令牌
```http
POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "DRgb4TvHZe1qJZQbZ..."
}
```

## 🛡️ 安全建议

1. **生产环境配置**
   - 使用强密钥（至少 32 字符）
   - 启用 HTTPS (`RequireHttpsMetadata = true`)
   - 使用环境变量存储敏感信息
   - 配置适当的 CORS 策略

2. **数据库安全**
   - 使用强密码
   - 限制数据库访问权限
   - 定期备份数据库

3. **令牌管理**
   - 设置合理的令牌过期时间
   - 实施令牌轮换策略
   - 定期清理过期令牌

## 🧪 技术栈

- **.NET 9** - 应用框架
- **ASP.NET Core** - Web API 框架
- **Entity Framework Core 9** - ORM
- **多数据库支持** - SQL Server / MySQL / PostgreSQL / SQLite / Oracle
- **JWT Bearer Authentication** - RSA 签名认证
- **BCrypt.Net** - 密码哈希
- **Swashbuckle (Swagger)** - API 文档

## 📖 设计模式

- **仓储模式 (Repository Pattern)** - 数据访问抽象
- **依赖注入 (Dependency Injection)** - 解耦和可测试性
- **分层架构 (Layered Architecture)** - 关注点分离
- **DTO 模式** - 数据传输优化

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 贡献步骤

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 📞 联系方式

如有问题，请通过以下方式联系：
- 📮 提交 [Gitee Issue](https://gitee.com/caragana-esculenta/one-auth-center/issues)
- 📧 发送邮件至 84691873@qq.com
- 🌟 Star 本项目以示支持

## 🙏 致谢

感谢所有为本项目做出贡献的开发者！

## ⭐ Star 历史

如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！

## 📈 项目状态

- ✅ 已完成核心功能开发
- ✅ 已完成文档编写
- 🔄 持续维护和优化中
- 📝 欢迎提交 Issue 和 PR

---

**注意**：本项目是一个完整的认证中心实现，包含了 OAuth 2.0 和 OpenID Connect 的核心功能。在生产环境使用前，请确保进行充分的安全审计和测试。

**版本**: v1.3.0  
**最后更新**: 2025-11-01  
**维护状态**: 积极维护中 ✅