fenghuo/packages/oidc-provider/examples/auto-keypair.md

OIDC Provider - 自动生成密钥对示例

现在OIDC Provider支持为RSA和ECDSA算法自动生成密钥对，无需手动提供。

基本用法

使用RSA算法（自动生成密钥对）

import { OIDCProvider } from '@your-package/oidc-provider';

// 直接使用构造函数创建Provider实例
const provider = new OIDCProvider({
    issuer: 'https://auth.example.com',
    signingAlgorithm: 'RS256', // 指定算法，密钥对将在首次使用时自动生成
    storage: storageAdapter,
    findUser: async (userId) => { /* 查找用户逻辑 */ },
    findClient: async (clientId) => { /* 查找客户端逻辑 */ },
    authConfig: {
        passwordValidator: async (username, password) => {
            // 验证用户名密码，返回用户ID或null
        }
    }
});

使用ECDSA算法（自动生成密钥对）

const provider = new OIDCProvider({
    issuer: 'https://auth.example.com',
    signingAlgorithm: 'ES256', // ECDSA算法，密钥对将在首次使用时自动生成
    storage: storageAdapter,
    findUser: async (userId) => { /* 查找用户逻辑 */ },
    findClient: async (clientId) => { /* 查找客户端逻辑 */ },
    authConfig: {
        passwordValidator: async (username, password) => {
            // 验证用户名密码，返回用户ID或null
        }
    }
});

使用HMAC算法（需要提供密钥）

const provider = new OIDCProvider({
    issuer: 'https://auth.example.com',
    signingKey: 'your-secret-key', // HS256必须提供密钥
    signingAlgorithm: 'HS256', // 可选，默认为HS256
    storage: storageAdapter,
    findUser: async (userId) => { /* 查找用户逻辑 */ },
    findClient: async (clientId) => { /* 查找客户端逻辑 */ },
    authConfig: {
        passwordValidator: async (username, password) => {
            // 验证用户名密码，返回用户ID或null
        }
    }
});

密钥生成时机

• 懒加载：密钥对将在首次调用需要签名的方法时自动生成（如生成token、获取JWKS等）
• 一次生成：每个Provider实例只会生成一次密钥对，后续调用会复用相同的密钥
• 控制台输出：自动生成密钥对时会在控制台输出确认信息

注意事项

1. 生产环境建议：在生产环境中，建议提前生成并持久化密钥对，而不是每次启动时重新生成
2. HS256算法：使用HS256时仍然需要提供signingKey
3. 同步构造：现在可以直接使用new OIDCProvider()构造函数，无需异步等待
4. 密钥轮换：如果需要密钥轮换，可以使用JWTUtils.generateRSAKeyPair()或JWTUtils.generateECDSAKeyPair()方法生成新的密钥对

手动提供密钥对

如果你想手动提供密钥对：

import { JWTUtils } from '@your-package/oidc-provider';

// 生成密钥对
const keyPair = await JWTUtils.generateRSAKeyPair('my-key-id');

const provider = new OIDCProvider({
    issuer: 'https://auth.example.com',
    signingKey: keyPair, // 手动提供密钥对
    signingAlgorithm: 'RS256',
    // ... 其他配置
});