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 | - |