fenghuo/packages/oidc-provider/README.md

OIDC Provider

OpenID Connect Provider 实现，支持标准的 OIDC 协议流程。

特性

• 完整的 OIDC 协议支持
• 密码认证策略
• 会话管理
• 令牌管理（访问令牌、刷新令牌、ID令牌）
• PKCE 支持
• 可自定义的存储适配器

快速开始

1. 安装

npm install @nice/oidc-provider

2. 配置

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 应用

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 - 数据库存储

自定义存储适配器

import { StorageAdapter } from '@nice/oidc-provider/storage';

class CustomStorageAdapter implements StorageAdapter {
    // 实现所需的方法
}

安全考虑

1. 签名密钥安全：确保 signingKey 足够复杂且妥善保管
2. HTTPS：生产环境必须使用 HTTPS
3. 客户端验证：实现严格的客户端验证逻辑
4. 密码策略：在 passwordValidator 中实现适当的密码策略

许可证

MIT