keycloak-connect-tbs
v1.0.20
Published
keycloak-connect-tbs connect module for Nest adjusted for RBAC
Downloads
298
Readme
Keycloak Connect TBS
Forked from nest-keycloak-connect. This package supporting RBAC with difference approach from the original one. The approach with following step:
- Get permission detail with request token from keycloak based on user JWT.
- Decode the new token and loop all permissions data for matched with inserted decorator.
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.
- Internal Access API, bypass the request from whitelist given urls of
token
,resource
,scope
or evenrole
. With regex matching method, so whitelist url must be a keyword.
Installation
Yarn
yarn add keycloak-connect-tbs keycloak-connect
NPM
npm install keycloak-connect-tbs keycloak-connect --save
Getting Started
Module registration
Registering the module:
KeycloakConnectModule.register({
authServerUrl: 'http://localhost:8080/auth',
realm: 'master',
clientId: 'my-nestjs-app',
secret: 'secret',
policyEnforcement: PolicyEnforcementMode.PERMISSIVE, // optional
tokenValidation: TokenValidation.ONLINE, // optional
internalUrls: ['localhost', 'users'], // optional
app_port: 3000 // required when internalUrls set
})
Async registration is also available:
KeycloakConnectModule.registerAsync({
useExisting: KeycloakConfigService,
imports: [ConfigModule]
})
KeycloakConfigService
import { Injectable } from '@nestjs/common';
import { KeycloakConnectOptions, KeycloakConnectOptionsFactory, PolicyEnforcementMode, TokenValidation } from 'keycloak-connect-tbs';
@Injectable()
export class KeycloakConfigService implements KeycloakConnectOptionsFactory {
createKeycloakConnectOptions(): KeycloakConnectOptions {
return {
authServerUrl: 'http://localhost:8080/auth',
realm: 'master',
clientId: 'my-nestjs-app',
secret: 'secret',
policyEnforcement: PolicyEnforcementMode.PERMISSIVE,
tokenValidation: TokenValidation.ONLINE,
internalUrls: ['localhost', 'users'],
app_port: 3000,
bypass_iss_check: true, // would token bypass the iss
};
}
}
You must pass your app server port for using internal access checking.
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, InternalAccess} from 'keycloak-connect-tbs';
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']})
@InternalAccess()
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. | | @Scope | Keycloak application scope name. | | @Roles | Keycloak realm/application roles. | | @InternalAccess | Will check request client ip from whitelist url list or not. |
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 |
| 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 | - |
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.