Clerk와 Next.js, NestJS를 활용한 안전하고 확장 가능한 풀스택 인증 구현 가이드

핵심 기술

이 글은 안전하고 확장 가능하며 개발자 친화적인 인증 솔루션으로 Clerk를 소개하고, Next.js (프론트엔드)와 NestJS (백엔드)를 사용하는 풀스택 애플리케이션에서 Clerk 인증을 설정하는 방법을 상세히 안내합니다.

기술적 세부사항

프론트엔드 (Next.js)

• Clerk SDK 설치: pnpm add @clerk/nextjs 명령어로 Clerk Next.js SDK를 설치합니다.
• clerkMiddleware() 설정: middleware.ts 파일에 clerkMiddleware()를 추가하여 앱 전체에서 사용자 인증 상태에 접근할 수 있도록 합니다.
  • middleware.ts 파일 생성 및 clerkMiddleware() 내보내기.
  • config.matcher를 사용하여 특정 경로 (Next.js 내부 파일, 정적 파일 등)는 건너뛰고 API 경로에는 항상 실행되도록 설정합니다.
• Clerk 컴포넌트 통합: RootLayout에서 ClerkProvider를 사용하여 인증 컨텍스트를 제공하고, SignInButton, SignUpButton, UserButton 등의 컴포넌트를 활용하여 사용자 인터페이스를 구축합니다.
• JWT 획득 및 백엔드 API 호출: useAuth() 훅을 통해 getToken() 함수를 사용하여 사용자의 JWT 토큰을 얻고, 이를 백엔드 API 호출 시 Authorization: Bearer ${token} 헤더에 포함시켜 전달합니다.

백엔드 (NestJS)

• Clerk Backend SDK 설치: pnpm add @clerk/backend 명령어로 Clerk Backend SDK를 설치합니다.
• Clerk Client Provider 생성: NestJS 모듈에서 createClerkClient를 사용하여 Clerk 클라이언트를 등록하고, 환경 변수(CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY)를 주입받아 설정합니다.
• AuthGuard 구현:
  • AuthGuardService를 생성하여 CanActivate 인터페이스를 구현합니다.
  • Request 객체에서 cookies.__session 또는 headers.authorization (Bearer 토큰)을 통해 인증 토큰을 추출합니다.
  • 추출된 토큰을 verifyToken() 함수로 검증합니다. (환경 변수 CLERK_SECRET_KEY 사용)
  • 토큰이 유효하면, clerkClient.users.getUser()를 통해 사용자 정보를 가져와 요청 객체에 추가합니다.
  • 유효하지 않거나 토큰이 없는 경우 UnauthorizedException을 발생시킵니다.
• API 라우트 보호: NestJS 컨트롤러에서 @UseGuards(AuthGuardService) 데코레이터를 사용하여 특정 API 엔드포인트에 대한 접근을 보호합니다. (예: ExampleController의 api/profile 엔드포인트)

개발 임팩트

• Clerk를 사용하면 개발자는 복잡한 인증 로직, 세션 관리, OAuth, MFA 등의 기능을 직접 구현하는 대신, 미리 구축된 솔루션을 활용하여 개발 시간을 단축할 수 있습니다.
• Next.js와 NestJS의 조합은 모듈화되고 테스트 가능한 백엔드 구조와 효율적인 프론트엔드 개발 경험을 제공하여 생산성을 높입니다.
• JWT 기반의 토큰 인증은 안전하고 확장 가능한 API 보호를 가능하게 하며, 풀스택 애플리케이션 전반에 걸쳐 일관된 보안 정책을 적용할 수 있습니다.

커뮤니티 반응

이 글은 Clerk, Next.js, NestJS의 강력한 시너지를 강조하며, 이러한 스택을 사용하면 SaaS 플랫폼, 내부 관리 도구, 소비자 앱 등 다양한 종류의 애플리케이션을 빠르고 안전하게 구축할 수 있다고 설명합니다.