@clemax/nest-keycloak-connect 2.1.0 → 2.1.1

package/dist/constants.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Used internally, provides keycloak options for the Nest guards.
+ */
+export declare const KEYCLOAK_CONNECT_OPTIONS = "KEYCLOAK_CONNECT_OPTIONS";
+/**
+ * Key for injecting a keycloak instance.
+ */
+export declare const KEYCLOAK_INSTANCE = "KEYCLOAK_INSTANCE";
+/**
+ * Key for injecting a keycloak multi tenant service.
+ */
+export declare const KEYCLOAK_MULTITENANT_SERVICE = "KEYCLOAK_MULTITENANT_SERVICE";
+/**
+ * Default cookie key.
+ */
+export declare const KEYCLOAK_COOKIE_DEFAULT = "KEYCLOAK_JWT";
+/**
+ * Role matching mode.
+ */
+export declare enum RoleMatch {
+    /**
+     * Match all roles
+     */
+    ALL = "all",
+    /**
+     * Match any roles
+     */
+    ANY = "any"
+}
+/**
+ * Policy enforcement mode.
+ */
+export declare enum PolicyEnforcementMode {
+    /**
+     * Deny all request when there is no matching resource.
+     */
+    ENFORCING = "enforcing",
+    /**
+     * Allow all request even when there's no matching resource.
+     */
+    PERMISSIVE = "permissive"
+}
+/**
+ * Token validation methods.
+ */
+export declare enum TokenValidation {
+    /**
+     * The default validation method, performs live validation via Keycloak servers.
+     */
+    ONLINE = "online",
+    /**
+     * Validate offline against the configured keycloak options.
+     */
+    OFFLINE = "offline",
+    /**
+     * Does not check for any validation. Should only be used for special cases (i.e development, internal networks)
+     */
+    NONE = "none"
+}
+export declare enum RoleMerge {
+    /**
+     * Overrides roles if defined both controller and handlers, with controller taking over.
+     */
+    OVERRIDE = 0,
+    /**
+     * Merges all roles from both controller and handlers.
+     */
+    ALL = 1
+}

package/dist/constants.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleMerge = exports.TokenValidation = exports.PolicyEnforcementMode = exports.RoleMatch = exports.KEYCLOAK_COOKIE_DEFAULT = exports.KEYCLOAK_MULTITENANT_SERVICE = exports.KEYCLOAK_INSTANCE = exports.KEYCLOAK_CONNECT_OPTIONS = void 0;
+/**
+ * Used internally, provides keycloak options for the Nest guards.
+ */
+exports.KEYCLOAK_CONNECT_OPTIONS = 'KEYCLOAK_CONNECT_OPTIONS';
+/**
+ * Key for injecting a keycloak instance.
+ */
+exports.KEYCLOAK_INSTANCE = 'KEYCLOAK_INSTANCE';
+/**
+ * Key for injecting a keycloak multi tenant service.
+ */
+exports.KEYCLOAK_MULTITENANT_SERVICE = 'KEYCLOAK_MULTITENANT_SERVICE';
+/**
+ * Default cookie key.
+ */
+exports.KEYCLOAK_COOKIE_DEFAULT = 'KEYCLOAK_JWT';
+/**
+ * Role matching mode.
+ */
+var RoleMatch;
+(function (RoleMatch) {
+    /**
+     * Match all roles
+     */
+    RoleMatch["ALL"] = "all";
+    /**
+     * Match any roles
+     */
+    RoleMatch["ANY"] = "any";
+})(RoleMatch || (exports.RoleMatch = RoleMatch = {}));
+/**
+ * Policy enforcement mode.
+ */
+var PolicyEnforcementMode;
+(function (PolicyEnforcementMode) {
+    /**
+     * Deny all request when there is no matching resource.
+     */
+    PolicyEnforcementMode["ENFORCING"] = "enforcing";
+    /**
+     * Allow all request even when there's no matching resource.
+     */
+    PolicyEnforcementMode["PERMISSIVE"] = "permissive";
+})(PolicyEnforcementMode || (exports.PolicyEnforcementMode = PolicyEnforcementMode = {}));
+/**
+ * Token validation methods.
+ */
+var TokenValidation;
+(function (TokenValidation) {
+    /**
+     * The default validation method, performs live validation via Keycloak servers.
+     */
+    TokenValidation["ONLINE"] = "online";
+    /**
+     * Validate offline against the configured keycloak options.
+     */
+    TokenValidation["OFFLINE"] = "offline";
+    /**
+     * Does not check for any validation. Should only be used for special cases (i.e development, internal networks)
+     */
+    TokenValidation["NONE"] = "none";
+})(TokenValidation || (exports.TokenValidation = TokenValidation = {}));
+var RoleMerge;
+(function (RoleMerge) {
+    /**
+     * Overrides roles if defined both controller and handlers, with controller taking over.
+     */
+    RoleMerge[RoleMerge["OVERRIDE"] = 0] = "OVERRIDE";
+    /**
+     * Merges all roles from both controller and handlers.
+     */
+    RoleMerge[RoleMerge["ALL"] = 1] = "ALL";
+})(RoleMerge || (exports.RoleMerge = RoleMerge = {}));

package/dist/decorators/access-token.decorator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Retrieves the currently used access token
+ * @since 2.0.0
+ */
+export declare const AccessToken: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/access-token.decorator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessToken = void 0;
+const common_1 = require("@nestjs/common");
+const internal_util_1 = require("../internal.util");
+/**
+ * Retrieves the currently used access token
+ * @since 2.0.0
+ */
+exports.AccessToken = (0, common_1.createParamDecorator)((data, ctx) => {
+    const [req] = (0, internal_util_1.extractRequest)(ctx);
+    return req.accessToken;
+});

package/dist/decorators/enforcer-options.decorator.d.ts

@@ -0,0 +1,8 @@
+import * as KeycloakConnect from 'keycloak-connect';
+export declare const META_ENFORCER_OPTIONS = "enforcer-options";
+/**
+ * Keycloak enforcer options
+ * @param opts - enforcer options
+ * @since 1.3.0
+ */
+export declare const EnforcerOptions: (opts: KeycloakConnect.EnforcerOptions) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/enforcer-options.decorator.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnforcerOptions = exports.META_ENFORCER_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_ENFORCER_OPTIONS = 'enforcer-options';
+/**
+ * Keycloak enforcer options
+ * @param opts - enforcer options
+ * @since 1.3.0
+ */
+const EnforcerOptions = (opts) => (0, common_1.SetMetadata)(exports.META_ENFORCER_OPTIONS, opts);
+exports.EnforcerOptions = EnforcerOptions;

package/dist/decorators/keycloak-user.decorator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Retrieves the current Keycloak logged-in user.
+ * @since 1.5.0
+ */
+export declare const KeycloakUser: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/keycloak-user.decorator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeycloakUser = void 0;
+const common_1 = require("@nestjs/common");
+const internal_util_1 = require("../internal.util");
+/**
+ * Retrieves the current Keycloak logged-in user.
+ * @since 1.5.0
+ */
+exports.KeycloakUser = (0, common_1.createParamDecorator)((data, ctx) => {
+    const [req] = (0, internal_util_1.extractRequest)(ctx);
+    return req.user;
+});

package/dist/decorators/public.decorator.d.ts

@@ -0,0 +1,7 @@
+export declare const META_PUBLIC = "public";
+/**
+ * Allows unauthorized traffic to enter the route.
+ * @since 1.2.0
+ * @param skipAuth attaches authorization header to user object when `false`, defaults to `true`
+ */
+export declare const Public: () => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/public.decorator.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Public = exports.META_PUBLIC = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_PUBLIC = 'public';
+/**
+ * Allows unauthorized traffic to enter the route.
+ * @since 1.2.0
+ * @param skipAuth attaches authorization header to user object when `false`, defaults to `true`
+ */
+const Public = () => (0, common_1.SetMetadata)(exports.META_PUBLIC, true);
+exports.Public = Public;

package/dist/decorators/resource.decorator.d.ts

@@ -0,0 +1,6 @@
+export declare const META_RESOURCE = "resource";
+/**
+ * Keycloak Resource.
+ * @param resource - name of resource
+ */
+export declare const Resource: (resource: string) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/resource.decorator.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Resource = exports.META_RESOURCE = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_RESOURCE = 'resource';
+/**
+ * Keycloak Resource.
+ * @param resource - name of resource
+ */
+const Resource = (resource) => (0, common_1.SetMetadata)(exports.META_RESOURCE, resource);
+exports.Resource = Resource;

package/dist/decorators/roles.decorator.d.ts

@@ -0,0 +1,10 @@
+import { RoleMatch } from '../constants';
+export declare const META_ROLES = "roles";
+export declare const META_ROLE_MATCHING_MODE = "role-matching-mode";
+/**
+ * Keycloak user roles.
+ * @param roles - the roles to match
+ * @since 2.0.0
+ */
+export declare const Roles: (...roles: string[]) => import("@nestjs/common").CustomDecorator<string>;
+export declare const RoleMatchingMode: (mode: RoleMatch) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/roles.decorator.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleMatchingMode = exports.Roles = exports.META_ROLE_MATCHING_MODE = exports.META_ROLES = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_ROLES = 'roles';
+exports.META_ROLE_MATCHING_MODE = 'role-matching-mode';
+/**
+ * Keycloak user roles.
+ * @param roles - the roles to match
+ * @since 2.0.0
+ */
+const Roles = (...roles) => (0, common_1.SetMetadata)(exports.META_ROLES, roles);
+exports.Roles = Roles;
+const RoleMatchingMode = (mode) => (0, common_1.SetMetadata)(exports.META_ROLE_MATCHING_MODE, mode);
+exports.RoleMatchingMode = RoleMatchingMode;

package/dist/decorators/scopes.decorator.d.ts

@@ -0,0 +1,19 @@
+import * as KeycloakConnect from 'keycloak-connect';
+export declare const META_SCOPES = "scopes";
+export declare const META_CONDITIONAL_SCOPES = "conditional-scopes";
+export type ConditionalScopeFn = (request: any, token: KeycloakConnect.Token) => string[];
+/**
+ * Keycloak authorization scopes.
+ * @param scopes - scopes that are associated with the resource
+ */
+export declare const Scopes: (...scopes: string[]) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Keycloak authorization conditional scopes.
+ * @param scopes - scopes that are associated with the resource depending on the conditions
+ */
+export declare const ConditionalScopes: (resolver: ConditionalScopeFn) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Retrieves the resolved scopes.
+ * @since 1.5.0
+ */
+export declare const ResolvedScopes: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/scopes.decorator.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResolvedScopes = exports.ConditionalScopes = exports.Scopes = exports.META_CONDITIONAL_SCOPES = exports.META_SCOPES = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_SCOPES = 'scopes';
+exports.META_CONDITIONAL_SCOPES = 'conditional-scopes';
+/**
+ * Keycloak authorization scopes.
+ * @param scopes - scopes that are associated with the resource
+ */
+const Scopes = (...scopes) => (0, common_1.SetMetadata)(exports.META_SCOPES, scopes);
+exports.Scopes = Scopes;
+/**
+ * Keycloak authorization conditional scopes.
+ * @param scopes - scopes that are associated with the resource depending on the conditions
+ */
+const ConditionalScopes = (resolver) => (0, common_1.SetMetadata)(exports.META_CONDITIONAL_SCOPES, resolver);
+exports.ConditionalScopes = ConditionalScopes;
+const common_2 = require("@nestjs/common");
+const internal_util_1 = require("../internal.util");
+/**
+ * Retrieves the resolved scopes.
+ * @since 1.5.0
+ */
+exports.ResolvedScopes = (0, common_2.createParamDecorator)((data, ctx) => {
+    const [req] = (0, internal_util_1.extractRequest)(ctx);
+    return req.scopes;
+});

package/dist/guards/auth.guard.d.ts

@@ -0,0 +1,19 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import * as KeycloakConnect from 'keycloak-connect';
+import { KeycloakConnectConfig } from '../interface/keycloak-connect-options.interface';
+import { KeycloakMultiTenantService } from '../services/keycloak-multitenant.service';
+/**
+ * An authentication guard. Will return a 401 unauthorized when it is unable to
+ * verify the JWT token or Bearer header is missing.
+ */
+export declare class AuthGuard implements CanActivate {
+    private singleTenant;
+    private keycloakOpts;
+    private multiTenant;
+    private readonly logger;
+    private readonly reflector;
+    constructor(singleTenant: KeycloakConnect.Keycloak, keycloakOpts: KeycloakConnectConfig, multiTenant: KeycloakMultiTenantService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private validateToken;
+    private extractJwt;
+}

package/dist/guards/auth.guard.js

@@ -0,0 +1,172 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+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 __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+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 AuthGuard_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const KeycloakConnect = __importStar(require("keycloak-connect"));
+const constants_1 = require("../constants");
+const public_decorator_1 = require("../decorators/public.decorator");
+const internal_util_1 = require("../internal.util");
+const keycloak_multitenant_service_1 = require("../services/keycloak-multitenant.service");
+const util_1 = require("../util");
+/**
+ * An authentication guard. Will return a 401 unauthorized when it is unable to
+ * verify the JWT token or Bearer header is missing.
+ */
+let AuthGuard = AuthGuard_1 = class AuthGuard {
+    constructor(singleTenant, keycloakOpts, multiTenant) {
+        this.singleTenant = singleTenant;
+        this.keycloakOpts = keycloakOpts;
+        this.multiTenant = multiTenant;
+        this.logger = new common_1.Logger(AuthGuard_1.name);
+        this.reflector = new core_1.Reflector();
+    }
+    canActivate(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const isPublic = this.reflector.getAllAndOverride(public_decorator_1.META_PUBLIC, [
+                context.getClass(),
+                context.getHandler(),
+            ]);
+            // Extract request/response
+            const cookieKey = this.keycloakOpts.cookieKey || constants_1.KEYCLOAK_COOKIE_DEFAULT;
+            const [request] = (0, internal_util_1.extractRequestAndAttachCookie)(context, cookieKey);
+            // if is not an HTTP request ignore this guard
+            if (!request) {
+                return true;
+            }
+            const jwt = this.extractJwt(request.headers);
+            const isJwtEmpty = jwt === null || jwt === undefined;
+            // Not a public route, require jwt
+            if (!isPublic && isJwtEmpty) {
+                this.logger.verbose('Empty jwt, unauthorized');
+                throw new common_1.UnauthorizedException();
+            }
+            // Public route, no jwt sent
+            if (isPublic && isJwtEmpty) {
+                return true;
+            }
+            this.logger.verbose(`Validating jwt`, { jwt });
+            const keycloak = yield (0, internal_util_1.useKeycloak)(request, jwt, this.singleTenant, this.multiTenant, this.keycloakOpts);
+            const isValidToken = yield this.validateToken(keycloak, jwt);
+            if (isValidToken) {
+                // Attach user info object
+                request.user = (0, util_1.parseToken)(jwt);
+                // Attach raw access token JWT extracted from bearer/cookie
+                request.accessToken = jwt;
+                this.logger.verbose(`User authenticated`, { user: request.user });
+                return true;
+            }
+            // Valid token should return, this time we warn
+            if (isPublic) {
+                this.logger.warn(`A jwt token was retrieved but failed validation.`, {
+                    jwt,
+                });
+                return true;
+            }
+            throw new common_1.UnauthorizedException();
+        });
+    }
+    validateToken(keycloak, jwt) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tokenValidation = this.keycloakOpts.tokenValidation || constants_1.TokenValidation.ONLINE;
+            const gm = keycloak.grantManager;
+            let grant;
+            try {
+                grant = yield gm.createGrant({ access_token: jwt });
+            }
+            catch (ex) {
+                this.logger.warn(`Cannot validate access token: ${ex}`);
+                // It will fail to create grants on invalid access token (i.e expired or wrong domain)
+                return false;
+            }
+            const token = grant.access_token;
+            this.logger.verbose(`Using token validation method: ${tokenValidation.toUpperCase()}`);
+            try {
+                let result;
+                switch (tokenValidation) {
+                    case constants_1.TokenValidation.ONLINE:
+                        result = yield gm.validateAccessToken(token);
+                        return result === token;
+                    case constants_1.TokenValidation.OFFLINE:
+                        result = yield gm.validateToken(token, 'Bearer');
+                        return result === token;
+                    case constants_1.TokenValidation.NONE:
+                        return true;
+                    default:
+                        this.logger.warn(`Unknown validation method: ${tokenValidation}`);
+                        return false;
+                }
+            }
+            catch (ex) {
+                this.logger.warn(`Cannot validate access token: ${ex}`);
+            }
+            return false;
+        });
+    }
+    extractJwt(headers) {
+        if (headers && !headers.authorization) {
+            this.logger.verbose(`No authorization header`);
+            return null;
+        }
+        const auth = headers.authorization.split(' ');
+        // We only allow bearer
+        if (auth[0].toLowerCase() !== 'bearer') {
+            this.logger.verbose(`No bearer header`);
+            return null;
+        }
+        return auth[1];
+    }
+};
+exports.AuthGuard = AuthGuard;
+exports.AuthGuard = AuthGuard = AuthGuard_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.KEYCLOAK_INSTANCE)),
+    __param(1, (0, common_1.Inject)(constants_1.KEYCLOAK_CONNECT_OPTIONS)),
+    __param(2, (0, common_1.Inject)(constants_1.KEYCLOAK_MULTITENANT_SERVICE)),
+    __metadata("design:paramtypes", [Object, Object, keycloak_multitenant_service_1.KeycloakMultiTenantService])
+], AuthGuard);

package/dist/guards/resource.guard.d.ts

@@ -0,0 +1,18 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import * as KeycloakConnect from 'keycloak-connect';
+import { KeycloakConnectConfig } from '../interface/keycloak-connect-options.interface';
+import { KeycloakMultiTenantService } from '../services/keycloak-multitenant.service';
+/**
+ * This adds a resource guard, which is policy enforcement by default is permissive.
+ * Only controllers annotated with `@Resource` and methods with `@Scopes`
+ * are handled by this guard.
+ */
+export declare class ResourceGuard implements CanActivate {
+    private singleTenant;
+    private keycloakOpts;
+    private multiTenant;
+    private readonly logger;
+    private readonly reflector;
+    constructor(singleTenant: KeycloakConnect.Keycloak, keycloakOpts: KeycloakConnectConfig, multiTenant: KeycloakMultiTenantService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}