Skip to main content

인증 흐름 (Authentication Flow)

이 문서는 프론트엔드 애플리케이션의 Web3 기반 인증 흐름에 대해 상세히 설명합니다.

1. 개요​

우리 애플리케이션은 MetaMask와 같은 Web3 지갑을 통한 서명 기반의 인증 방식을 사용합니다. 사용자는 지갑을 연결하고 특정 메시지에 서명함으로써 백엔드로부터 인증 토큰(JWT)을 발급받아 로그인 상태를 유지합니다. 인증 토큰은 HttpOnly 쿠키로 관리되어 보안을 강화합니다.

2. 주요 구성 요소​

2.1. Web3Provider (frontend-autopromaker-ai/src/providers/Web3Provider.tsx)​

Web3Provider는 애플리케이션 전반에 걸쳐 Web3 지갑 연결 상태, 지갑 주소, 네트워크 정보, 토큰 잔액 등 Web3 관련 데이터를 제공하는 React Context Provider입니다.

  • 주요 기능:
    • MetaMask 연결 및 해제.
    • 연결된 지갑의 publicAddress 관리.
    • 현재 연결된 블록체인 네트워크 정보 (network.name, network.chainId) 조회 및 관리.
    • 네이티브 토큰(ETH) 및 ERC-20 토큰(USDT) 잔액 조회 및 관리.
    • accountsChanged 및 chainChanged 이벤트 리스너를 등록하여 지갑 계정 또는 네트워크 변경 시 상태를 자동으로 업데이트.

2.2. useAuth 훅 (frontend-autopromaker-ai/src/features/auth/hooks/useAuth.ts)​

useAuth 훅은 Web3Provider에서 제공하는 지갑 연결 상태를 기반으로 사용자 인증(로그인/로그아웃) 로직을 추상화합니다. React Query를 사용하여 서버와의 통신을 관리합니다.

  • 주요 기능:
    • 로그인 (login):
      1. 백엔드에 publicAddress를 전송하여 nonce 값을 요청합니다.
      2. MetaMask를 통해 nonce를 포함한 메시지에 서명합니다.
      3. 서명된 메시지와 publicAddress를 백엔드에 전송하여 서명을 검증하고 JWT를 발급받습니다.
      4. 백엔드는 JWT를 HttpOnly 쿠키로 설정하여 클라이언트에 응답합니다.
      5. 로그인 성공 후 userProfile 쿼리를 무효화하여 최신 사용자 정보를 가져오도록 트리거합니다.
    • 로그아웃 (logout):
      1. 백엔드 로그아웃 API를 호출하여 서버 측 세션을 종료하고 HttpOnly 쿠키를 삭제합니다.
      2. Web3Provider의 disconnectWallet 함수를 호출하여 클라이언트 측 지갑 연결 상태를 초기화합니다.
      3. React Query 캐시를 초기화하고 userProfile 쿼리를 무효화합니다.
    • 로그인 상태 (isLoggedIn): userProfile 데이터의 존재 여부로 로그인 상태를 판단합니다.
    • 사용자 프로필 (userProfile): 백엔드 /auth/profile 엔드포인트로부터 사용자 정보를 가져옵니다.

3. 보호된 경로 접근 제어 및 리디렉션 (frontend-autopromaker-ai/middleware.ts)​

Next.js 미들웨어를 사용하여 클라이언트 측 라우팅 이전에 서버 측에서 보호된 경로에 대한 접근을 제어합니다.

  • 작동 방식:
    1. 모든 요청이 서버에 도달하면 middleware.ts 파일이 실행됩니다.
    2. accessToken HttpOnly 쿠키의 존재 여부를 통해 사용자의 로그인 상태를 간접적으로 판단합니다.
    3. protectedPaths 배열에 정의된 경로(예: /dashboard)로의 요청이 들어오고 accessToken이 없으면, 로그인 페이지(루트 /)로 리디렉션합니다.
    4. 리디렉션 시 ?redirected=true 쿼리 파라미터를 추가하여 로그인 페이지에서 사용자에게 알림을 제공합니다.
    5. 로그인 상태에서 루트 페이지(/)에 접근 시, /dashboard와 같은 기본 보호된 페이지로 리디렉션하여 불필요한 로그인 페이지 노출을 방지합니다.

4. 백엔드 연동​

  • backend-autopromaker-ai/src/auth/auth.controller.ts: /auth/login, /auth/profile, /auth/logout 엔드포인트를 제공합니다.
  • backend-autopromaker-ai/src/auth/auth.service.ts: 로그인 로직(nonce 생성, 서명 검증, JWT 발급) 및 프로필 조회 로직을 구현합니다.
  • backend-autopromaker-ai/src/users/user.entity.ts: 사용자 정보를 저장하는 User 엔티티를 정의하며, publicAddress, nonce, username 등의 필드를 포함합니다.