nest-acl-sdk

Description

ACL SDK module for Nest. It provides some decorator to define role/permissions for API endpoints base on metadata, and help to automated collect policies of endpoints of microservices then send to api-iam service if need.

Noted:

Nest ACL SDK and Nestjs swagger should be used together!

Installation

$ npm i --save nest-acl-sdk

Usage

ACL SDK provides 2 strategies:

• RBAC: Role based access control
• CBAC: Claim based access control (permissions)

Use synchronous config

import {ACLModule, ACLStrategy, ACLModuleOptions, ACLService} from 'nest-acl-sd';
@Module({
  imports: [
    ...
    DiscoveryModule,
    ACLModule.register({
      strategy: ACLStrategy.RBAC,
      serviceBaseUrl: '/api',
      serviceName: 'test-api',
      apiIamBaseUrl: 'api-iam/api/',
      iamChecksumPoliciesUrl: '/policies/',
      iamUpdatePoliciesUrl: '/policies',
      logProcess: true,
      global: true,
    })
  ],
  providers: [...],
})
export class AppModule implements OnApplicationBootstrap {
  constructor(private aclService: ACLService) {}

  async onApplicationBootstrap() {
    const this.aclService: ACLService = this.get<ACLService>(ACLService);
    await this.aclService.updateEndpointPolicies();
    console.log('policies', aclService.getPoliciesData());
  }
}

use with asynchronous config

import {ACLModule, ACLStrategy, ACLModuleOptions, ACLService} from 'nest-acl-sd';
@Module({
  imports: [
    ...
    DiscoveryModule,
    ACLModule.registerAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => {
        return {
          strategy: ACLStrategy.CBAC,
          serviceBaseUrl: config.get<string>('service.baseUrl'),
          serviceName: config.get<string>('service.name'),
          apiIamBaseUrl: config.get<string>('aclSDK.iamBaseUrl'),
          iamChecksumPoliciesUrl: config.get<string>('aclSDK.iamChecksumPoliciesUrl'),
          iamUpdatePoliciesUrl: config.get<string>('aclSDK.iamUpdatePoliciesUrl'),
          logProcess: config.get<boolean>('aclSDK.logProcess'),
          global: true,
        } as ACLModuleOptions;
      }
    })
  ],
  providers: [...],
})
export class AppModule implements OnApplicationBootstrap {
  constructor(private aclService: ACLService) {}

  async onApplicationBootstrap() {
    const aclService: ACLService = this.get<ACLService>(ACLService);
     await aclService.updateEndpointPolicies();
    console.log('policies', aclService.getPoliciesData());
  }
}

If use Claim based access control strategy (CBAC) you can use @Permissions decorator to define policies of endpoint in controller class

import {Controller, Get, Post} from '@nestjs/common';
import {ApiOperation} from '@nestjs/swagger';
import {Permissions} from '../decorators/permission.decorator';

@Controller('test-cbac')
export class TestCbacController {

  @ApiOperation({
    operationId: 'getAbc',
    description: 'Get abc',
  })
  @Permissions(['service_get_abc'])
  @Get('abc')
  async getAbc() {
    return 'abc';
  }

  @ApiOperation({
    operationId: 'getCde',
    description: 'Get cde',
  })
  @Permissions(['service_get_abc', 'index_abc'])
  @Get('cde')
  async getCde() {
    return 'cde';
  }
}

If use Role based access control strategy (RBAC) you can use @Roles decorator to define policies of endpoint in controller class

import {Controller, Get, Post} from '@nestjs/common';
import {ApiOperation} from '@nestjs/swagger';
import {Roles} from '../decorators/roles.decorator';

@Controller('test-rbac')
export class TestRbacController {

  @ApiOperation({
    operationId: 'getAbc',
    description: 'Get abc',
  })
  @Roles(['admin'])
  @Get('abc')
  async getAbc() {
    return 'abc';
  }

  @ApiOperation({
    operationId: 'getCde',
    description: 'Get cde',
  })
  @Roles(['customers', 'admin'])
  @Get('cde')
  async getCde() {
    return 'cde';
  }
}

Collect and update endpoint policies

in AppModule we implements OnApplicationBoostrap event, we call function updateEndpointPolicies(), the ACL service automated collect all defined roles/permissions on controllers then check it with IAM service by checksum to decide policies need to update or not.

ACLModuleOptions:

• strategy: Enum - ACL SDK provides 2 options: ACLStrategy.CBAC and ACLStrategy.RBAC
• global: boolean - Allow this ACL SDK module is an global module
• serviceBaseUrl: string - is global prefix URL of your service,
• serviceName: string - is your service's name.
• apiIamBaseUrl: string - The base URL of IAM Service
• iamChecksumPoliciesUrl: string | Function - The define of IAM service endpoint URL to get MD5 checksum about service's policies from IAM service to decide update policies or not (by HTTP Get method)
• iamUpdatePoliciesUrl: string | Function - The define of IAM service endpoint URL to update policies (by HTTP POST method).
• logProcess: boolean - enable/disable logging debug when processing collect and update policies.

License

Nest is MIT licensed.