@builder6/oidc 3.2.3 → 4.0.0

package/README.md

@@ -1,11 +1,264 @@
 # Builder6 OIDC Client Module
 
+Builder6 OIDC 客户端模块为 Builder6 平台提供 OpenID Connect (OIDC) 身份认证集成功能，支持通过外部身份提供者（IdP）进行单点登录（SSO）和用户认证。
 
-## Environment Variables
+## 功能特性
 
-```shell
+- **OpenID Connect 认证**: 支持标准的 OIDC 认证流程
+- **单点登录 (SSO)**: 与企业身份提供者集成实现 SSO
+- **多种认证流程**: 支持授权码流程（Authorization Code Flow）
+- **用户信息同步**: 自动同步 OIDC 提供者的用户信息
+- **会话管理**: 管理用户会话和令牌刷新
+- **移动端支持**: 检测移动设备并提供优化的登录体验
+- **安全令牌处理**: 安全地处理访问令牌和刷新令牌
+
+## 安装
+
+```bash
+npm install @builder6/oidc
+```
+
+或
+
+```bash
+yarn add @builder6/oidc
+```
+
+## 环境变量
+
+### OIDC 基本配置
+
+```bash
+# 启用 OIDC 认证
 B6_OIDC_ENABLED=true
+
+# OIDC 提供者的 Issuer URL
 B6_OIDC_ISSUER=https://id.steedos.cn/realms/master
+
+# OIDC 客户端 ID
 B6_OIDC_CLIENT_ID=steedos-oidc-public
-B6_OIDC_CLIENT_SECRET=none
+
+# OIDC 客户端密钥（如果是机密客户端）
+B6_OIDC_CLIENT_SECRET=your-client-secret
+
+# 重定向 URI（回调地址）
+B6_OIDC_REDIRECT_URI=http://localhost:5100/api/v6/oidc/callback
+
+# 登出后重定向 URI
+B6_OIDC_POST_LOGOUT_REDIRECT_URI=http://localhost:5100
+```
+
+### 高级配置
+
+```bash
+# OIDC 作用域（空格分隔）
+B6_OIDC_SCOPE=openid profile email
+
+# 响应类型
+B6_OIDC_RESPONSE_TYPE=code
+
+# 启用 PKCE（公共客户端推荐）
+B6_OIDC_PKCE_ENABLED=true
+
+# ID 令牌签名算法
+B6_OIDC_ID_TOKEN_SIGNED_RESPONSE_ALG=RS256
+
+# 用户信息端点认证方法
+B6_OIDC_USERINFO_SIGNED_RESPONSE_ALG=RS256
+```
+
+## 使用示例
+
+### 在 NestJS 应用中集成
+
+```typescript
+import { Module } from '@nestjs/common';
+import { OidcModule } from '@builder6/oidc';
+
+@Module({
+  imports: [OidcModule],
+})
+export class AppModule {}
+```
+
+### OIDC 认证流程
+
+1. **发起登录**: 用户访问登录页面
+2. **重定向到 IdP**: 应用重定向到 OIDC 提供者
+3. **用户认证**: 用户在 IdP 上完成认证
+4. **回调处理**: IdP 重定向回应用的回调地址
+5. **令牌交换**: 应用使用授权码交换访问令牌
+6. **用户信息获取**: 获取用户信息并创建会话
+
+### 登录按钮示例
+
+```html
+<!-- 前端登录按钮 -->
+<a href="/api/v6/oidc/auth">使用 OIDC 登录</a>
+```
+
+### 在控制器中使用 OIDC 服务
+
+```typescript
+import { OidcService } from '@builder6/oidc';
+
+constructor(private oidcService: OidcService) {}
+
+// 发起 OIDC 认证
+@Get('auth')
+async initiateAuth(@Res() res: Response) {
+  const authUrl = await this.oidcService.getAuthorizationUrl();
+  res.redirect(authUrl);
+}
+
+// 处理回调
+@Get('callback')
+async handleCallback(@Query('code') code: string, @Req() req: Request) {
+  const tokens = await this.oidcService.getTokens(code);
+  const userInfo = await this.oidcService.getUserInfo(tokens.access_token);
+  
+  // 创建用户会话
+  req.session.user = userInfo;
+  
+  return { success: true, user: userInfo };
+}
+
+// 登出
+@Get('logout')
+async logout(@Req() req: Request, @Res() res: Response) {
+  const logoutUrl = await this.oidcService.getLogoutUrl(
+    req.session.id_token
+  );
+  req.session.destroy();
+  res.redirect(logoutUrl);
+}
+```
+
+## API 端点
+
+模块提供以下主要 API 端点：
+
+- **GET `/api/v6/oidc/auth`**: 发起 OIDC 认证流程
+- **GET `/api/v6/oidc/callback`**: OIDC 回调处理端点
+- **GET `/api/v6/oidc/logout`**: OIDC 登出端点
+- **GET `/api/v6/oidc/userinfo`**: 获取当前用户信息
+
+## 支持的 OIDC 提供者
+
+该模块兼容任何符合 OpenID Connect 规范的身份提供者，包括但不限于：
+
+- **Keycloak**: 开源身份和访问管理解决方案
+- **Auth0**: 商业身份平台
+- **Okta**: 企业级身份管理
+- **Azure AD**: Microsoft Azure Active Directory
+- **Google Identity**: Google 身份服务
+- **自定义 OIDC 服务器**: 任何符合 OIDC 标准的服务
+
+## 配置示例
+
+### Keycloak 配置
+
+```bash
+B6_OIDC_ENABLED=true
+B6_OIDC_ISSUER=https://keycloak.example.com/realms/myrealm
+B6_OIDC_CLIENT_ID=builder6-client
+B6_OIDC_CLIENT_SECRET=your-secret
+B6_OIDC_REDIRECT_URI=http://localhost:5100/api/v6/oidc/callback
+```
+
+### Auth0 配置
+
+```bash
+B6_OIDC_ENABLED=true
+B6_OIDC_ISSUER=https://your-tenant.auth0.com
+B6_OIDC_CLIENT_ID=your-client-id
+B6_OIDC_CLIENT_SECRET=your-client-secret
+B6_OIDC_REDIRECT_URI=http://localhost:5100/api/v6/oidc/callback
+```
+
+### Azure AD 配置
+
+```bash
+B6_OIDC_ENABLED=true
+B6_OIDC_ISSUER=https://login.microsoftonline.com/your-tenant-id/v2.0
+B6_OIDC_CLIENT_ID=your-application-id
+B6_OIDC_CLIENT_SECRET=your-client-secret
+B6_OIDC_REDIRECT_URI=http://localhost:5100/api/v6/oidc/callback
 ```
+
+## 移动端支持
+
+模块使用 `ismobilejs` 检测移动设备，并可以为移动端提供定制的登录体验：
+
+```typescript
+import { isMobile } from '@builder6/oidc';
+
+if (isMobile(req)) {
+  // 提供移动端优化的登录流程
+}
+```
+
+## 安全特性
+
+- **PKCE 支持**: 增强公共客户端的安全性
+- **State 参数**: 防止 CSRF 攻击
+- **Nonce 验证**: 防止重放攻击
+- **令牌验证**: 自动验证 ID 令牌签名
+- **安全存储**: 令牌安全存储在服务器端会话中
+
+## 依赖项
+
+### 主要依赖
+
+- `openid-client`: ^5.7.1 - OpenID Connect 客户端库
+- `ejs`: ^3.1.10 - 模板引擎
+- `ismobilejs`: ^1.1.1 - 移动设备检测
+- `lodash`: ^4.17.21 - 工具函数库
+- `request-ip`: ^3.3.0 - IP 地址获取
+
+### Peer Dependencies
+
+- `@builder6/core`: ^3.0.10 - 核心功能模块
+- `@nestjs/common`: ^11.0.0 - NestJS 核心
+- `@nestjs/core`: ^11.0.0 - NestJS 核心
+- `@nestjs/swagger`: ^11.0.7 - API 文档
+
+## 开发
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 监听模式
+
+```bash
+npm run build:watch
+```
+
+### 格式化代码
+
+```bash
+npm run format
+```
+
+## 使用场景
+
+- **企业 SSO**: 与企业身份提供者集成实现单点登录
+- **社交登录**: 通过 Google、Microsoft 等社交账号登录
+- **多租户应用**: 支持多个 OIDC 租户配置
+- **零信任架构**: 基于 OIDC 的现代身份认证架构
+
+## 故障排查
+
+### 常见问题
+
+1. **重定向 URI 不匹配**: 确保 `B6_OIDC_REDIRECT_URI` 与 IdP 中配置的回调 URL 完全一致
+2. **CORS 错误**: 确保 IdP 允许应用的域名
+3. **令牌验证失败**: 检查 IdP 的签名算法配置
+4. **用户信息获取失败**: 确保请求的作用域包含必要的用户信息
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder6/oidc",
-  "version": "3.2.3",
+  "version": "4.0.0",
   "main": "dist/index.js",
   "license": "MIT",
   "files": [
@@ -19,7 +19,7 @@
     "request-ip": "^3.3.0"
   },
   "peerDependencies": {
-    "@builder6/core": "^3.0.10",
+    "@builder6/core": "^4.0.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/swagger": "^11.0.7"
@@ -27,5 +27,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "544e8b41e82e41a3a7534cd30219c00d60285c63"
+  "gitHead": "6d6e13fed8d4b3c6de14f84dcb6287c5661ea6f6"
 }