Next.js BFF 환경에서 카카오 OAuth 인가 코드와 닉네임을 동시에 전달할 수 없는 문제 해결

[sgoldenbird]

🐞 문제 상황 (Problem Description)

카카오 회원가입 연동 시, 백엔드 API가 닉네임과 인가 코드를 동시에 요청 파라미터로 요구하고 있습니다.
하지만 카카오의 정책상, 닉네임을 가져오기 위해서는 인가 코드를 사용해 먼저 액세스 토큰을 발급받아야 하며, 이 과정에서 인가 코드는 소진됩니다.
따라서 사용된 인가 코드와 함께 닉네임을 백엔드에 전달하면, 백엔드는 이를 "잘못된 인가 코드"로 간주하고 요청을 거부합니다.
결과적으로, 현재 API 명세에서는 닉네임과 유효한 인가 코드를 동시에 백엔드에 전달하는 것이 기술적으로 불가능한 상황입니다.

---

💻 환경 정보 (Environment)

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

---

🔍 발생 원인 분석 (Investigation)

• 카카오 OAuth 플로우의 구조적 제약(카카오 인가 코드의 일회성)
  카카오 OAuth 2.0 흐름에서 발급된 인가 코드는 액세스 토큰으로 교환되는 즉시 소진되는 일회성 토큰입니다. 한 번 사용되면 재사용할 수 없습니다.

• 백엔드 API 명세의 구조적 모순
  백엔드 API는 nickname (사용자 식별용)과 카카오 인가 코드 (스웨거 명세상 token으로 표기)를 동시에 필수로 요구하지만, 닉네임을 가져오는 순간 인가 코드는 소진됩니다.

• BFF 구조에서의 문제점
  BFF에서 닉네임을 받아오기 위해 인가 코드를 소진하면, 이후 백엔드에는 더 이상 유효하지 않은 코드를 전달하게 됩니다.

---

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

• ❌ BFF에서 카카오 인가 코드를 액세스 토큰으로 교환 후 닉네임과 함께 백엔드에 전달

  • 시도: 프론트엔드에서 인가 코드를 받아 BFF로 전달 -> BFF가 카카오 API와 통신하여 인가 코드를 액세스 토큰으로 교환하고, 사용자 프로필(닉네임 포함)을 가져옴 -> BFF에서 이 액세스 토큰과 닉네임을 백엔드 API에 전달.
  • 문제점: 스웨거 명세를 확인 결과, 백엔드에서 요구하는 token 값은 카카오 액세스 토큰이 아닌 인가 코드였으며, 동시에 nickname도 필수로 요구했습니다. 이 방식으로는 백엔드의 요구사항을 충족시킬 수 없었습니다.

• ❌ BFF에서 사용자 정보를 가져온 후 인가 코드와 닉네임을 백엔드로 전달
  → 동일하게 인가 코드 재사용 불가

• ✅ 닉네임을 임의로 생성하여 API 요구사항 우회
  → 임의의 string으로 닉네임을 만들어 백엔드에 전달

• ✅ transition page를 두고 사용자로부터 닉네임을 입력받아 백엔드에 전달

---

✅ 최종 해결 방법 (Final Solution)

transition page를 두고 사용자로부터 닉네임을 입력받아 백엔드에 전달하는 방식으로 구현

문제의 핵심은 카카오 인가 코드의 일회성과 백엔드 API가 nickname 및 token을 동시에 요구하는 구조적 불일치였습니다.
이를 해결하기 위해, 다음과 같은 2단계 인증 및 회원가입 플로우를 구축했습니다.

1. 로그인 시도 및 인가 코드 소진:

• 사용자가 '카카오로 시작하기' 버튼을 클릭하면, api/auth/kakao/signin 리디렉션 URI로 인가 코드를 받습니다.
• 이 인가 코드를 백엔드의 로그인 API에 전달하여 기존 사용자 여부를 확인합니다.
• 이 과정에서 인가 코드는 소진됩니다. 회원가입이 필요한 사용자의 경우 백엔드는 403 Forbidden 에러를 반환합니다.

2. 회원가입 플로우 재시작:

• 로그인 실패(403) 시, 프론트엔드는 사용자에게 회원가입이 필요함을 알리는 transition page(src/app/(auth)/kakao/transition/page.tsx)로 이동합니다.
• 이 페이지는 사용자에게 닉네임을 입력받는 UI를 제공합니다.
• 사용자가 닉네임을 입력하고 '계속하기' 버튼을 클릭하면, api/auth/kakao/signup 리디렉션 URI로 새로운 인가 코드를 다시 요청합니다.
• 새롭게 발급된 인가 코드는 state 파라미터에 담긴 닉네임 정보와 함께 백엔드 회원가입 API에 직접 전달됩니다.

3. 회원가입 성공 및 자동 로그인:

• 백엔드 API는 전달받은 인가 코드를 직접 사용하여 액세스 토큰을 교환하고, 사용자 정보를 가져와 회원가입을 완료합니다.
• 회원가입 성공 시, 서버는 토큰을 발급하고, 클라이언트는 이를 쿠키에 저장하여 자동 로그인이 이루어집니다.

이 방법으로 백엔드 API를 수정하지 않고도 클라이언트와 BFF 단에서 복잡한 정책 불일치를 해소했습니다.

---

💡 알게 된 점 (Lessons Learned)

OAuth Provider 정책 이해의 중요성:
카카오와 같은 외부 인증 제공자의 OAuth 흐름(특히 인가 코드의 일회성)을 정확히 이해하는 것이 중요합니다.

API 명세의 명확성 및 일관성 요구:
외부 API와의 연동 시, API 명세가 백엔드의 내부 로직(예: 인가 코드를 직접 사용하는지, 액세스 토큰을 받는지)을 명확하게 반영해야 프론트엔드/BFF에서 올바른 흐름을 설계할 수 있습니다. token이라는 모호한 필드명과 nickname 동시 요구는 오해를 불러일으켰습니다.

BFF의 역할 재정립:
BFF는 단순히 요청을 포워딩하는 프록시 역할뿐만 아니라, 클라이언트와 백엔드 API 사이의 변환 계층으로서의 역할이 중요합니다. 특히 외부 서비스(카카오)의 정책과 내부 백엔드 API의 요구사항이 불일치할 때, BFF가 이 불일치를 해소하는 로직(예: 인가 코드-액세스 토큰 교환, 임시 닉네임 생성 등)을 수행하여 복잡성을 캡슐화할 수 있습니다.

유연한 백엔드 API 설계의 필요성:
카카오와 같은 서비스 연동에서 redirect uri는 필수적이며, 이를 처리할 수 있는 서버(BFF 또는 백엔드)가 필요합니다. 백엔드가 이러한 OAuth 흐름을 유연하게 처리할 수 있도록 설계되지 않으면, 프론트엔드/BFF 단에서 복잡한 우회 로직을 구현해야 할 수 있습니다. 닉네임과 같은 사용자 정보는 인가 코드를 통해 가져올 수 있는 부가 정보이므로, 회원가입 시점에 필수로 요구하기보다 이후 업데이트하는 방식으로 유연성을 확보하는 것이 바람직할 수 있습니다.

협업과 정보 공유:
문제 발생 시 백엔드 팀 또는 관련 담당자와의 긴밀한 소통을 통해 API 명세의 의도를 정확히 파악하고, 기술적인 제약 사항을 공유하여 최적의 해결책을 도출하는 것이 중요합니다.