Nestjs Clerk-guard

NestJS Library for protecting services using Clerk.com Authentication

Installation

install with npm:

npm install @flowcore/nestjs-clerk-guard @flowcore/microservice

or yarn:

yarn add @flowcore/nestjs-clerk-guard @flowcore/microservice

If you are using GraphQL, you also need to install the @nestjs/graphql package.

Configuration

Import the ClerkGuardModule into your NestJS application and configure it with your Keycloak server's details:

import { ClerkGuardModuleBuilder, ClerkGuardConfigurationSchema } from '@flowcore/nestjs-clerk-guard';
import { ConfigModule, ConfigFactory } from '@flowcore/microservice';
import { AuthGuardBuilder } from "./auth-guard.builder";

const config = ConfigModule.forRoot(
  new ConfigFactory()
    // ...other configuration schemas
    .withSchema(ClerkGuardConfigurationSchema)
  // ...other configuration schemas,
);

@Module({
  imports: [
    config,
    // ...other modules
    new ClerkGuardModuleBuilder().withConfig(config).build(),
  ],
  providers: [
    ...new AuthGuardBuilder()
      .usingClaimGuard()
      .build(),
  ],
})
export class AppModule {
}

This can then be configured in a service with the following environment variables

| Environment Variable | Description | Type | Default Value | Required | |----------------------|------------------------------------------------------------------------------------------------|:--------:|---------------|:--------:| | CLERK_JWKS_URL | The URL to the JWKS endpoint for your Clerk.com application. | string | | ✅ |

Usage

The AuthGuard is global and will protect all routes by default. You can use the @Public() decorator to exclude routes from the AuthGuard.

import { Public } from '@flowcore/nestjs-clerk-guard';
import { Controller, Get } from '@nestjs/common';

@Controller()
export class AppController {
  @Get()
  @Public()
  getHello(): string {
    return 'Hello World!';
  }
}

You can also use the @ClaimsRequired() decorators to protect routes with a ClaimGuard. The @ClaimsRequired() decorator accepts a list of claims. If the user has one of the claims in the token, the route will be accessible.

import { Roles } from '@flowcore/nestjs-clerk-guard';
import { Controller, Get } from '@nestjs/common';
import { ClaimsRequired } from "./claims.decorator";

@Controller()
export class AppController {
  @ClaimsRequired(['some_key'])
  getHello(): string {
    return 'Hello World!';
  }
}

For public endpoints like /health or /metrics you can use the built-in public endpoints are used to keep these paths open. If you want to override these defaults or disable them, you can do so by configuring the ClerkGuardModule using the ClerkGuardModuleBuilder:

@Module({
  imports: [
    config,
    // ...other modules
    new ClerkGuardModuleBuilder()
      .withConfig(config)
      .noPublicEndpoints() // for disabling the built-in public endpoints
      .overridePublicEndpoints(
        [
          '/health',
          '/metrics',
          '/healthz',
        ],
      )
      .build(),
  ],
  // ... other provider, controllers etc.
})
export class AppModule {
}

To get access to the user information in the request, you can use the @AuthenticatedUser() decorator:

import { AuthenticatedUser } from '@flowcore/nestjs-clerk-guard';
import { Controller, Get } from '@nestjs/common';

@Controller()
export class AppController {
  @Get()
  getHello(@AuthenticatedUser() user: any /* change to match your token */): string {
    return 'Hello World!';
  }
}

This also works with @Resolvers() in GraphQL.

We hope you find this library useful in your NestJS projects!

Development

yarn install

or with npm:

npm install