@haneinfo/oidc-auth

中文文档
6.0.1发布于 2026/11/17UNLICENSEDTypeScriptCommonJS近 30 天下载 5119

OIDC interactive authentication for Haneinfo apps: JWKS/RS256 verification, (issuer, subject) identity mapping, JIT provisioning and inbound delegated (RFC 8693) trust profiles.

原始使用文档
文档目录7 节
  1. Architecture (6.0)
  2. Migrating from 5.x to 6.0
  3. Removed environment variables and exports
  4. New required capability
  5. Changes to haneinfo.config.ts
  6. DelegatedAuthModule changes
  7. Not yet migrated (Phase 2 W7)

@haneinfo/oidc-auth

OIDC interactive authentication and inbound delegated (RFC 8693) token verification for Haneinfo NestJS apps.

Architecture (6.0)

  • Single interactive verification path: JwtVerifierService.verifyJwtToken(token) is the sole verification entry point for interactive bearer tokens (used by OidcInteractiveStrategy and @haneinfo/plugin-host-nest's InteractiveAuthGuard).
  • IAM profile contract: issuer, jwksUri (via getTrustedMetadata()), signing algorithm allowlist (signingAlgorithms), and claim normalization (normalizeClaims('web', payload, header)) all come from the injected IAM_PROFILE (IamProfilePort, capability haneinfo.iam-profile).
  • Audience & client separation: Web API audience (web.apiAudience) and Web RP client ID (web.clientId) come from the deployment configuration (IamDeploymentConfig) and are enforced by the IAM_PROFILE implementation rather than OIDC_AUDIENCE or azp === audience.
  • Token timestamp validation: iat and exp bounds (clockToleranceSeconds, maxIssuedLifetimeSeconds) are enforced by @haneinfo/plugin-api's validateTokenTimestamps.

Migrating from 5.x to 6.0

Removed environment variables and exports

  • OIDC_ISSUER, OIDC_AUDIENCE and OIDC_JWKS_URL are no longer read.
  • oidcAuthConfigFromEnvironment is removed, and oidcAuthConfigSchema is now z.object({}).strict().
  • The Passport path is removed: OidcStrategy, JwtAuthGuard, and the passport, passport-jwt and @nestjs/passport dependencies. Use InteractiveAuthGuard from @haneinfo/plugin-host-nest instead.
  • JwtVerifierService.buildOidcJwtUser is removed. It built a principal from an unverified payload.

New required capability

  • requires now includes haneinfo.iam-profile (CAPABILITY_IAM_PROFILE), and engine.haneinfoPluginApi is ^1.29.0.

Changes to haneinfo.config.ts

Set runtime.oidc to {}, then add @haneinfo/iam-keycloak/plugin, runtime.iam and iam.deployment. The @haneinfo/plugin-host-nest README has the details.

import { iamKeycloakPlugin } from '@haneinfo/iam-keycloak/plugin';
import { oidcAuthPlugin } from '@haneinfo/oidc-auth/plugin';
import type { IamDeploymentConfig } from '@haneinfo/plugin-api';
import { defineHaneinfoConfig } from '@haneinfo/plugin-host-nest';

// Single source of truth for profileId, issuer, capabilities, web.apiAudience and web.clientId.
const iamDeployment: IamDeploymentConfig = {
  /* ... */
};

export default defineHaneinfoConfig({
  inventory,
  plugins: [{ plugin: iamKeycloakPlugin }, { plugin: oidcAuthPlugin } /* , ... */],
  iam: { deployment: iamDeployment },
  runtime: {
    iam: iamDeployment,
    oidc: {},
  },
});

DelegatedAuthModule changes

  • DelegatedAuthModule.forFeature(options) no longer accepts an oidc option and no longer reads OIDC_JWKS_URL.
  • DelegatedJwtVerifierService injects IAM_PROFILE. On the first verification it reads jwksUri from getTrustedMetadata() and checks it with validateDelegatedJwksUrl.
  • Apps must make IAM_PROFILE injectable through options.imports, together with PrismaService, IDENTITY_STORE and AUDIT_SINK.
  • O3 startup gate: DelegatedAuthModule checks IAM_PROFILE.mcpCapabilities.delegation at startup and refuses to boot unless it is true (cross-app delegation O3 is not enabled, so delegated entry points must not be registered).

Not yet migrated (Phase 2 W7)

The template, the Apps and @haneinfo/app-tooling (for example packages/app-tooling/src/scaffold.ts and its tests) still use these names. They migrate in Phase 2 W7:

  • OIDC_ISSUER
  • OIDC_AUDIENCE
  • OIDC_JWKS_URL

版本与发布记录

@haneinfo/oidc-auth 共发布 38 个版本,首次发布于 2026/10/02;过去 12 个月发布了 38 个版本。

版本发布日期距今
6.0.1latest2026/11/17今天
6.0.02026/11/161 天前
5.1.312026/11/0412 天前
5.1.302026/11/0214 天前
5.1.292026/11/0115 天前
5.1.282026/10/3017 天前

关于 @haneinfo/oidc-auth 的常见问题

@haneinfo/oidc-auth 是什么?

OIDC interactive authentication for Haneinfo apps: JWKS/RS256 verification, (issuer, subject) identity mapping, JIT provisioning and inbound delegated (RFC 8693) trust profiles.

如何安装 @haneinfo/oidc-auth?

在项目目录运行 npm install @haneinfo/oidc-auth,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:zod(^4.4.0)、@nestjs/core(^11.0.0 || ^12.0.0)、@nestjs/common(^11.0.0 || ^12.0.0)、@prisma/client(^6.19.0 || ^7.10.1)、@haneinfo/common(^0.6.1 || ^0.7.0)、@haneinfo/plugin-host-nest(^2.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@haneinfo/oidc-auth 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@haneinfo/oidc-auth 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@haneinfo/oidc-auth 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@haneinfo/oidc-auth 可以商用吗?

@haneinfo/oidc-auth 使用 UNLICENSED 许可。作者声明为 UNLICENSED,即不授予公开使用许可(与公共领域的 Unlicense 不同)。使用前需获得作者授权。以上为概括,不构成法律意见,请以许可原文为准。

@haneinfo/oidc-auth 的下载量有多少?

根据 npm 官方下载统计,@haneinfo/oidc-auth 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,119 次,日均约 171 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@haneinfo/oidc-auth 还在维护吗?

最新版本 6.0.1 发布于 2026/11/17(今天);至今共发布 38 个版本,其中过去 12 个月发布了 38 个;首次发布于 2026/10/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。