Builder6 OIDC Client Module

Builder6 OIDC 客户端模块为 Builder6 平台提供 OpenID Connect (OIDC) 身份认证集成功能，支持通过外部身份提供者（IdP）进行单点登录（SSO）和用户认证。

功能特性

• OpenID Connect 认证: 支持标准的 OIDC 认证流程
• 单点登录 (SSO): 与企业身份提供者集成实现 SSO
• 多种认证流程: 支持授权码流程（Authorization Code Flow）
• 用户信息同步: 自动同步 OIDC 提供者的用户信息
• 会话管理: 管理用户会话和令牌刷新
• 移动端支持: 检测移动设备并提供优化的登录体验
• 安全令牌处理: 安全地处理访问令牌和刷新令牌

安装

npm install @builder6/oidc

或

yarn add @builder6/oidc

环境变量

OIDC 基本配置

# 启用 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

# 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

高级配置

# 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 应用中集成

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. 用户信息获取: 获取用户信息并创建会话

登录按钮示例

<!-- 前端登录按钮 -->
<a href="/api/v6/oidc/auth">使用 OIDC 登录</a>

在控制器中使用 OIDC 服务

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 配置

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 配置

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 配置

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 检测移动设备，并可以为移动端提供定制的登录体验：

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 文档

开发

构建

npm run build

监听模式

npm run build:watch

格式化代码

npm run format

使用场景

• 企业 SSO: 与企业身份提供者集成实现单点登录
• 社交登录: 通过 Google、Microsoft 等社交账号登录
• 多租户应用: 支持多个 OIDC 租户配置
• 零信任架构: 基于 OIDC 的现代身份认证架构

故障排查

常见问题

1. 重定向 URI 不匹配: 确保 B6_OIDC_REDIRECT_URI 与 IdP 中配置的回调 URL 完全一致
2. CORS 错误: 确保 IdP 允许应用的域名
3. 令牌验证失败: 检查 IdP 的签名算法配置
4. 用户信息获取失败: 确保请求的作用域包含必要的用户信息

License

MIT