TBS Auth

Package for TBS authentication and authorization. Only support for casdoor.

Features

1. Authentication check (token).
2. Authorization check based on casdoor enforcer.
3. Auto sync / populate for casdoor enforcer policy.

Installation

Yarn

yarn add tbs-auth

NPM

npm install tbs-auth

Getting Started

Module registration

Registering the module:

import { TbsAuthModule } from "tbs-auth";

TbsAuthModule.register({
  internal_urls: ['localhost', 'users'], // optional
  app_port: 3000, // required when internal_urls set
  casdoor: {
    host: "http:localhost:8000", // your casdoor api url
    client_id: "ada71jxcasd", // your casdoor client id
    private_key: "ajdkad81lkj123291nnsadjhsahj1", // your casdoor client secret
    organization: "tbs-icarus", // yout casdoor organization
    appName: 'tbs-app' // your casdoor app name 
  }
})

Auto Populate / Sync Policy. Put on main.ts.

import { TbsAuthSyncService } from "tbs-auth";

await TbsAuthSyncService(
  app, 
  {
    host: process.env.CASDOOR_HOST,
    client_id: process.env.CASDOOR_CLIENT_ID,
    private_key: process.env.CASDOOR_PRIVATE_KEY,
  },
  "tbs",
  "products:",
  "tbs-icarus",
  "tbs-app",
);

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.

import { AuthenticationGuard } from "tbs-auth"

providers: [
  {
    provide: APP_GUARD,     
    useClass: AuthenticationGuard,
  },
]

Public API

This decorator can be applied at the controller or function level. Function-level application takes precedence over controller-level. The decorator accepts parameters:

• false → If a token is provided, it will be checked for validity. If the token is revoked or expired, an unauthorized error will be thrown. However, if no token is provided, the client can still access this API.
• true → skip everything even token provided.

import { Public } from "tbs-auth"

@Controller('cats')
@Public()
export class CatsController {}

Internal Access API

This decorator can be applied at the controller or function level. Function-level application takes precedence over controller-level. The decorator accepts parameters:

• STRICT → Requester domain must be registered on internal_urls config module registration above.
• NOT_STRICT → When the requester domain is not registered in internal_urls, a token must be provided for authorization. However, if the requester domain is registered, the token is bypassed.

import { Public } from "tbs-auth"

@Controller('cats')
@Public() // fill true for skip the provided token, or false to skip everything
export class CatsController {}

What does these providers do ?

AuthenticationGuard

Adds an authentication guard, you can also have it scoped if you like (using regular @UseGuards(AuthenticationGuard) 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.

Configuring controllers

In your controllers, simply do:

import {Public, InternalAccess, InternalAccessMethod} from "tbs-auth";
import {Controller, Get, Delete, Put, Post, Param} from '@nestjs/common';
import {Product} from './product';
import {ProductService} from './product.service';
import {BypassEnforcer} from "./bypass-enforcer.decorator";

@Controller()
export class ProductController {
  constructor(private service: ProductService) {
  }

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

  @Get()
  @InternalAccess()
  async findAllBarcodes() {
    return await this.service.findAllBarcodes();
  }

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

  @Post()
  @InternalAccess(InternalAccessMethod.STRICT)
  async create(@Body() product: Product) {
    return await this.service.create(product);
  }

  @Delete(':code')
  async deleteByCode(@Param('code') code: string) {
    return await this.service.deleteByCode(code);
  }

  @Put(':code')
  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	Default
@Public	Allow any user to use the route.	true
@InternalAccess	Check if the request client IP is in the whitelist URL list.	NOT_STRICT
@PopulateEnforcer	Auto populate enforcer data for some role in an endpoint or controller	null
@BypassEnforcer	Bypass the enforcer checking on an endpoint or controller	true

Configuration options

Keycloak Options

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

Nest Keycloak Options

Option	Description	Required	Default
internalUrls	Sets the list of whitelist url keyword to access endpoint	no	-
app_port	Sets the port of your app server port	yes when interalUrls sets	-
casdoor.host	Casdoor API Url	yes	-
casdoor.client_id	Casdoor Client ID	yes	-
casdoor.private_key	Casdoor Client Secret	yes	-
casdoor.organization	Casdoor Organization	yes	-
casdoor.appName	Casdoor App Name	yes	-