Nest Keycloak Connect CashGo

Nest Keycloak Connect CashGo is a fork of version 1.9.2 from the project https://www.npmjs.com/package/nest-keycloak-connect, originally authored by John Joshua Ferrer [e-mail].

This library is built upon the functionalities of keycloak-nodejs-connect-cashgo, which can be found at https://www.npmjs.com/package/keycloak-nodejs-connect-cashgo.

For more detailed information about this fork, please refer to the original repository.

Information about Publishing New Versions

Before publishing new versions of the package, please ensure you have the necessary access as an administrator to the CashGo organization's repository on NPM (https://www.npmjs.com/settings/cashgo).

Here are the steps to publish new versions:

1 - Log in to NPM using the terminal command npm login. Enter your NPM credentials when prompted.

2 - Whenever you make modifications to the package, increment the version following the Semantic Versioning format using the script ./set-version.sh x.y.z, where x.y.z represents the new version number.

3 - After incrementing the version, commit your changes to the repository.

4 - Finally, publish the new version to NPM using the script ./release.sh. This script will take care of the publishing process.

Following these steps will ensure that new versions of the package are properly incremented, committed, and published to the CashGo organization's repository on NPM. Always remember to follow the best practices for versioning and make sure to thoroughly test the changes before publishing a new version.

Version of nodejs

v19.7.0

Nest Keycloak Connect

An adapter for keycloak-nodejs-connect.

Features

• Protect your resources using Keycloak's Authorization Services.
• Simply add @Resource, @Scopes, or @Roles in your controllers and you're good to go.
• Compatible with Fastify platform.

Installation

Yarn

yarn add nest-keycloak-connect-cashgo keycloak-nodejs-connect-cashgo

NPM

npm install nest-keycloak-connect-cashgo keycloak-nodejs-connect-cashgo --save

Getting Started

Module registration

Registering the module:

KeycloakConnectModule.register({
  authServerUrl: 'http://localhost:8080', // might be http://localhost:8080/auth for older keycloak versions
  issUrl: 'http://localhost:8080/realms/master', 
  realm: 'master',
  clientId: 'my-nestjs-app',
  secret: 'secret',   
  policyEnforcement: PolicyEnforcementMode.PERMISSIVE, // optional
  tokenValidation: TokenValidation.ONLINE, // optional
})

Async registration is also available:

KeycloakConnectModule.registerAsync({
  useExisting: KeycloakConfigService,
  imports: [ConfigModule]
})

KeycloakConfigService

import { Injectable } from '@nestjs/common';
import { KeycloakConnectOptions, KeycloakConnectOptionsFactory, PolicyEnforcementMode, TokenValidation } from 'nest-keycloak-connect';

@Injectable()
export class KeycloakConfigService implements KeycloakConnectOptionsFactory {

  createKeycloakConnectOptions(): KeycloakConnectOptions {
    return {
      authServerUrl: 'http://localhost:8080', // might be http://localhost:8080/auth for older keycloak versions
      issUrl: 'http://localhost:8080/realms/master', 
      realm: 'master',
      clientId: 'my-nestjs-app',
      secret: 'secret',
      policyEnforcement: PolicyEnforcementMode.PERMISSIVE,
      tokenValidation: TokenValidation.ONLINE,
    };
  } 
}

You can also register by just providing the keycloak.json path and an optional module configuration:

KeycloakConnectModule.register(`./keycloak.json`, {
  policyEnforcement: PolicyEnforcementMode.PERMISSIVE,
  tokenValidation: TokenValidation.ONLINE,
})

Guards

Register any of the guards either globally, or scoped in your controller.

Global registration using APP_GUARD token

NOTE: These are in order, see https://docs.nestjs.com/guards#binding-guards for more information.

providers: [
  {
    provide: APP_GUARD,     
    useClass: AuthGuard,
  },
  {
    provide: APP_GUARD,
    useClass: ResourceGuard,
  },
  {
    provide: APP_GUARD,
    useClass: RoleGuard,
  },
]

Scoped registration

@Controller('cats')
@UseGuards(AuthGuard, ResourceGuard)
export class CatsController {}

What does these providers do ?

AuthGuard

Adds an authentication guard, you can also have it scoped if you like (using regular @UseGuards(AuthGuard) in your controllers). By default, it will throw a 401 unauthorized when it is unable to verify the JWT token or Bearer header is missing.

ResourceGuard

Adds a resource guard, which is permissive by default (can be configured see options). Only controllers annotated with @Resource and methods with @Scopes are handled by this guard.

NOTE: This guard is not necessary if you are using role-based authorization exclusively. You can use role guard exclusively for that.

RoleGuard

Adds a role guard, can only be used in conjunction with resource guard when enforcement policy is PERMISSIVE, unless you only use role guard exclusively. Permissive by default. Used by controller methods annotated with @Roles (matching can be configured)

Configuring controllers

In your controllers, simply do:

import { Resource, Roles, Scopes, Public, RoleMatchingMode } from 'nest-keycloak-connect';
import { Controller, Get, Delete, Put, Post, Param } from '@nestjs/common';
import { Product } from './product';
import { ProductService } from './product.service';

@Controller()
@Resource(Product.name)
export class ProductController {
  constructor(private service: ProductService) {}

  @Get()
  @Public()
  async findAll() {
    return await this.service.findAll();
  }

  @Get()
  @Roles({ roles: ['admin', 'other'] })
  async findAllBarcodes() {
    return await this.service.findAllBarcodes();
  }

  @Get(':code')
  @Scopes('View')
  async findByCode(@Param('code') code: string) {
    return await this.service.findByCode(code);
  }

  @Post()
  @Scopes('Create')
  async create(@Body() product: Product) {
    return await this.service.create(product);
  }

  @Delete(':code')
  @Scopes('Delete')
  @Roles({ roles: ['admin', 'realm:sysadmin'], mode: RoleMatchingMode.ALL })
  async deleteByCode(@Param('code') code: string) {
    return await this.service.deleteByCode(code);
  }

  @Put(':code')
  @Scopes('Edit')
  async update(@Param('code') code: string, @Body() product: Product) {
    return await this.service.update(code, product);
  }
}

Decorators

Here is the decorators you can use in your controllers.

Decorator	Description
@AuthenticatedUser	Retrieves the current Keycloak logged-in user. (must be per method, unless controller is request scoped.)
@EnforcerOptions	Keycloak enforcer options.
@Public	Allow any user to use the route.
@Resource	Keycloak application resource name.
@Scopes	Keycloak application scope name.
@Roles	Keycloak realm/application roles.

Multi tenant configuration

Setting up for multi-tenant is configured as an option in your configuration:

{
  authServerUrl: 'http://localhost:8180/auth',
  clientId: 'nest-api',
  secret: 'fallback', // will be used as fallback when resolver returns null
  multiTenant: {
    realmResolver: (request) => {
      return request.get('host').split('.')[0];
    },
    realmSecretResolver: (realm) => {
      const secrets = { master: 'secret', slave: 'password' };
      return secrets[realm];
    }
  }
}

Configuration options

Keycloak Options

For Keycloak options, refer to the official keycloak-connect library.

Nest Keycloak Options

Option	Description	Required	Default
cookieKey	Cookie Key	no	KEYCLOAK_JWT
logLevels	Built-in logger level (deprecated, will be removed in 2.0)	no	log
useNestLogger	Use the nest logger (deprecated, will be removed in 2.0)	no	true
policyEnforcement	Sets the policy enforcement mode	no	PERMISSIVE
tokenValidation	Sets the token validation method	no	ONLINE
multiTenant	Sets the options for multi-tenant configuration	no	-
roleMerge	Sets the merge mode for @Role decorator	no	OVERRIDE

Multi Tenant Options

Option	Description	Required	Default
resolveAlways	Option to always resolve the realm and secret. Disabled by default.	no	false
realmResolver	A function that passes a request (from respective platform i.e express or fastify) and returns a string	yes	-
realmSecretResolver	A function that passes the realm string and returns the secret string	yes	-

Example app

An example application is provided in the source code with both Keycloak Realm and Postman requests for you to experiment with.