158 lines
4.1 KiB
Markdown
158 lines
4.1 KiB
Markdown
# OIDC Provider
|
||
|
||
OpenID Connect Provider 实现，支持标准的 OIDC 协议流程。
|
||
|
||
## 特性
|
||
|
||
- 完整的 OIDC 协议支持
|
||
- 密码认证策略
|
||
- 会话管理
|
||
- 令牌管理（访问令牌、刷新令牌、ID令牌）
|
||
- PKCE 支持
|
||
- 可自定义的存储适配器
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装
|
||
|
||
```bash
|
||
npm install @nice/oidc-provider
|
||
```
|
||
|
||
### 2. 配置
|
||
|
||
```typescript
|
||
import { createOIDCProvider } from '@nice/oidc-provider/middleware/hono';
|
||
import { MemoryStorageAdapter } from '@nice/oidc-provider/storage';
|
||
|
||
const config = {
|
||
issuer: 'https://your-domain.com',
|
||
signingKey: 'your-signing-key',
|
||
storage: new MemoryStorageAdapter(),
|
||
|
||
// 用户和客户端查找函数
|
||
findUser: async (userId: string) => {
|
||
// 从数据库查找用户
|
||
return await db.user.findUnique({ where: { id: userId } });
|
||
},
|
||
|
||
findClient: async (clientId: string) => {
|
||
// 从数据库查找客户端
|
||
return await db.client.findUnique({ where: { id: clientId } });
|
||
},
|
||
|
||
// 认证配置
|
||
authConfig: {
|
||
// 密码验证器
|
||
passwordValidator: async (username: string, password: string) => {
|
||
const user = await db.user.findUnique({ where: { username } });
|
||
if (user && await bcrypt.compare(password, user.hashedPassword)) {
|
||
return user.id;
|
||
}
|
||
return null;
|
||
},
|
||
|
||
// 会话配置
|
||
sessionTTL: 24 * 60 * 60, // 24小时
|
||
rememberMeMaxAge: 30 * 24 * 60 * 60, // 30天
|
||
|
||
// 页面配置
|
||
pageConfig: {
|
||
title: '用户登录',
|
||
brandName: '我的应用',
|
||
logoUrl: '/logo.png'
|
||
}
|
||
}
|
||
};
|
||
|
||
// 创建 OIDC Provider Hono 应用
|
||
const oidcApp = createOIDCProvider(config);
|
||
```
|
||
|
||
### 3. 集成到 Hono 应用
|
||
|
||
```typescript
|
||
import { Hono } from 'hono';
|
||
|
||
const app = new Hono();
|
||
|
||
// 挂载 OIDC Provider
|
||
app.route('/oidc', oidcApp);
|
||
|
||
export default app;
|
||
```
|
||
|
||
## API 端点
|
||
|
||
创建后的 OIDC Provider 将提供以下标准端点：
|
||
|
||
- `POST /login` - 用户登录
|
||
- `GET /logout` - 用户登出
|
||
- `POST /logout` - 用户登出（POST 方式）
|
||
- `GET /.well-known/openid-configuration` - OIDC 发现文档
|
||
- `GET /.well-known/jwks.json` - JSON Web Key Set
|
||
- `GET /auth` - 授权端点
|
||
- `POST /token` - 令牌端点
|
||
- `GET /userinfo` - 用户信息端点
|
||
- `POST /revoke` - 令牌撤销端点
|
||
- `POST /introspect` - 令牌内省端点
|
||
|
||
## 配置选项
|
||
|
||
### OIDCProviderConfig
|
||
|
||
| 字段 | 类型 | 必需 | 描述 |
|
||
|------|------|------|------|
|
||
| `issuer` | string | ✓ | 发行者标识符 |
|
||
| `signingKey` | string | ✓ | JWT 签名密钥 |
|
||
| `storage` | StorageAdapter | ✓ | 存储适配器 |
|
||
| `findUser` | function | ✓ | 用户查找函数 |
|
||
| `findClient` | function | ✓ | 客户端查找函数 |
|
||
| `authConfig` | AuthConfig | - | 认证配置 |
|
||
| `tokenTTL` | TokenTTLConfig | - | 令牌过期时间配置 |
|
||
|
||
### AuthConfig
|
||
|
||
| 字段 | 类型 | 必需 | 描述 |
|
||
|------|------|------|------|
|
||
| `passwordValidator` | function | - | 密码验证函数 |
|
||
| `sessionTTL` | number | - | 会话过期时间（秒） |
|
||
| `rememberMeMaxAge` | number | - | 记住我最长时间（秒） |
|
||
| `pageConfig` | PageConfig | - | 登录页面配置 |
|
||
|
||
### PageConfig
|
||
|
||
| 字段 | 类型 | 描述 |
|
||
|------|------|------|
|
||
| `title` | string | 登录页面标题 |
|
||
| `brandName` | string | 品牌名称 |
|
||
| `logoUrl` | string | Logo URL |
|
||
|
||
## 存储适配器
|
||
|
||
项目提供了多种存储适配器：
|
||
|
||
- `MemoryStorageAdapter` - 内存存储（适用于开发和测试）
|
||
- `RedisStorageAdapter` - Redis 存储
|
||
- `DatabaseStorageAdapter` - 数据库存储
|
||
|
||
### 自定义存储适配器
|
||
|
||
```typescript
|
||
import { StorageAdapter } from '@nice/oidc-provider/storage';
|
||
|
||
class CustomStorageAdapter implements StorageAdapter {
|
||
// 实现所需的方法
|
||
}
|
||
```
|
||
|
||
## 安全考虑
|
||
|
||
1. **签名密钥安全**：确保 `signingKey` 足够复杂且妥善保管
|
||
2. **HTTPS**：生产环境必须使用 HTTPS
|
||
3. **客户端验证**：实现严格的客户端验证逻辑
|
||
4. **密码策略**：在 `passwordValidator` 中实现适当的密码策略
|
||
|
||
## 许可证
|
||
|
||
MIT |