TASK-005 OAuth 로그인 구현

이번 TASK-005에서는 vibePulse의 로그인 흐름을 구현했습니다.

처음에는 인증을 조금 더 넓게 생각했습니다. 회원가입은 사용자가 최대한 편해야 하니까 OAuth는 당연히 필요했고, 이메일 가입도 같이 넣는 방향을 떠올렸습니다. 한국인 바이브코더들도 고객이 될 수 있으니 카카오와 네이버 로그인도 처음부터 같이 고려했습니다.

겉으로 보면 자연스러운 선택처럼 보였습니다. Google, GitHub, Kakao, Naver, 이메일까지 있으면 사용자는 원하는 방식으로 가입할 수 있습니다. 그런데 실제로 구현 범위와 운영 부담을 하나씩 따져보니 생각이 조금씩 바뀌었습니다.

이번 타스크에서 중요한 건 로그인 옵션을 많이 보여주는 것이 아니었습니다. vibePulse의 첫 목표는 사용자가 가입 후 빠르게 대시보드에 들어오고, 온보딩을 거쳐 첫 모니터를 만드는 흐름을 완성하는 것이었습니다.

그래서 이번에는 Google과 GitHub 로그인에 집중하고, Kakao·Naver·이메일 가입은 필요성이 확인됐을 때 후속 TASK로 미루기로 결정했습니다.

처음 생각한 인증 범위

처음에는 이렇게 생각했습니다.

“로그인은 한 번 만들 때 넉넉하게 넣는 게 좋지 않을까?”

특히 한국 사용자를 생각하면 카카오와 네이버는 꽤 자연스러운 선택지처럼 보였습니다. 이메일 가입도 마찬가지였습니다. 특정 소셜 계정을 쓰고 싶지 않은 사용자에게는 이메일이 가장 익숙한 방식일 수 있기 때문입니다.

초기 구상은 대략 이랬습니다.

여기서 잠깐 멈췄습니다.

많이 넣는 것과 지금 필요한 것을 넣는 것은 달랐습니다. 특히 인증은 화면에 버튼 하나 추가하는 것으로 끝나지 않았습니다. provider 콘솔 설정, redirect URI, 환경 변수, 에러 처리, allowlist, 계정 연결, 테스트 범위가 같이 따라왔습니다.

처음에는 금방 끝날 줄 알았습니다. 그런데 다시 보니 문제는 코드가 아니라 범위의 기준이었습니다.

카카오와 네이버를 잠시 내려놓은 이유

카카오와 네이버는 한국 사용자에게 좋은 선택지입니다. 이 판단 자체가 바뀐 것은 아닙니다. 다만 이번 타이밍에 꼭 붙여야 하는지는 다시 봐야 했습니다.

카카오를 예로 들면 단순히 client id와 secret만 넣으면 끝나는 구조가 아니었습니다. 카카오 개발자 콘솔에서 앱을 만들고, redirect URI를 맞추고, 동의항목을 설정해야 했습니다. 이메일을 쓰려면 동의항목 권한과 검수 흐름까지 확인해야 했습니다. 경우에 따라 비즈니스 인증도 필요했습니다.

네이버도 마찬가지로 별도 콘솔 설정과 callback 관리가 필요했습니다.

반면 vibePulse의 초기 타겟은 바이브코더와 개발자에 가깝습니다. 이 사용자들은 대부분 Google 계정을 가지고 있을 가능성이 높고, 개발자라면 GitHub 계정도 자연스럽게 연결됩니다.

그래서 판단을 이렇게 바꿨습니다.

“한국 서비스를 만든다고 해서 처음부터 모든 한국형 로그인을 붙여야 하는 건 아닙니다. 지금 사용자에게 가장 빨리 닿는 경로가 무엇인지 먼저 봐야 했습니다.”

이번에는 Google과 GitHub만 UI에 노출하기로 했습니다. Kakao와 Naver는 완전히 버린 것이 아니라, 백엔드와 설정 구조는 나중에 켤 수 있도록 열어두고 UI에서는 숨겼습니다.

구조적으로는 이런 방향이었습니다.

지금 노출
- Google
- GitHub

나중에 활성화
- Kakao
- Naver

후속 TASK
- 이메일/비밀번호 가입
- Magic link
- 팀 초대 기반 이메일 흐름

이렇게 나누고 나니 TASK-005의 목적이 더 선명해졌습니다. 이번 작업은 “인증 옵션 5종 완성”이 아니라 초기 사용자에게 충분한 로그인과 온보딩 흐름을 안정적으로 만드는 것이었습니다.

이메일 가입은 왜 미뤘나

이메일 가입도 처음에는 같이 넣고 싶었습니다. 소셜 계정을 원하지 않는 사용자도 있을 수 있고, 이메일은 가장 보편적인 방식처럼 보였기 때문입니다.

하지만 이메일 가입은 제대로 만들지 않으면 오히려 애매해집니다.

이메일 가입을 넣는다는 것은 보통 아래 작업을 함께 의미합니다.

• 이메일 인증
• 비밀번호 재설정
• 비밀번호 정책
• 트랜잭션 메일 발송
• 스팸·봇 가입 방지
• 인증되지 않은 계정 처리
• 로그인 실패와 계정 잠금 정책

폼 하나를 만드는 문제가 아니었습니다. 특히 vibePulse는 아직 초기 제품이고, 이번 TASK의 핵심은 “가입 후 첫 모니터까지 가는 흐름”이었습니다.

이메일 가입은 사용자가 실제로 필요로 한다는 신호가 보였을 때 별도 TASK로 여는 편이 더 맞다고 판단했습니다.

예를 들면 이런 신호가 있을 때입니다.

지금은 “혹시 모르니까”라는 이유만으로 넣기에는 구현과 운영 비용이 컸습니다. 이 결정을 문서에도 남겼습니다. 나중에 다시 논의할 때 감정이나 느낌이 아니라, 어떤 기준으로 미뤘는지 볼 수 있게 하기 위해서였습니다.

아래 섹션을 ## Better Auth로 로그인 흐름 만들기 앞에 추가하면 가장 자연스럽습니다. 앞에서는 “왜 Google/GitHub만 먼저 하기로 했는가”를 다루고, 이 섹션에서 “그럼 인증 라이브러리는 왜 Better Auth였는가”로 이어지는 흐름입니다.

왜 Better Auth였나

로그인 provider 범위를 줄인 뒤에는 인증 라이브러리도 다시 봤습니다. 처음부터 직접 구현하는 선택지도 있었고, Auth.js, Clerk, Auth0 같은 선택지도 있었습니다. 겉으로 보면 모두 “로그인을 붙이는 도구”처럼 보였지만, vibePulse의 TASK-005 기준으로 보면 중요하게 봐야 할 지점이 조금 달랐습니다.

이번에 제가 본 기준은 단순했습니다.

• OAuth를 빠르게 붙일 수 있는가
• DB와 사용자 데이터를 프로젝트 안에서 직접 다룰 수 있는가
• org, member, subscription 같은 제품 리소스와 연결하기 쉬운가
• 나중에 팀 기능이나 권한 구조로 확장할 수 있는가
• 초기 SaaS에 과한 외부 의존이나 비용을 만들지 않는가

처음에는 Auth.js도 자연스러운 후보였습니다. Next.js 생태계에서 오래 쓰였고, OAuth provider를 붙이는 방식도 익숙합니다. 실제로 OAuth와 세션을 직접 구성하기에는 좋은 선택지였습니다. 다만 vibePulse에서는 로그인 직후에 organization, member, default project, free subscription을 바로 만들어야 했습니다. 단순 세션 처리보다 제품 데이터와의 결합이 더 중요했습니다.

Clerk도 후보였습니다. UI 컴포넌트와 hosted auth 경험이 좋고, organization 같은 B2B 기능도 빠르게 붙일 수 있습니다. 하지만 이번 단계에서는 인증을 빠르게 붙이는 것만큼이나 우리 DB 안에서 흐름을 명확히 보고 싶다는 요구가 있었습니다. 초기 제품에서 외부 서비스의 편리함을 얻는 대신, 인증과 프로비저닝 흐름이 블랙박스처럼 느껴지는 것은 조금 부담스러웠습니다.

Auth0는 더 엔터프라이즈에 가까운 선택지로 봤습니다. 기능은 강하지만 vibePulse의 TASK-005에는 무거웠습니다. 지금 필요한 것은 거대한 인증 플랫폼이 아니라, OAuth 로그인과 제품 초기 리소스 생성을 안정적으로 연결하는 것이었습니다.

그래서 Better Auth가 더 잘 맞는다고 판단했습니다.

Better Auth는 앱 안에서 인증을 구성하는 방향이 vibePulse와 잘 맞았습니다. Next.js와 통합할 수 있고, organization plugin도 제공하기 때문에 이후 조직·멤버·권한 구조로 확장할 여지가 있었습니다. 공식 문서에서도 organization plugin은 조직의 멤버와 팀을 관리하는 용도로 설명하고, generic OAuth plugin은 OAuth 2.0과 OIDC 기반 provider 확장을 다룹니다.  

물론 Better Auth라고 해서 모든 것이 편하기만 한 것은 아니었습니다. 실제로 작업 중에는 better-call 버전 충돌이 있었습니다. better-auth가 기대하는 버전과 CLI 쪽 의존성이 끌고 온 버전이 달라 API가 깨졌고, 결국 workspace override로 버전을 맞춰야 했습니다.

여기서 다시 한 번 느꼈습니다.

라이브러리를 고른다는 것은 “문제를 없애는 것”이 아니라, 내가 감당할 문제의 종류를 고르는 일이었습니다.

Clerk를 골랐다면 hosted auth와 빠른 UI의 장점을 얻었을 겁니다. 대신 외부 서비스 의존과 제품 데이터 연결 방식을 더 신경 써야 했을 것입니다. Auth.js를 골랐다면 익숙한 OAuth 흐름을 얻었겠지만, organization과 프로비저닝 구조는 더 직접 만들어야 했을 가능성이 큽니다. Better Auth를 고르면서는 앱 내부 통제와 확장성을 얻는 대신, 패키지 버전이나 설정 문제를 직접 다루게 됐습니다.

이번 TASK-005에서는 그 교환이 괜찮다고 봤습니다.

vibePulse는 아직 초기 제품이고, 인증 이후에 바로 org와 project를 만들고 온보딩으로 연결하는 흐름이 중요했습니다. 그래서 외부 hosted auth보다 프로젝트 내부에서 인증과 제품 데이터를 함께 다루는 구조가 더 적합했습니다.

결국 Better Auth를 선택한 이유는 “가장 유명해서”가 아니라, vibePulse의 초기 SaaS 구조와 가장 잘 맞는 책임 범위를 가지고 있었기 때문입니다.

Better Auth로 로그인 흐름 만들기

구현은 Better Auth를 중심으로 진행했습니다.

OAuth provider를 설정하고, /api/auth/* 핸들러를 만들고, 로그인·회원가입 화면에서 Google과 GitHub 로그인을 연결했습니다. 단순히 로그인만 성공하는 것이 아니라, 가입 직후 vibePulse를 바로 사용할 수 있도록 기본 리소스도 생성해야 했습니다.

첫 로그인 후 생성되는 기본 흐름은 이렇게 잡았습니다.

OAuth 로그인 성공
└─ User 생성
   └─ Organization 생성
      ├─ Member owner 연결
      ├─ Default project 생성
      └─ Free subscription 생성

이 부분은 중요했습니다. 사용자가 로그인한 뒤 빈 화면을 보는 것이 아니라, 바로 온보딩으로 이어져야 했습니다. vibePulse는 모니터링 제품이기 때문에 사용자가 가장 빨리 경험해야 하는 것은 “계정 생성”이 아니라 첫 모니터 생성이었습니다.

그래서 로그인 성공 후 다음 항목이 실제 DB에 만들어지는지 확인했습니다.

이 확인을 하고 나서야 로그인 구현이 단순히 “버튼을 누르면 들어간다” 수준을 넘었다고 느꼈습니다. 인증은 입구이고, 입구 다음에는 바로 사용할 수 있는 최소한의 공간이 있어야 했습니다.

dev allowlist를 넣으면서 생긴 일

로컬과 dev 환경에서는 아무 계정이나 로그인할 수 있으면 곤란합니다. 그래서 AUTH_ALLOWED_ACCOUNTS 기반 allowlist를 넣었습니다. 허용된 이메일이나 provider id만 로그인할 수 있게 했습니다.

처음에는 기능 자체만 보면 단순했습니다.

if local or dev:
  allow listed account only
else:
  allow normal sign in

그런데 실제 테스트를 해보니 사용자 경험이 문제였습니다. allowlist에 없는 계정으로 로그인하면 Better Auth의 기본 에러 페이지로 떨어졌습니다. 기능적으로는 막힌 것이 맞지만, 제품 입장에서는 어색했습니다.

사용자는 vibePulse 로그인 화면에서 시작했는데, 실패했을 때 라이브러리 기본 에러 페이지를 보게 됩니다. 이건 좋은 UX가 아니었습니다.

그래서 에러 흐름을 다시 잡았습니다.

이 작은 수정이 생각보다 중요했습니다. 인증에서 성공 경로만큼 중요한 것이 실패 경로였습니다.

로그인할 수 없을 때도 사용자는 제품 안에 남아 있어야 했습니다.

i18n에서 다시 만난 UX 문제

이번 작업 중 의외로 시간을 쓴 부분이 언어 설정이었습니다.

vibePulse는 한국어를 기본 locale로 두고, 영어는 /en prefix를 붙이는 구조였습니다. 처음에는 next-intl의 기본 흐름대로 브라우저 언어를 감지하고, 사용자가 언어를 바꾸면 쿠키에 저장하는 방식이었습니다.

원칙은 괜찮았습니다.

하지만 실제로 테스트해보니 어색한 지점이 있었습니다. 브라우저가 영어 우선이면 /en/login으로 들어가고, 로그인 후에도 영어 화면에 머무는 일이 생겼습니다. 대시보드와 온보딩에는 언어 전환 UI가 없어서, 사용자는 영어에 갇힌 것처럼 느낄 수 있었습니다.

여기서 다시 생각이 바뀌었습니다.

“기술적으로 정상 동작”과 “제품 UX로 자연스러운 동작”은 달랐습니다.

그래서 대시보드와 온보딩에도 언어 전환을 넣고, 사용자가 KO/EN을 선택하면 NEXT_LOCALE 쿠키에 저장되도록 수정했습니다. 또한 OAuth callback과 로그인 리다이렉트에서도 locale이 유지되도록 경로를 정리했습니다.

중간에 .next 개발 캐시가 깨져 JSON parse error가 나기도 했습니다. 처음에는 메시지 파일 문제인가 싶었지만, 실제 원인은 Next.js dev cache였습니다. .next를 지우고 다시 빌드하니 정상으로 돌아왔습니다.

이런 시행착오는 작지만 기억에 남았습니다. 에러 메시지는 언어 파일을 가리키는 것처럼 보였지만, 실제 원인은 다른 곳에 있었습니다. 로그를 보고 바로 단정하지 않고, 파일 자체와 빌드 결과를 나눠 확인해야 했습니다.

로그인 화면을 다듬는 과정

기능이 붙은 뒤에는 로그인 화면도 여러 번 다듬었습니다.

처음에는 OAuth 버튼 4개를 기준으로 UI를 생각했습니다. 하지만 최종적으로 Google과 GitHub만 노출하기로 하면서 화면도 더 단순해졌습니다.

중간에 시도한 것들은 꽤 많았습니다.

• Google, GitHub, Kakao, Naver 아이콘 정리
• Kakao/Naver 공식 리소스 확인
• 2열 그리드에서 1열 버튼으로 변경
• 버튼 설명 문구 제거
• 우측 화살표 제거
• 카드 높이 축소
• 로그인 중 스피너 개선
• allowlist 에러 배너 강조
• 로그인 문구 톤 조정

특히 “연결 중” 상태를 보여주는 방식도 여러 번 바꿨습니다. 처음에는 전용 연결 패널까지 만들었지만, 실제로 보니 너무 과했습니다. 로그인 버튼을 누르는 짧은 순간에 전체 화면 전환처럼 보이는 피드백은 오히려 무거웠습니다.

결국 다시 작은 스피너 방식으로 돌아왔습니다. 다만 클릭한 버튼만 강조하고, 나머지 버튼은 비활성화해서 사용자가 지금 어떤 provider로 이동 중인지 알 수 있게 했습니다.

여기서 배운 점은 단순했습니다.

작은 인터랙션은 멋있게 만드는 것보다, 사용자가 방금 한 행동을 조용히 확인시켜 주는 정도가 더 좋을 때가 많았습니다.

로딩 애니메이션도 CSS와 motion 사이에서 고민했습니다. 로그인 로딩처럼 React 상태와 직접 연결되는 UI는 motion으로 정리했습니다. 반면 마케팅 페이지의 정적인 애니메이션은 CSS로 유지했습니다.

이 결정도 문서에 남겼습니다. 지금 당장은 작은 차이지만, 나중에 “왜 여기는 motion이고 저기는 CSS인가”를 다시 묻게 될 수 있기 때문입니다.

온보딩까지 이어지는지 확인하기

로그인이 끝난 뒤에는 온보딩이 실제로 이어지는지 확인했습니다.

이번 TASK-005의 온보딩은 3가지 경로를 기준으로 잡았습니다.

실제 테스트에서는 URL 프로브 경로를 먼저 확인했습니다. https://example.com을 넣고 모니터가 생성되는지 봤습니다. 이후 DB에서 모니터가 생성되고, onboardingCompleted 값이 true로 바뀐 것도 확인했습니다.

대시보드에서는 상태가 “확인 중”으로 보였습니다. 처음에는 이게 이상한가 싶었지만, 아직 반복 프로브 스케줄러는 TASK-007 범위였습니다. 즉 온보딩 중 즉시 프로브는 통과했지만, 주기적인 체크 결과는 아직 없는 상태였습니다.

이런 부분은 제품에서 특히 조심해야 합니다. 개발자는 “아직 스케줄러가 없으니까 pending이 맞다”고 생각할 수 있지만, 사용자는 “왜 확인 중이지?”라고 느낄 수 있습니다. 이번 TASK에서는 범위 밖으로 두되, 다음 작업에서 상태 표현을 더 자연스럽게 볼 필요가 있다고 느꼈습니다.

이번 TASK에서 실제로 남은 기준

TASK-005를 진행하며 구현한 것은 많았지만, 마지막에 다시 정리해보면 핵심은 몇 가지였습니다.

• Google/GitHub OAuth 로그인
• dev allowlist
• 첫 로그인 시 기본 리소스 생성
• 로그인 후 대시보드 보호
• 온보딩 진입과 완료
• locale 유지
• allowlist 실패 UX
• Kakao/Naver UI 숨김
• 이메일 가입 deferred 문서화

Ship 전에 사람이 확인해야 할 항목도 남겼습니다.

• 최소 1개 OAuth provider로 로그인 성공
• 신규 가입 후 org / project / subscription 생성 확인
• URL 온보딩 경로 완료
• 로그인 후 새로고침 시 세션 유지 확인
• allowlist 허용 계정 성공
• allowlist 거부 계정 최종 확인
• Docker build 확인
• dev 배포 환경에서 callback 재확인

여기서도 전부 한 번에 끝내려고 하지 않았습니다. 로컬에서 Google/GitHub 기준의 핵심 경로를 확인하고, Kakao/Naver와 이메일은 후속 작업으로 남겼습니다. Docker build나 dev 배포 callback처럼 환경 의존성이 있는 항목은 ship 전 또는 CI에서 확인하는 쪽으로 정리했습니다.

결국 로그인은 버튼보다 기준의 문제

이번 TASK를 하면서 가장 많이 생각한 것은 “로그인을 몇 개 넣을까”가 아니었습니다.

진짜 질문은 이것에 가까웠습니다.

지금 사용자가 첫 성공까지 가는 데 꼭 필요한 인증 흐름은 무엇인가?

처음에는 이메일도 넣고, 카카오도 넣고, 네이버도 넣는 쪽이 더 좋아 보였습니다. 하지만 vibePulse의 현재 타겟과 TASK 범위를 기준으로 보면 Google과 GitHub만으로도 충분했습니다. 오히려 나머지를 지금 붙이려다 보면 첫 모니터까지 가는 핵심 흐름이 늦어질 수 있었습니다.

그래서 이번 선택은 “덜 만든 것”이 아니라, 지금 검증해야 할 흐름을 더 선명하게 만든 것에 가까웠습니다.

물론 이 결정이 영원히 유지되는 것은 아닙니다. 국내 사용자 비중이 늘고, 카카오나 네이버 요청이 실제로 보이면 그때 다시 TASK를 열면 됩니다. B2B나 팀 초대가 필요해지면 이메일 기반 흐름도 다시 볼 수 있습니다.

이번에는 거기까지 가지 않았습니다.

OAuth 로그인은 Google과 GitHub로 시작했습니다. 그리고 그 선택 덕분에 Better Auth, allowlist, 기본 리소스 생성, 온보딩, locale UX, 로그인 실패 처리까지 더 깊게 볼 수 있었습니다.

goodtek은 이런 선택과 시행착오를 계속 기록하려고 합니다. 완성된 기능만 남기면 간단해 보이지만, 실제 빌드는 대부분 이런 작은 갈림길에서 방향을 정하는 일에 가까웠습니다. 다음 작업에서도 “지금 필요한 것”과 “나중에 해도 되는 것”을 계속 나눠보겠습니다.