Registry / security / nest-keycloak-grpc

nest-keycloak-grpc

library0.2.0jsnpmunverified

A NestJS gRPC wrapper for Keycloak that provides guards (`ProtectedGuard`, `RoleGuard`) and decorators (`@Protected`, `@Role`) for authenticating and authorizing gRPC calls via Keycloak. Current version 0.2.0, requires `@grpc/grpc-js`, NestJS 8, and `keycloak-connect` between 17 and 18. Configurable via environment variables. Essentially a bridge between NestJS gRPC services and Keycloak's role-based access control, with automatic token validation and permission checking. Limited documentation and active development; not widely adopted.

security

npm install nest-keycloak-grpc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEST-KEYCLOAK-GRPC

nest-keycloak-grpc

securityjavascriptv0.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KeycloakGrpcConnectModule

✓ import { KeycloakGrpcConnectModule } from 'nest-keycloak-grpc'

✗ import KeycloakGrpcConnectModule from 'nest-keycloak-grpc'

Named export, not default. Module must be imported with braces.

Protected

✓ import { Protected } from 'nest-keycloak-grpc'

✗ import { Protected } from '@nestjs/common'

Custom decorator, not part of NestJS core.

RoleGuard

✓ import { RoleGuard } from 'nest-keycloak-grpc'

✗ import { RoleGuard } from 'keycloak-connect'

RoleGuard is part of the package, not keycloak-connect.

Shows minimal setup: import module, add to NestJS imports, and use @Protected() decorator with guards on a gRPC method.

import { Module } from '@nestjs/common'; import { ConfigModule } from '@nestjs/config'; import { KeycloakGrpcConnectModule, Protected, RoleGuard, ProtectedGuard } from 'nest-keycloak-grpc'; import { GrpcMethod } from '@nestjs/microservices'; @Module({ imports: [ ConfigModule.forRoot(), KeycloakGrpcConnectModule, ], controllers: [ExampleController], }) export class AppModule {} @Controller() export class ExampleController { @Protected() @UseGuards(ProtectedGuard, RoleGuard) @GrpcMethod('ExampleService', 'SecureMethod') async secureMethod(@Role('admin') data: unknown) { return { message: 'Authenticated and authorized' }; } }

Debug

Known issues

breakingRequires keycloak-connect >=17.0.0 <=18.0.0; incompatible with Keycloak 19 or later

fix

Pin keycloak-connect to ^17.0.0 or ^18.0.0, check for updates to package supporting newer Keycloak.

affects: >=0.2.0

deprecatedKeycloak roles are implemented as permissions; @Role decorator may not reflect Keycloak role model as expected.

fix

Understand that in Keycloak, roles are sometimes permissions; use Keycloak groups for traditional roles.

affects: >=0.2.0

gotchaUsing @Role('permission') expects a permission name, not a role; wrong argument may cause authorization failures

fix

Ensure to pass permission names (e.g., 'read:resource') as defined in Keycloak client scopes/permissions.

affects: >=0.2.0

gotchaPackage has no documentation on customizing Keycloak options like token audience verification; all options are env-based

fix

Add environment variables for required options; if more control needed, consider forking the package or using keycloak-connect directly.

affects: >=0.2.0

Errors

Common errors & fixes

Cannot find module 'nest-keycloak-grpc' or its corresponding type declarations.

Package not installed or missing from node_modules.

fix

Run: npm install nest-keycloak-grpc @grpc/grpc-js @nestjs/common @nestjs/core @nestjs/config keycloak-connect

TypeError: Failed to read configuration from env: KEYCLOAK_BASE_URL

Environment variables KEYCLOAK_BASE_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET are not set.

fix

Set the required environment variables in your deployment or .env file.

Nest can't resolve dependencies of the KeycloakGrpcConnectModule (?). Please ensure that the argument KEYCLOAK_OPTIONS at index [0] is available in the RootTestModule context.

ConfigModule is not imported before KeycloakGrpcConnectModule in the imports array.

fix

Add ConfigModule.forRoot() before KeycloakGrpcConnectModule in the imports array.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredgRPC transport library for Node.js, required for gRPC functionality

@nestjs/commonrequiredNestJS common package providing decorators, guards, and module infrastructure

@nestjs/corerequiredNestJS core runtime for modules and dependency injection

@nestjs/configrequiredNestJS configuration module to load environment variables

keycloak-connectrequiredKeycloak Node.js adapter for token validation and user session management

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/Future-Africa/nest-keycloak-grpc ↗

packagenest-keycloak-grpc ↗

homepagehttps://github.com/Future-Africa/nest-keycloak-grpc#readme ↗