nestjs-keycloak-auth 1.0.0

package/dist/interface/keycloak-auth-options.interface.d.ts

@@ -0,0 +1,162 @@
+import { PolicyEnforcementMode, RoleMerge, TokenValidation } from '../constants';
+export type KeycloakAuthOptions = string | KeycloakAuthConfig;
+/**
+ * Multi tenant configuration.
+ */
+export interface MultiTenantOptions {
+    /**
+     * Option to always resolve the realm and secret. Disabled by default.
+     */
+    resolveAlways?: boolean;
+    /**
+     * The realm resolver function.
+     */
+    realmResolver: (request: unknown) => Promise<string> | string;
+    /**
+     * The realm secret resolver function.
+     */
+    realmSecretResolver?: (realm: string, request?: unknown) => Promise<string> | string;
+    /**
+     * The realm auth server url resolver function.
+     */
+    realmAuthServerUrlResolver?: (realm: string, request?: unknown) => Promise<string> | string;
+    /**
+     * The realm client id resolver function.
+     */
+    realmClientIdResolver: (realm: string, request?: unknown) => Promise<string> | string;
+}
+/**
+ * Library only configuration.
+ */
+export interface NestKeycloakConfig {
+    /**
+     * Sets the policy enforcement mode for this adapter, defaults to {@link PolicyEnforcementMode.PERMISSIVE}.
+     */
+    policyEnforcement?: PolicyEnforcementMode;
+    /**
+     * Sets the token validation method, defaults to {@link TokenValidation.ONLINE}.
+     */
+    tokenValidation?: TokenValidation;
+    /**
+     * Multi tenant options.
+     */
+    multiTenant?: MultiTenantOptions;
+    /**
+     * Role merging options.
+     */
+    roleMerge?: RoleMerge;
+}
+/**
+ * Keycloak Connect options.
+ * @see {@link https://github.com/keycloak/keycloak-nodejs-connect/blob/f8e011aea5/middleware/auth-utils/config.js}
+ */
+export interface KeycloakAuthConfig extends NestKeycloakConfig {
+    /**
+     * Realm ID.
+     */
+    realm?: string;
+    /**
+     * Client/Application ID.
+     */
+    resource?: string;
+    /**
+     * Client/Application ID.
+     * @see {KeycloakAuthOptions#resource}
+     */
+    'client-id'?: string;
+    /**
+     * Client/Application ID.
+     * @see {KeycloakAuthOptions#resource}
+     */
+    clientId?: string;
+    /**
+     * Client/Application secret.
+     */
+    credentials?: KeycloakCredentials;
+    /**
+     * Client/Application secret.
+     * @see {KeycloakCredentials#secret}
+     */
+    secret: string;
+    /**
+     * If this is a public application or confidential.
+     * @see {KeycloakAuthOptions#public}
+     */
+    'public-client'?: boolean;
+    /**
+     * If this is a public application or confidential.
+     */
+    public?: boolean;
+    /**
+     * Authentication server URL.
+     * @see {KeycloakAuthOptions#authServerUrl}
+     */
+    'auth-server-url'?: string;
+    /**
+     * Authentication server URL.
+     * @see {KeycloakAuthOptions#authServerUrl}
+     */
+    'server-url'?: string;
+    /**
+     * Authentication server URL.
+     * @see {KeycloakAuthOptions#authServerUrl}
+     */
+    serverUrl?: string;
+    /**
+     * Authentication server URL.
+     */
+    authServerUrl?: string;
+    /**
+     * How many minutes before retrying getting the keys.
+     * @see {KeycloakAuthOptions#minTimeBetweenJwksRequests}
+     */
+    'min-time-between-jwks-requests'?: number;
+    /**
+     * How many minutes before retrying getting the keys.
+     */
+    minTimeBetweenJwksRequests?: number;
+    /**
+     * If this is a Bearer Only application.
+     * @see {KeycloakAuthOptions#bearerOnly}
+     */
+    'bearer-only'?: boolean;
+    /**
+     * If this is a Bearer Only application.
+     */
+    bearerOnly?: boolean;
+    /**
+     * Formatted public-key.
+     * @see {KeycloakAuthOptions#realmPublicKey}
+     */
+    'realm-public-key'?: string;
+    /**
+     * Formatted public-key.
+     */
+    realmPublicKey?: string;
+    /**
+     * Verify token audience.
+     * @see {KeycloakAuthOptions#verifyTokenAudience}
+     */
+    'verify-token-audience'?: boolean;
+    /**
+     * Verify token audience.
+     */
+    verifyTokenAudience?: boolean;
+    /**
+     * Confidential port.
+     */
+    'confidential-port'?: string | number;
+    /**
+     * Require SSL.
+     */
+    'ssl-required'?: string;
+}
+/**
+ * Represents Keycloak credentials.
+ */
+export interface KeycloakCredentials {
+    /**
+     * Client/Application secret.
+     */
+    secret: string;
+}

package/dist/interface/keycloak-auth-options.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+// The typings are a bit of a mess, I'm sure there's a better way to do this.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/keycloak-grant.interface.d.ts

@@ -0,0 +1,33 @@
+export interface KeycloakGrantResponse {
+    access_token: string;
+    expires_in: number;
+    token_type: string;
+    refresh_token?: string;
+    id_token?: string;
+    refresh_expires_in?: number;
+    scope?: string;
+    'not-before-policy'?: number;
+    session_state?: string;
+}
+export interface KeycloakUserInfoResponse {
+    sub: string;
+    name?: string;
+    preferred_username?: string;
+    given_name?: string;
+    family_name?: string;
+    email?: string;
+    email_verified?: boolean;
+    [key: string]: unknown;
+}
+export interface PermissionCheckOptions {
+    claims?: Record<string, unknown>;
+    response_mode?: 'decision' | 'permissions' | 'token';
+    audience?: string;
+    subject_token?: string;
+    isPublic?: boolean;
+}
+export interface KeycloakPermission {
+    rsid?: string;
+    rsname?: string;
+    scopes?: string[];
+}

package/dist/interface/keycloak-grant.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/keycloak-request.interface.d.ts

@@ -0,0 +1,8 @@
+export interface KeycloakRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    user?: Record<string, unknown>;
+    accessToken?: string;
+    scopes?: string[];
+    permissions?: unknown[];
+    [key: string]: unknown;
+}

package/dist/interface/keycloak-request.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/oidc.interface.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Discovered OIDC endpoint URLs from .well-known/openid-configuration.
+ */
+export interface OidcEndpoints {
+    jwks_uri: string;
+    token_endpoint: string;
+    introspection_endpoint: string;
+    userinfo_endpoint: string;
+    end_session_endpoint: string;
+}
+export interface CachedDiscovery {
+    endpoints: OidcEndpoints;
+    fetchedAt: number;
+}

package/dist/interface/oidc.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/server.interface.d.ts

@@ -0,0 +1,9 @@
+export interface ServerResponse {
+    status(code: number): ServerResponse;
+    send(data: string): void;
+}
+export interface ServerRequest {
+    body?: unknown;
+    rawBody?: unknown;
+    [key: string]: unknown;
+}

package/dist/interface/server.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interface/tenant-config.interface.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolved tenant configuration — plain data replacing keycloak-connect's Keycloak instance.
+ */
+export interface ResolvedTenantConfig {
+    authServerUrl: string;
+    realm: string;
+    clientId: string;
+    secret: string;
+    realmUrl: string;
+    realmAdminUrl: string;
+    isPublic: boolean;
+    bearerOnly: boolean;
+}

package/dist/interface/tenant-config.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/internal.util.d.ts

@@ -0,0 +1,13 @@
+import { ExecutionContext } from '@nestjs/common';
+import { ResolvedTenantConfig } from './interface/tenant-config.interface';
+import { KeycloakRequestLike } from './interface/keycloak-request.interface';
+import { KeycloakAuthConfig } from './interface/keycloak-auth-options.interface';
+import { KeycloakMultiTenantService } from './services/keycloak-multitenant.service';
+export { KeycloakRequestLike };
+/**
+ * Resolves the tenant configuration for the current request.
+ * For multi-tenant: uses the realm resolver or extracts realm from JWT issuer.
+ * For single-tenant: returns the provided default config.
+ */
+export declare const useTenantConfig: (request: KeycloakRequestLike, jwt: string | undefined, singleTenantConfig: ResolvedTenantConfig, multiTenant: KeycloakMultiTenantService, opts: KeycloakAuthConfig) => Promise<ResolvedTenantConfig>;
+export declare const extractRequest: (context: ExecutionContext) => [KeycloakRequestLike | undefined, unknown];

package/dist/internal.util.js

@@ -0,0 +1,54 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRequest = exports.useTenantConfig = void 0;
+const util_1 = require("./util");
+/**
+ * Resolves the tenant configuration for the current request.
+ * For multi-tenant: uses the realm resolver or extracts realm from JWT issuer.
+ * For single-tenant: returns the provided default config.
+ */
+const useTenantConfig = (request, jwt, singleTenantConfig, multiTenant, opts) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    if (opts.multiTenant && opts.multiTenant.realmResolver) {
+        const resolvedRealm = opts.multiTenant.realmResolver(request);
+        const realm = resolvedRealm instanceof Promise ? yield resolvedRealm : resolvedRealm;
+        return yield multiTenant.get(realm, request);
+    }
+    else if (!opts.realm) {
+        if (!jwt) {
+            return singleTenantConfig;
+        }
+        try {
+            const payload = (0, util_1.parseToken)(jwt);
+            const issuerRealm = (_a = payload.iss) === null || _a === void 0 ? void 0 : _a.split('/').pop();
+            if (issuerRealm) {
+                return yield multiTenant.get(issuerRealm, request);
+            }
+        }
+        catch (_b) {
+            // Fall back to the default config when issuer parsing fails.
+            return singleTenantConfig;
+        }
+    }
+    return singleTenantConfig;
+});
+exports.useTenantConfig = useTenantConfig;
+const extractRequest = (context) => {
+    if (context.getType() === 'http') {
+        const httpContext = context.switchToHttp();
+        const request = httpContext.getRequest();
+        const response = httpContext.getResponse();
+        return [request, response];
+    }
+    return [undefined, undefined];
+};
+exports.extractRequest = extractRequest;

package/dist/keycloak-auth.module.d.ts

@@ -0,0 +1,54 @@
+import { DynamicModule, Logger } from '@nestjs/common';
+import { KeycloakAuthOptions, NestKeycloakConfig } from './interface/keycloak-auth-options.interface';
+import { KeycloakAuthModuleAsyncOptions } from './interface/keycloak-auth-module-async-options.interface';
+export * from './constants';
+export * from './decorators/access-token.decorator';
+export * from './decorators/enforcer-options.decorator';
+export * from './decorators/keycloak-user.decorator';
+export * from './decorators/public.decorator';
+export * from './decorators/resource.decorator';
+export * from './decorators/roles.decorator';
+export * from './decorators/scopes.decorator';
+export * from './decorators/token-scopes.decorator';
+export * from './guards/auth.guard';
+export * from './guards/resource.guard';
+export * from './guards/role.guard';
+export * from './interface/jwt.interface';
+export * from './interface/keycloak-auth-module-async-options.interface';
+export * from './interface/keycloak-auth-options-factory.interface';
+export * from './interface/keycloak-auth-options.interface';
+export * from './interface/keycloak-request.interface';
+export * from './interface/oidc.interface';
+export * from './interface/server.interface';
+export * from './interface/tenant-config.interface';
+export * from './interface/enforcer-options.interface';
+export * from './interface/jwks.interface';
+export * from './interface/keycloak-grant.interface';
+export * from './services/keycloak-multitenant.service';
+export * from './services/oidc-discovery.service';
+export * from './services/keycloak-http.service';
+export * from './services/keycloak-url.service';
+export * from './services/keycloak-grant.service';
+export * from './services/jwks-cache.service';
+export * from './services/token-validation.service';
+export * from './services/backchannel-logout.service';
+export * from './services/keycloak-admin.service';
+export * from './controllers/keycloak-admin.controller';
+export * from './token/keycloak-token';
+export * from './token/keycloak-grant';
+export * from './types/conditional-scope.type';
+export * from './errors';
+export * from './util';
+export declare class KeycloakAuthModule {
+    static logger: Logger;
+    /**
+    * Register the `KeycloakAuth` module.
+    * @param opts `keycloak.json` path in string or {@link NestKeycloakConfig} object.
+    * @param config {@link NestKeycloakConfig} when using `keycloak.json` path, optional
+    * @returns
+    */
+    static register(opts: KeycloakAuthOptions, config?: NestKeycloakConfig): DynamicModule;
+    static registerAsync(opts: KeycloakAuthModuleAsyncOptions): DynamicModule;
+    private static createAsyncProviders;
+    private static createAsyncOptionsProvider;
+}

package/dist/keycloak-auth.module.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var KeycloakAuthModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeycloakAuthModule = void 0;
+const axios_1 = require("@nestjs/axios");
+const jwks_cache_service_1 = require("./services/jwks-cache.service");
+const keycloak_http_service_1 = require("./services/keycloak-http.service");
+const keycloak_grant_service_1 = require("./services/keycloak-grant.service");
+const oidc_discovery_service_1 = require("./services/oidc-discovery.service");
+const keycloak_admin_service_1 = require("./services/keycloak-admin.service");
+const common_1 = require("@nestjs/common");
+const token_validation_service_1 = require("./services/token-validation.service");
+const constants_1 = require("./constants");
+const backchannel_logout_service_1 = require("./services/backchannel-logout.service");
+const keycloak_admin_controller_1 = require("./controllers/keycloak-admin.controller");
+const keycloak_multitenant_service_1 = require("./services/keycloak-multitenant.service");
+const keycloak_auth_providers_1 = require("./keycloak-auth.providers");
+__exportStar(require("./constants"), exports);
+__exportStar(require("./decorators/access-token.decorator"), exports);
+__exportStar(require("./decorators/enforcer-options.decorator"), exports);
+__exportStar(require("./decorators/keycloak-user.decorator"), exports);
+__exportStar(require("./decorators/public.decorator"), exports);
+__exportStar(require("./decorators/resource.decorator"), exports);
+__exportStar(require("./decorators/roles.decorator"), exports);
+__exportStar(require("./decorators/scopes.decorator"), exports);
+__exportStar(require("./decorators/token-scopes.decorator"), exports);
+__exportStar(require("./guards/auth.guard"), exports);
+__exportStar(require("./guards/resource.guard"), exports);
+__exportStar(require("./guards/role.guard"), exports);
+__exportStar(require("./interface/jwt.interface"), exports);
+__exportStar(require("./interface/keycloak-auth-module-async-options.interface"), exports);
+__exportStar(require("./interface/keycloak-auth-options-factory.interface"), exports);
+__exportStar(require("./interface/keycloak-auth-options.interface"), exports);
+__exportStar(require("./interface/keycloak-request.interface"), exports);
+__exportStar(require("./interface/oidc.interface"), exports);
+__exportStar(require("./interface/server.interface"), exports);
+__exportStar(require("./interface/tenant-config.interface"), exports);
+__exportStar(require("./interface/enforcer-options.interface"), exports);
+__exportStar(require("./interface/jwks.interface"), exports);
+__exportStar(require("./interface/keycloak-grant.interface"), exports);
+__exportStar(require("./services/keycloak-multitenant.service"), exports);
+__exportStar(require("./services/oidc-discovery.service"), exports);
+__exportStar(require("./services/keycloak-http.service"), exports);
+__exportStar(require("./services/keycloak-url.service"), exports);
+__exportStar(require("./services/keycloak-grant.service"), exports);
+__exportStar(require("./services/jwks-cache.service"), exports);
+__exportStar(require("./services/token-validation.service"), exports);
+__exportStar(require("./services/backchannel-logout.service"), exports);
+__exportStar(require("./services/keycloak-admin.service"), exports);
+__exportStar(require("./controllers/keycloak-admin.controller"), exports);
+__exportStar(require("./token/keycloak-token"), exports);
+__exportStar(require("./token/keycloak-grant"), exports);
+__exportStar(require("./types/conditional-scope.type"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./util"), exports);
+let KeycloakAuthModule = KeycloakAuthModule_1 = class KeycloakAuthModule {
+    /**
+    * Register the `KeycloakAuth` module.
+    * @param opts `keycloak.json` path in string or {@link NestKeycloakConfig} object.
+    * @param config {@link NestKeycloakConfig} when using `keycloak.json` path, optional
+    * @returns
+    */
+    static register(opts, config) {
+        const keycloakConnectProviders = [
+            (0, keycloak_auth_providers_1.createKeycloakAuthOptionProvider)(opts, config),
+            keycloak_auth_providers_1.keycloakProvider,
+            keycloak_multitenant_service_1.KeycloakMultiTenantService,
+            {
+                provide: constants_1.KEYCLOAK_MULTITENANT_SERVICE,
+                useClass: keycloak_multitenant_service_1.KeycloakMultiTenantService,
+            },
+            oidc_discovery_service_1.OidcDiscoveryService,
+            keycloak_http_service_1.KeycloakHttpService,
+            keycloak_grant_service_1.KeycloakGrantService,
+            jwks_cache_service_1.JwksCacheService,
+            token_validation_service_1.TokenValidationService,
+            backchannel_logout_service_1.BackchannelLogoutService,
+            keycloak_admin_service_1.KeycloakAdminService,
+        ];
+        return {
+            module: KeycloakAuthModule_1,
+            imports: [axios_1.HttpModule],
+            controllers: [keycloak_admin_controller_1.KeycloakAdminController],
+            providers: keycloakConnectProviders,
+            exports: keycloakConnectProviders,
+        };
+    }
+    static registerAsync(opts) {
+        const optsProvider = this.createAsyncProviders(opts);
+        return {
+            module: KeycloakAuthModule_1,
+            imports: [...(opts.imports || []), axios_1.HttpModule],
+            controllers: [keycloak_admin_controller_1.KeycloakAdminController],
+            providers: optsProvider,
+            exports: optsProvider,
+        };
+    }
+    static createAsyncProviders(options) {
+        const reqProviders = [
+            this.createAsyncOptionsProvider(options),
+            keycloak_auth_providers_1.keycloakProvider,
+            keycloak_multitenant_service_1.KeycloakMultiTenantService,
+            {
+                provide: constants_1.KEYCLOAK_MULTITENANT_SERVICE,
+                useClass: keycloak_multitenant_service_1.KeycloakMultiTenantService,
+            },
+            oidc_discovery_service_1.OidcDiscoveryService,
+            keycloak_http_service_1.KeycloakHttpService,
+            keycloak_grant_service_1.KeycloakGrantService,
+            jwks_cache_service_1.JwksCacheService,
+            token_validation_service_1.TokenValidationService,
+            backchannel_logout_service_1.BackchannelLogoutService,
+            keycloak_admin_service_1.KeycloakAdminService,
+        ];
+        if (options.useExisting || options.useFactory) {
+            return reqProviders;
+        }
+        return [
+            ...reqProviders,
+            {
+                provide: options.useClass,
+                useClass: options.useClass,
+            },
+        ];
+    }
+    static createAsyncOptionsProvider(options) {
+        if (options.useFactory) {
+            return {
+                provide: constants_1.KEYCLOAK_AUTH_OPTIONS,
+                useFactory: options.useFactory,
+                inject: options.inject || [],
+            };
+        }
+        return {
+            provide: constants_1.KEYCLOAK_AUTH_OPTIONS,
+            useFactory: (optionsFactory) => __awaiter(this, void 0, void 0, function* () { return yield optionsFactory.createKeycloakAuthOptions(); }),
+            inject: [options.useExisting || options.useClass],
+        };
+    }
+};
+exports.KeycloakAuthModule = KeycloakAuthModule;
+KeycloakAuthModule.logger = new common_1.Logger(KeycloakAuthModule_1.name);
+exports.KeycloakAuthModule = KeycloakAuthModule = KeycloakAuthModule_1 = __decorate([
+    (0, common_1.Module)({})
+], KeycloakAuthModule);

package/dist/keycloak-auth.providers.d.ts

@@ -0,0 +1,7 @@
+import { Provider } from '@nestjs/common';
+import { KeycloakAuthConfig, KeycloakAuthOptions, NestKeycloakConfig } from './interface/keycloak-auth-options.interface';
+export declare const keycloakProvider: Provider;
+export declare const createKeycloakAuthOptionProvider: (opts: KeycloakAuthOptions, config?: NestKeycloakConfig) => {
+    provide: string;
+    useValue: KeycloakAuthConfig;
+};