nest-keycloak-connect

To run the example application, you must first build the main package and then install dependencies within the example directory. A realm configuration file (nest-example.json) is included to facilitate immediate setup in Keycloak.

# Build the main package from the root directory
cd ../
npm run build

# Install dependencies in the example folder
cd example
npm install

Once dependencies are installed, you can start the application in development mode using the following command from the example directory.

# development
npm run start

You can register guards globally using the APP_GUARD token or scope them to specific controllers using @UseGuards.

Guard Roles:

• AuthGuard: Verifies the JWT token or Bearer header. Throws 401 if verification fails.
• ResourceGuard: Handles controllers with @Resource and methods with @Scopes. It is permissive by default.
• RoleGuard: Handles methods annotated with @Roles. If policyEnforcement is set to PERMISSIVE, it must be used in conjunction with ResourceGuard.

// Global registration
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 {}

Install nest-keycloak-connect along with its peer dependency keycloak-connect using your preferred package manager.

# Using NPM
npm install nest-keycloak-connect keycloak-connect --save

# Using Yarn
yarn add nest-keycloak-connect keycloak-connect

To use the library, you must register the KeycloakConnectModule in your NestJS application. You can use synchronous registration, asynchronous registration with a configuration service, or provide a path to a keycloak.json file.

// Synchronous registration
KeycloakConnectModule.register({
  authServerUrl: 'http://localhost:8080',
  realm: 'master',
  clientId: 'my-nestjs-app',
  secret: 'secret',
  policyEnforcement: PolicyEnforcementMode.PERMISSIVE,
  tokenValidation: TokenValidation.ONLINE,
});

// Async registration using a configuration service
KeycloakConnectModule.registerAsync({
  useExisting: KeycloakConfigService,
  imports: [ConfigModule],
});

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

When using RoleGuard, you can control how roles are aggregated and how they are validated against the user's token.

RoleMerge (Configuration Option)

Controlled via the roleMerge property in your KeycloakConnectConfig. It determines how @Roles decorators on the class level and method level interact:

• RoleMerge.OVERRIDE: The decorator on the specific method takes precedence over the class-level decorator.
• RoleMerge.ALL: Roles from both the class and the method are combined into a single list.

RoleMatch (Decorator Option)

Controlled via the mode property within the @Roles decorator. It determines the logic used to validate the user's token:

• RoleMatch.ANY: Access is granted if the user has at least one of the required roles.
• RoleMatch.ALL: Access is granted only if the user has all of the required roles.

Use the following decorators to enforce authorization and access user data within your NestJS controllers:

For asynchronous registration, implement the KeycloakConnectOptionsFactory interface in an injectable service to provide your configuration.

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',
      realm: 'master',
      clientId: 'my-nestjs-app',
      secret: 'secret',
      policyEnforcement: PolicyEnforcementMode.PERMISSIVE,
      tokenValidation: TokenValidation.ONLINE,
    };
  }
}

To support multiple realms dynamically, use the multiTenant property within your configuration. You must provide a realmResolver and a realmClientIdResolver. You can optionally provide resolvers for the realm secret, the auth server URL, and a flag to always resolve these values.

const multiTenantConfig: MultiTenantOptions = {
  resolveAlways: true,
  realmResolver: (request) => {
    // Logic to extract realm from request (e.g., header or path)
    return 'tenant-a';
  },
  realmClientIdResolver: async (realm) => {
    // Logic to find client ID for a specific realm
    return `client-${realm}`;
  },
  realmSecretResolver: async (realm) => {
    // Logic to find secret for a specific realm
    return 'secret-for-' + realm;
  },
  realmAuthServerUrlResolver: async (realm) => {
    return `https://keycloak.example.com/${realm}`;
  }
};

When setting up the KeycloakConnectModule, you provide configuration via KeycloakConnectOptions, which can be a string or a KeycloakConnectConfig object. The KeycloakConnectConfig object is used to define connection details such as the realm, client ID, secret, and server URLs. Note that many keys have both camelCase and kebab-case aliases to maintain compatibility with the original keycloak-nodejs-connect configuration style.

const config: KeycloakConnectConfig = {
  realm: 'my-realm',
  clientId: 'my-client',
  secret: 'my-client-secret',
  serverUrl: 'https://keycloak.example.com',
  // Additional options like policyEnforcement or tokenValidation can be added here
};