@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 byOidcInteractiveStrategyand@haneinfo/plugin-host-nest'sInteractiveAuthGuard). - IAM profile contract:
issuer,jwksUri(viagetTrustedMetadata()), signing algorithm allowlist (signingAlgorithms), and claim normalization (normalizeClaims('web', payload, header)) all come from the injectedIAM_PROFILE(IamProfilePort, capabilityhaneinfo.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 theIAM_PROFILEimplementation rather thanOIDC_AUDIENCEorazp === audience. - Token timestamp validation:
iatandexpbounds (clockToleranceSeconds,maxIssuedLifetimeSeconds) are enforced by@haneinfo/plugin-api'svalidateTokenTimestamps.
Migrating from 5.x to 6.0
Removed environment variables and exports
OIDC_ISSUER,OIDC_AUDIENCEandOIDC_JWKS_URLare no longer read.oidcAuthConfigFromEnvironmentis removed, andoidcAuthConfigSchemais nowz.object({}).strict().- The Passport path is removed:
OidcStrategy,JwtAuthGuard, and thepassport,passport-jwtand@nestjs/passportdependencies. UseInteractiveAuthGuardfrom@haneinfo/plugin-host-nestinstead. JwtVerifierService.buildOidcJwtUseris removed. It built a principal from an unverified payload.
New required capability
requiresnow includeshaneinfo.iam-profile(CAPABILITY_IAM_PROFILE), andengine.haneinfoPluginApiis^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 anoidcoption and no longer readsOIDC_JWKS_URL.DelegatedJwtVerifierServiceinjectsIAM_PROFILE. On the first verification it readsjwksUrifromgetTrustedMetadata()and checks it withvalidateDelegatedJwksUrl.- Apps must make
IAM_PROFILEinjectable throughoptions.imports, together withPrismaService,IDENTITY_STOREandAUDIT_SINK. - O3 startup gate:
DelegatedAuthModulechecksIAM_PROFILE.mcpCapabilities.delegationat startup and refuses to boot unless it istrue(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_ISSUEROIDC_AUDIENCEOIDC_JWKS_URL