dev-resources.site

for different kinds of informations.

Authentication with Clerk in NestJS Server Application

Published at

1/4/2025

Introduction

This article provides a comprehensive, step-by-step guide to implementing authentication and authorization in a NestJS backend application with Clerk.

What is Clerk?

Clerk is a comprehensive platform offering embeddable user interfaces, flexible APIs, and an intuitive and robust dashboard for seamless user authentication and management. It covers everything from session management and multi-factor authentication to social sign-ons, magic links, email or SMS one-time passcodes and more.

Why use Clerk?

Authentication and security requirements, trends, and best practices are always evolving because data protection and privacy are increasingly important. By offloading these responsibilities to a specialized service provider, you can focus on building the core features of your application and ship faster.

Platforms like Clerk exist to take on these security tasks for you.

Prerequisites

Basic knowledge of Typescript
Familiarity with NestJS Fundamentals
Understanding of authentication concept on the backend
Running Node 18 or latest

Project setup

This project requires a new or existing NestJS project, a Clerk account and application, and libraries like Passport, Passport Strategy and Clerk backend SDK.

Creating a NestJS project

You can easily set up a new NestJS project using the Nest CLI. With any package manager you prefer, run the following commands to create a new Nest application:

$ pnpm add -g @nestjs/cli
$ nest new clerk-auth

Checkout the NestJS documentation for more details.

Setting up your Clerk account and application

If you don’t already have one, create a Clerk account and set up a new application in the Clerk dashboard. You can get started on Clerk website.

Installing required libraries

The required libraries for this project can be installed with this command:

$ pnpm add @clerk/backend @nestjs/config @nestjs/passport passport passport-custom

Environment configuration

Create a .env file in the root directory of your project to manage variables for different environments, production, development or staging.

Add the following variables, replacing the placeholders with the actual keys obtained from your Clerk account dashboard.

# .env

CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

To access environment variables throughout the application using the ConfigService, import the ConfigModule into the root AppModule.

// src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
  ],
})
export class AppModule {}

Integrating Clerk in NestJS

This section explains how to integrate and utilize the Clerk backend SDK in your NestJS project.

Creating a Clerk client provider

Registering the Clerk client as a provider makes it injectable into classes using a decorator, allowing it to be used wherever needed throughout the codebase, as demonstrated in the upcoming sections.

// src/providers/clerk-client.provider.ts

import { createClerkClient } from '@clerk/backend';
import { ConfigService } from '@nestjs/config';

export const ClerkClientProvider = {
  provide: 'ClerkClient',
  useFactory: (configService: ConfigService) => {
    return createClerkClient({
      publishableKey: configService.get('CLERK_PUBLISHABLE_KEY'),
      secretKey: configService.get('CLERK_SECRET_KEY'),
    });
  },
  inject: [ConfigService],
};

Registering the ClerkClientProvider in AppModule

Next, you need to register the provider with Nest to enable dependency injection.

// src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ClerkClientProvider } from 'src/providers/clerk-client.provider';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
  ],
  providers: [ClerkClientProvider],
})
export class AppModule {}

Using Passport with Clerk-Issued JWT

Clerk issues a JWT token when a user signs up or logs in through Clerk’s hosted pages or a frontend app. This token is then sent as a bearer token in the Authorization header of requests made to the NestJS backend application.

Creating a Clerk Strategy

In NestJS, Passport is the recommended way to implement authentication strategies. You’ll create a custom Clerk strategy that verifies tokens with Clerk client.

// src/auth/clerk.strategy.ts

import { User, verifyToken } from '@clerk/backend';
import { Injectable, Injectable, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PassportStrategy } from '@nestjs/passport';
import { Strategy } from 'passport-custom';
import { UsersService } from 'src/users/users.service';
import { Request } from 'express';
import { ClerkClient } from '@clerk/backend';

@Injectable()
export class ClerkStrategy extends PassportStrategy(Strategy, 'clerk') {
  constructor(
    @Inject('ClerkClient')
    private readonly clerkClient: ClerkClient,
    private readonly configService: ConfigService,
  ) {
    super();
  }

  async validate(req: Request): Promise<User> {
    const token = req.headers.authorization?.split(' ').pop();

    if (!token) {
      throw new UnauthorizedException('No token provided');
    }

    try {
      const tokenPayload = await verifyToken(token, {
        secretKey: this.configService.get('CLERK_SECRET_KEY'),
      });

      const user = await this.clerkClient.users.getUser(tokenPayload.sub);

      return user;
    } catch (error) {
      console.error(error);
      throw new UnauthorizedException('Invalid token');
    }
  }
}

The validate() method returns user data that NestJS automatically attaches to the request.user.

Creating an Auth Module

Create an AuthModule that provides the Clerk strategy and integrates with the PassportModule. Then, register the AuthModule in the AppModule.

// src/auth/auth.module.ts

import { Module } from '@nestjs/common';
import { ClerkStrategy } from './clerk.strategy';
import { PassportModule } from '@nestjs/passport';
import { ClerkClientProvider } from 'src/providers/clerk-client.provider';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [PassportModule, ConfigModule],
  providers: [ClerkStrategy, ClerkClientProvider],
  exports: [PassportModule],
})
export class AuthModule {}

// src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ClerkClientProvider } from 'src/providers/clerk-client.provider';
import { AuthModule } from 'src/auth/auth.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    AuthModule,
  ],
  providers: [ClerkClientProvider],
})
export class AppModule {}

Implementing routes protections

Protected routes are routes that require the user to be authenticated before they can access them.

Creating Clerk authentication guard

Guards determine whether a specific request should be processed by a route handler based on certain runtime conditions.

If you want to protect all routes in your application by default, you’ll need to take the following steps:

Create a Public decorator to mark routes that should be accessible without authentication.
Implement a ClerkAuthGuard to restrict access to protected routes, allowing only authenticated users to proceed.

// src/decorators/public.decorator.ts

import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

// src/auth/clerk-auth.guard.ts

import { type ExecutionContext, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { AuthGuard } from '@nestjs/passport';
import { IS_PUBLIC_KEY } from 'src/decorators/public.decorator';

@Injectable()
export class ClerkAuthGuard extends AuthGuard('clerk') {
  constructor(private reflector: Reflector) {
    super();
  }

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (isPublic) {
      return true;
    }

    return super.canActivate(context);
  }
}

Enabling authentication globally

Since most of your endpoints will be protected by default, you can configure the authentication guard as a global guard.

// src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ClerkClientProvider } from '../providers/clerk-client.provider';
import { AuthModule } from '../auth/auth.module';
import { ClerkAuthGuard } from '../auth/clerk-auth.guard';
import { APP_GUARD } from '@nestjs/core';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    AuthModule,
  ],
  providers: [
    ClerkClientProvider,
    {
      provide: APP_GUARD,
      useClass: ClerkAuthGuard,
    },
  ],
})
export class AppModule {}

Defining Protected and Public Routes

In these two controllers, the Public decorator is used in the AppController to designate a route as public. In contrast, no decorator is needed in the AuthController to specify routes as protected, as the authentication guard is applied globally by default.

// src/app.controller.ts

import { Controller, Get } from '@nestjs/common';
import { Public } from 'src/decorators/public.decorator';

@Controller()
export class AppController {
  @Public()
  @Get()
  async app() {
    return 'Hello World';
  }
}

// src/auth/auth.controller.ts

import { User } from '@clerk/backend';
import { Controller, Get } from '@nestjs/common';
import { CurrentUser } from 'src/decorators/current-user.decorator';

@Controller('auth')
export class AuthController {
  @Get('me')
  async getProfile(@CurrentUser() user: User) {
    return user;
  }
}

Note: Remember to register the AppController in the AppModule and the AuthController in the AuthModule.

Conclusion

Clerk as a platform handles authentication and security responsibilities, keeping up with the latest trends and best practices. This enables you to focus on building your application’s core features and accelerating your development process.

In this guide, we’ve covered the steps to implement Clerk authentication, from setting up the project to securing routes. These foundational steps should help you get started on your journey of exploring the possibilities with an authentication service platform.

A fully functional example of this project is included at the end of this article.