카카오 소셜 로그인, 회원가입 흐름 설계 전략: 인가코드 일회성, 분리된 백엔드, UX 혼란 해결

[sgoldenbird]

🐞 문제 상황 (Problem Description)

카카오 소셜 로그인 기능을 제공하며 다음과 같은 상황적인 제약으로 인해 구조에 대해 고민하게되었습니다:

• 카카오는 회원가입, 로그인을 통합 흐름으로 처리하는 것을 전제로 API를 제공
• 코드잇 백엔드 API는 회원가입, 로그인 두개로 분리되어 있음
• 카카오 인가코드가 일회성: 한 번 로그인 요청에 사용되면 재사용 불가 → 하나의 인가코드로 로그인 실패 후 회원가입으로 이어지는 흐름이 불가능
• 닉네임 파라미터 요구:
  • 카카오 회원가입 시 백엔드가 nickname과 token(=인가코드)를 함께 요구함. 그러나 이 시점에선 사용자의 닉네임을 카카오에서 받아올 수 없음
  • Next.js BFF 환경에서 카카오 OAuth 인가 코드와 닉네임을 동시에 전달할 수 없는 문제 해결 #306
• 카카오 동의서(약관 동의 UI)는 한번만 뜨고 동의 후에는 다시 나타나지 않음 → 항상 나타나게 하려면 서비스 신청, 심사 필요함.
  • 회원가입 하지 않은 상태에서 카카오로 로그인 버튼을 눌렀을때 약관 동의 UI가 먼저 나타나고 동의한 후에 회원가입 안됐다는걸 알게됨.
  • 이후 다시 카카오로 회원가입 할때는 약관 동의 UI가 나타나지 않음

---

💻 환경 정보 (Environment)

• 브라우저: Chrome 138
• 프론트엔드 프레임워크: React 19, Next.js
• 배포 환경: Vercel
• API 서버: 외부 REST API, 수정 불가

---

🔍 발생 원인 분석 (Investigation)

카카오 OAuth 자체는 로그인/회원가입 통합 흐름을 권장하지만, 우리 백엔드는 아래와 같은 이유로 완전한 통합 흐름을 구현하기 어려움:

• 인가코드는 한 번만 사용 가능하므로 하나의 인가코드로 "로그인 → 실패 → 회원가입" 흐름이 기술적으로 불가능
• 백엔드는 닉네임을 회원가입 시점에 요구하나, 카카오 API로부터 닉네임을 가져오기 전엔 해당 정보를 확보할 수 없음
• 계약서 동의는 로그인이던 회원가입이던 한번만 뜨고 동의 후에는 다시 나타나지 않음 → 항상 나타나게 하려면 서비스 신청, 심사 필요함.
  이로 인해 사용자 시나리오에서 다음과 같은 문제 발생:
  • 사용자: “카카오 로그인” 클릭 → 계약서 동의 → 회원이 아님 → 회원가입 페이지 이동, "카카오 회원가입" 클릭 → 추가 동의 없이 자동 회원가입 → 자동 로그인
  • 사용자 입장에서 계약서에 동의 후 회원가입으로 이어지는 연결 고리가 부족하고, 중간의 “회원이 아니라 로그인 실패 후 회원가입 페이지에서 다시 시작” 하는 흐름은 귀찮음과 혼란을 유발함, 유저 이탈 가능성이 높아짐.

---

🛠 시도해본 해결 방법 (Attempts)

✅방식 1: 단일 redirect URI, 두개의 버튼 → state 파라미터 활용 intent 분기, 분기된 흐름

• redirect URI: 단일 구현 api/auth/kakao/callback
• 버튼: 카카오 로그인, 카카오 회원가입
• api/auth/signin과 api/auth/signup 페이지에서 state=signin / state=signup을 OAuth 요청에 포함
  • 사용자가 누른 버튼 또는 페이지에 대한 정보를 state로 사용자가 로그인하려하는지 회원가입 하려하는지 의도 전달
• 카카오 로그인 콜백에서 state를 읽어 intent에 따라 로그인 또는 회원가입 API 호출

1단계: OAuth.tsx - 카카오로 떠날 때 state에 intent 담기

const kakaoAuthUrl = `https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${KAKAO_CLIENT_ID}&redirect_uri=${KAKAO_REDIRECT_URI}&state=${pageType}`;
window.location.href = kakaoAuthUrl;

2단계: callback/route.ts에서 state로 의도 분기

이제 콜백 API는 카카오로부터 사용자가 처음에 어떤 버튼을 눌렀는지(state) 알 수 있습니다.

const intent = req.nextUrl.searchParams.get('state');

if (intent === 'signup') {
  // 로그인 시도 없이 바로 회원가입 페이지로 이동
  const signupUrl = new URL('/signup', req.url);
  signupUrl.searchParams.set('email', email);
  signupUrl.searchParams.set('nickname', kakao_account.profile.nickname);
  signupUrl.searchParams.set('provider', 'kakao');
  signupUrl.searchParams.set('providerId', String(kakaoId));
  return NextResponse.redirect(signupUrl);
} else {
  // 로그인 시도 → 실패(404) 시 회원가입 페이지로 이동
  const signInRes = await fetch(...);
  if (signInRes.ok) {
    // 토큰 저장 및 리디렉션
  } else if (signInRes.status === 404) {
    const signupUrl = new URL('/signup', req.url);
    // 정보 추가 후 이동
    return NextResponse.redirect(signupUrl);
  }
}

❌ 단점

• ‘state’의 원래 목적 훼손
  • OAuth의 state는 요청-응답 짝을 검증하는 CSRF 방지용이 핵심.
  • 여기에 비즈니스 의도(intent)를 얹으면, 검증 로직과 라우팅 로직이 섞여 코드 복잡도↑, 리뷰 난이도↑, 보안 실수 여지↑
• 사용자가 잘못된 버튼(회원가입 없이 로그인)을 눌렀을 경우
  • 인가코드 소모 문제로 자동 전환이 불가능하여 인증 절차 후 실패 → 다시 회원가입 버튼 클릭 하는 흐름이 사용자 입장에서 귀찮고 이탈자 발생 가능성이 높아짐.
  • 계약서 동의는 로그인 시점에만 발생하므로 UX가 역순처럼 느껴짐 (→ 로그인버튼 눌렀을때 동의했기 때문에 정작 회원가입은 동의 절차 없이 바로 됨)
    • 로그인 실패 → 약관 동의 후 → “회원가입 먼저 하세요” 안내 → 다시 회원가입 → 약관 없이 바로 가입 처리됨 → 혼란
    • 로그인 → 약관 동의 → 회원가입 이동이라는 UX가 어색함

✅방식 2: 두개의 redirect URI, 두개의 버튼, 분기된 흐름

• redirect URI: 이원화 api/auth/kakao/signin, api/auth/kakao/signup
• 버튼: 카카오 로그인, 카카오 회원가입
• state를 사용하지 않고 각각의 redirect URI로 보내서 처리

❌단점

• 사용자 입장에서 잘못된 버튼(회원가입 없이 로그인)을 눌렀을 경우, UX 흐름은 방식1과 같아서 동일한 UX, 이탈자 문제 발생.

✅방식 3: 두개의 redirect URI, 하나의 통합 버튼, 하나의 흐름

• redirect URI: 이원화 api/auth/kakao/signin, api/auth/kakao/signup
• 버튼: 카카오로 시작하기
• 새로운 인가코드를 각각 두번 받도록 변경.
• 흐름:

1. 사용자가 카카오로 시작하기 버튼 클릭(로그인페이지 또는 회원가입 페이지에서)
2. 약관 동의 UI
3. 인가 코드 요청 및 리디렉션
   • 사용자가 동의를 마치면, 카카오는 인가 코드를 발행하여 api/auth/kakao/signin 리디렉션 URI로 전달합니다.
   • 이는 SignInForm.tsx에서 handleKakaoLogin 함수를 통해 시작됩니다.
4. api/auth/kakao/signin 라우트 핸들러가 인가 코드를 받아 로그인 API를 호출
   • 회원가입된 유저: 로그인에 성공하고 사용자 정보와 토큰을 쿠키에 저장한 후 메인 페이지로 리디렉션됩니다.
   • 회원가입이 안된 유저: 백엔드는 403 Forbidden 에러를 반환하며 로그인에 실패합니다. (백엔드는 없는 유저를 403으로 처리하고 있음)
5. KakaoTransition 페이지로 이동
   • 등록되지 않은 사용자니 회원가입 먼저 하라는 메시지가 표시
   • RoamReady에서 사용할 닉네임 입력
   • Next.js BFF 환경에서 카카오 OAuth 인가 코드와 닉네임을 동시에 전달할 수 없는 문제 해결 #306 참고
   • 계속하기 버튼 클릭
6. 약관 동의 UI
7. 새로운 인가코드 요청 및 리디렉션
   • 사용자가 동의를 마치면, 카카오는 인가 코드를 발행하여 api/auth/kakao/signup 리디렉션 URI로 전달합니다.
8. 인가코드와 사용자가 입력한 닉네임으로 회원가입 후 자동 로그인
   • api/auth/kakao/signup 라우트 핸들러가 새로운 인가 코드와 사용자가 입력한 닉네임을 받아 회원가입 API를 호출하고, 성공 시 바로 로그인 처리 후 메인 페이지로 리디렉션됩니다.

---

✅ 최종 해결 방법 (Final Solution)

방식 3 (두 개의 redirect URI + 하나의 통합 버튼 + 인가코드 두 번 발급) 으로 구현

• 버튼은 “카카오로 시작하기” 하나만 제공
• 로그인과 회원가입을 각각 별도의 redirect URI(api/auth/kakao/signin, api/auth/kakao/signup)로 처리
• 로그인 시도 → 실패 시 회원가입 페이지로 이동하여 닉네임 입력 → 새로운 인가코드를 발급받아 회원가입 진행
• 회원가입 성공 시 자동으로 로그인 처리 후 메인 페이지로 리디렉션

이 방식으로

• 카카오 인가코드의 일회성 제약 문제를 해결
• 백엔드의 닉네임 파라미터 요구사항을 충족
• 로그인과 회원가입의 흐름을 명확하게 분리할 수 있었다.

---

💡 알게 된 점 (Lessons Learned)

인가 코드의 일회성

• 카카오 OAuth 인가 코드는 한 번만 사용할 수 있으며,
  한 번 로그인 시도에 사용되면 같은 코드로 회원가입 시도는 불가능하다.
• 따라서 로그인 → 실패 → 회원가입 자동 시도 같은 흐름은 기술적으로 불가능하다는 점을 알게 되었음.

redirect uri 분리의 필요성

• 로그인과 회원가입을 명확히 분리된 redirect URI로 처리함으로써 사용자의 의도를 정확하게 반영할 수 있고,
• 각각의 인증 흐름에서 새로운 인가 코드를 받을 수 있도록 만들면 인증 흐름이 끊기지 않을 수 있다.

백엔드 API 스펙의 영향

• 카카오로부터 닉네임을 받을 수 없고, 백엔드 API는 nickname 파라미터를 필수로 요구하여, kakao transition page를 만들고 사용자로부터 닉네임을 입력받도록 설계했음 → 백엔드 API 설계에 따라 클라이언트 흐름도 바뀐다는 점을 체감.

사용자 경험과 인증 흐름의 균형

• 분기된 흐름(방식1,2)의 경우 로그인 도중 계약서 동의를 받고, 이후 회원가입으로 전환하면 회원가입 단계에서 다시 동의를 받지 않는 구조가 시맨틱하게 어색
• 하나의 흐름(방식 3) 인가코드를 연이어 두번 발급받을 경우, 연이어 약관 동의 UI가 나타나 UX 혼란, 어색 → UX를 고려해 kakao transition page를 생성. 사용자가 두 번의 동의 과정을 자연스럽게 납득할 수 있도록 흐름을 설계.

---

🔗 참고자료 / 관련 이슈, PR

• Next.js BFF 환경에서 카카오 OAuth 인가 코드와 닉네임을 동시에 전달할 수 없는 문제 해결 #306
• OAuth(Kakao) 흐름 #302
• Refactor: refactoring2 #444
• Feat: 카카오 OAuth redirect URI 분리 #496