소개

이 문서에서는 Clerk를 사용하여 NestJS 백엔드 애플리케이션에서 인증 및 권한 부여를 구현하는 방법에 대한 포괄적인 단계별 가이드를 제공합니다.

사무원이란 무엇입니까?

Clerk는 원활한 사용자 인증 및 관리를 위해 내장형 사용자 인터페이스, 유연한 API, 직관적이고 강력한 대시보드를 제공하는 종합 플랫폼입니다. 세션 관리 및 다단계 인증부터 소셜 로그인, 매직 링크, 이메일 또는 SMS 일회성 비밀번호 등에 이르기까지 모든 것을 다룹니다.

서기를 사용하는 이유는 무엇입니까?

데이터 보호와 개인 정보 보호가 점점 더 중요해짐에 따라 인증 및 보안 요구 사항, 추세, 모범 사례는 항상 진화하고 있습니다. 이러한 책임을 전문 서비스 제공업체에 맡기면 애플리케이션의 핵심 기능을 구축하는 데 집중하고 더 빠르게 출시할 수 있습니다.

Clerk와 같은 플랫폼은 이러한 보안 작업을 대신 수행하기 위해 존재합니다.

전제 조건

Typescript 기본 지식
NestJS 기초에 대한 숙지
백엔드 인증 개념 이해
Node 18 이상 실행

프로젝트 설정

이 프로젝트에는 신규 또는 기존 NestJS 프로젝트, Clerk 계정 및 애플리케이션, 그리고 Passport, Passport Strategy 및 Clerk 백엔드 SDK와 같은 라이브러리가 필요합니다.

NestJS 프로젝트 만들기

Nest CLI를 사용하여 새로운 NestJS 프로젝트를 쉽게 설정할 수 있습니다. 원하는 패키지 관리자를 사용하여 다음 명령을 실행하여 새 Nest 애플리케이션을 생성하세요.

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

로그인 후 복사

자세한 내용은 NestJS 문서를 확인하세요.

사무원 계정 및 신청서 설정

아직 계정이 없다면 서기 계정을 만들고 서기 대시보드에서 새 애플리케이션을 설정하세요. Clerk 웹사이트에서 시작할 수 있습니다.

필수 라이브러리 설치

이 프로젝트에 필요한 라이브러리는 다음 명령으로 설치할 수 있습니다.

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

로그인 후 복사

환경 구성

프로젝트의 루트 디렉터리에 .env 파일을 생성하여 다양한 환경, 프로덕션, 개발 또는 스테이징에 대한 변수를 관리하세요.

다음 변수를 추가하고 자리 표시자를 서기 계정 대시보드에서 얻은 실제 키로 바꿉니다.

# .env

CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

로그인 후 복사

ConfigService를 사용하여 애플리케이션 전체에서 환경 변수에 액세스하려면 ConfigModule을 루트 AppModule로 가져옵니다.

// src/app.module.ts

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

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

로그인 후 복사

NestJS에 사무원 통합

이 섹션에서는 NestJS 프로젝트에 Clerk 백엔드 SDK를 통합하고 활용하는 방법을 설명합니다.

사무원 클라이언트 제공자 생성

Clerk 클라이언트를 공급자로 등록하면 데코레이터를 사용하여 클래스에 주입할 수 있으므로 다음 섹션에서 설명하는 것처럼 코드베이스 전체에서 필요할 때마다 사용할 수 있습니다.

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

로그인 후 복사

AppModule에 ClerkClientProvider 등록

다음으로 종속성 주입을 활성화하려면 공급자를 Nest에 등록해야 합니다.

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

로그인 후 복사

서기가 발행한 JWT로 여권 사용

Clerk는 사용자가 Clerk의 호스팅 페이지 또는 프런트엔드 앱을 통해 가입하거나 로그인할 때 JWT 토큰을 발급합니다. 그런 다음 이 토큰은 NestJS 백엔드 애플리케이션에 대한 요청의 Authorization 헤더에 전달자 토큰으로 전송됩니다.

서기 전략 수립

NestJS에서는 인증 전략을 구현하는 데 Passport가 권장되는 방법입니다. Clerk 클라이언트로 토큰을 확인하는 맞춤형 Clerk 전략을 생성하게 됩니다.

# .env

CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

로그인 후 복사

validate() 메소드는 NestJS가 자동으로 request.user에 첨부하는 사용자 데이터를 반환합니다.

인증 모듈 생성

Clerk 전략을 제공하고 PassportModule과 통합되는 AuthModule을 생성합니다. 그런 다음 AppModule에 AuthModule을 등록하세요.

// src/app.module.ts

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

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

로그인 후 복사

// 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],
};

로그인 후 복사

경로 보호 구현

보호된 경로는 사용자가 액세스하기 전에 인증을 받아야 하는 경로입니다.

사무원 인증 가드 생성

경비원은 특정 런타임 조건에 따라 경로 핸들러에서 특정 요청을 처리해야 하는지 여부를 결정합니다.

기본적으로 애플리케이션의 모든 경로를 보호하려면 다음 단계를 수행해야 합니다.

인증 없이 액세스할 수 있는 경로를 표시하는 공용 데코레이터를 만듭니다.
보호된 경로에 대한 액세스를 제한하여 인증된 사용자만 진행할 수 있도록 ClerkAuthGuard를 구현합니다.

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

로그인 후 복사

// 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');
    }
  }
}

로그인 후 복사

전역적으로 인증 활성화

대부분의 엔드포인트가 기본적으로 보호되므로 인증 가드를 글로벌 가드로 구성할 수 있습니다.

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

로그인 후 복사

보호된 경로와 공개 경로 정의

이 두 컨트롤러에서는 AppController의 Public 데코레이터를 사용하여 경로를 공개로 지정합니다. 반면, 인증 가드는 기본적으로 전역적으로 적용되므로 경로를 보호하도록 지정하기 위해 AuthController에 데코레이터가 필요하지 않습니다.

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

로그인 후 복사

// src/decorators/public.decorator.ts

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

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

로그인 후 복사

참고: AppModule에 AppController를 등록하고 AuthModule에 AuthController를 등록하는 것을 잊지 마세요.