OAuth(Kakao) 흐름

[sgoldenbird]

1. ✨ 설계 배경 및 목적

사용자 편의성을 극대화하고 회원가입 및 로그인 절차를 단순화하기 위해 카카오 소셜 로그인/회원가입 기능을 지원합니다.
카카오 OAuth 인가코드의 일회성 제약과, 백엔드가 회원가입 시 닉네임을 필수로 요구하는 스펙을 만족시키기 위해 로그인과 회원가입 redirect URI를 분리하고, Transition Page를 통해 닉네임을 입력받는 흐름을 도입했습니다.
이를 통해 복잡한 인증 과정을 서버와 BFF에서 안전하게 처리하고, 사용자에게는 최대한 자연스러운 경험을 제공합니다.

2. 🧱 구성요소 및 구조

redirect URI 이원화 + Transition Page + 인가코드 두 번 발급

카카오 로그인 전체 흐름은 다음과 같습니다:

1. (사용자) “카카오로 시작하기” 버튼 클릭 → 카카오 인증 페이지로 이동.
2. (카카오 → 서버) 카카오는 사용자를 로그인 콜백 URI(/api/auth/kakao/signin) 로 리디렉트하며 인가 코드를 전달.
3. (서버 → 백엔드) 서버는 인가코드를 사용해 로그인 시도.
   • 가입된 유저 → 로그인 성공 → 토큰 발급 및 쿠키 설정 → 홈으로 이동
   • 미가입 유저 → 403 응답 → Transition Page로 이동.
4. (Transition Page) 닉네임 입력 UI 제공 → “계속하기” 클릭 시 회원가입 콜백 URI(/api/auth/kakao/signup) 으로 새 인가 코드 요청.
5. (카카오 → 서버) 카카오는 새 인가코드를 회원가입 redirect URI에 전달.
6. (서버 → 백엔드) 서버는 새 인가코드 + 닉네임으로 회원가입 API 호출.
   • 성공 시 → 토큰 발급 및 쿠키 설정 → 홈으로 이동.
   • 실패 시 → 적절한 에러 페이지나 재시도 안내.

3. ⚙️ 동작 흐름 요약

• 시작: 클라이언트에서 “카카오로 시작하기” 클릭.
• 1차 인가코드: /api/auth/kakao/signin에서 로그인 시도 → 실패 시 Transition Page.
• Transition Page: 닉네임 입력 후 회원가입 진행.
• 2차 인가코드: /api/auth/kakao/signup에서 회원가입 요청 → 자동 로그인 처리.

4. 🔮 설계 의도 및 고려사항

• 인가코드 일회성 제약 대응: 로그인과 회원가입을 각각 새로운 인가코드로 처리.
• 닉네임 요구사항 충족: Transition Page에서 직접 입력받아 API 요구사항을 충족.
• 사용자 경험 보완: 약관 동의 UI가 두 번 뜰 수 있는 어색함을 Transition Page로 납득 가능한 흐름으로 연결.
• 보안 강화:
  • 인가코드 교환 및 사용자 정보 요청은 서버에서 수행.
  • 최종 accessToken/refreshToken은 HttpOnly Secure 쿠키에 저장.
• 자동 로그인 편의 제공: 회원가입 완료 즉시 토큰을 발급받아 자동 로그인 처리.
• 중앙 집중식 에러 처리: 로그인/회원가입 실패 시 상태 코드에 따라 UX를 분기하고 에러 메시지 제공.

5. 🪄 세부 설명: 주요 훅 / 컴포넌트 / 유틸

• src/app/api/auth/kakao/signin/route.ts:
  카카오 인증 콜백을 처리하고, 받은 인가 코드를 백엔드 로그인 API에 전달합니다.
  로그인 실패 시 UrlMessageToast를 통해 REGISTER_REQUIRED 메시지를 전달합니다.

• src/app/(auth)/kakao/transition/page.tsx:
  로그인 실패 시 진입하는 중간 페이지입니다.
  닉네임 입력 폼을 제공하며, 폼 제출 시 api/auth/kakao/signup 리디렉션 URI로 재요청을 유도합니다.

• src/app/api/auth/kakao/signup/route.ts:
  두 번째 인가 코드 콜백을 처리합니다.
  URL에서 새로운 인가 코드와 state 파라미터로 전달된 닉네임을 추출하여 백엔드의 회원가입 API에 직접 전달합니다.

• src/domain/Auth/utils/setAuthCookies.ts:
  인증 성공 후 받은 accessToken과 refreshToken을 HTTP Only 쿠키로 안전하게 설정하는 유틸리티 함수입니다.

6. 🧩 사용 예시 및 패턴

• src/app/(auth)/kakao/transition/page.tsx (클라이언트 측):
  이 컴포넌트는 로그인 실패 시 사용자가 닉네임을 입력하는 페이지입니다.

'use client';
import dynamic from 'next/dynamic';
import { Suspense } from 'react';

const KakaoTransition = dynamic(
  () => import('@/domain/Auth/components/KakaoTransition'),
  { ssr: false }, // 클라이언트 전용 렌더링
);

export default function Page() {
  return (
    <Suspense fallback={null}>
      <KakaoTransition />
    </Suspense>
  );
}

• src/app/api/auth/kakao/signup/route.ts (서버 측)
  새로 발급된 인가 코드와 닉네임을 백엔드에 직접 전달하는 로직입니다.

import { NextRequest, NextResponse } from 'next/server';
import { oauthResponseSchema } from '@/domain/Auth/schemas/response';
import setAuthCookies from '@/domain/Auth/utils/setAuthCookies';
import { API_ENDPOINTS } from '@/shared/constants/endpoints';
import { ERROR_CODES, ROUTES } from '@/shared/constants/routes';

async function handleOauthSignUp(
  kakaoAuthCode: string,
  nickname: string,
): Promise<OAuthResponse> {
  const redirectUri = process.env.NEXT_PUBLIC_KAKAO_SIGNUP_REDIRECT_URI;
  if (!redirectUri) {
    throw new Error('NEXT_PUBLIC_KAKAO_SIGNUP_REDIRECT_URI가 설정되지 않았습니다.');
  }

  const signUpResponse = await fetch(
    `${process.env.API_BASE_URL}${API_ENDPOINTS.OAUTH.SIGNUP_PROVIDER('kakao')}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        token: kakaoAuthCode,
        nickname: nickname,
        redirectUri,
      }),
    },
  );

  const responseData = await signUpResponse.json();
  if (!signUpResponse.ok) {
    throw Object.assign(
      new Error(responseData.message || '회원가입에 실패했습니다.'),
      {
        status: signUpResponse.status,
      },
    );
  }
  return oauthResponseSchema.parse(responseData);
}

export async function GET(request: NextRequest) {
  try {
    const code = request.nextUrl.searchParams.get('code');
    const state = request.nextUrl.searchParams.get('state');

    if (!code) {
      throw Object.assign(new Error('카카오 인증 코드가 없습니다.'), { status: 400 });
    }

    const nickname = state ? decodeURIComponent(state) : null;

    if (!nickname) {
      throw Object.assign(new Error('회원가입에 필요한 닉네임 정보가 없습니다.'), { status: 400 });
    }

    const responseData = await handleOauthSignUp(code, nickname);

    const response = NextResponse.redirect(new URL(ROUTES.ACTIVITIES.ROOT, request.url));

    setAuthCookies(response, {
      accessToken: responseData.accessToken,
      refreshToken: responseData.refreshToken,
    });

    return response;
  } catch (error: unknown) {
    // 에러 처리 로직...
  }
}

7. ⚠️ 사용 시 주의사항

• 인가코드 재사용 불가: 로그인 실패 후 회원가입 시 반드시 새 인가코드를 발급받아야 함.
• Transition Page 필수: 닉네임 입력을 위한 사용자 인터랙션이 없으면 회원가입이 불가능.
• 환경 변수 관리: REST API Key, Redirect URI는 .env 파일에서 안전하게 관리.
• 에러 처리 상세화: 로그인/회원가입 실패 시 UI와 메시지를 구분해 사용자 혼란 최소화.
• 토큰 보안: setAuthCookies에서 httpOnly/secure 옵션을 반드시 적용.
• OAuth UX 혼란 완화: 약관 동의가 연속으로 뜰 수 있으므로, Transition Page에서 UX를 설명하는 메시지 제공.

8. 📎 참고 파일 및 링크

• src/app/api/auth/kakao/signin/route.ts
• src/app/api/auth/kakao/signup/route.ts
• src/app/(auth)/kakao/transition/page.tsx
• src/domain/Auth/utils/setAuthCookies.ts
• src/domain/Auth/components/OAuth.tsx
• src/domain/Auth/forms/SignInForm.tsx
• src/domain/Auth/forms/SignUpForm.tsx
• 카카오 개발자 문서: 카카오 로그인 REST API
• Next.js BFF 환경에서 카카오 OAuth 인가 코드와 닉네임을 동시에 전달할 수 없는 문제 해결 #306
• `카카오 소셜 로그인, 회원가입 흐름 설계 전략`: 인가코드 일회성, 분리된 백엔드, UX 혼란 해결 #500