카카오 소셜 로그인 연결하기 — 카카오 개발자 콘솔 설정부터 .env 연동까지
카카오 OAuth 로그인을 웹 앱에 붙이는 전 과정. 개발자 콘솔에서 앱 생성·REST API 키·Redirect URI 설정 → KAKAO_CLIENT_ID·KAKAO_REDIRECT_URI 를 .env 에 넣기까지. 흔한 에러(KOE006) 해결 포함.
카카오 소셜 로그인(카카오 OAuth)을 웹 앱에 붙이는 전 과정 — 카카오 개발자 콘솔에서 앱을 만들고, REST API 키·Redirect URI 를 설정해,
.env의KAKAO_CLIENT_ID·KAKAO_REDIRECT_URI를 채워 로그인 버튼을 살리는 것까지 정리했습니다. 인증 코드는 이미 구현되어 있고 설정만 하면 되는 상황을 전제로 합니다.
들어가며
회원가입 폼을 만들지 않아도 되는 가장 쉬운 로그인이 소셜 로그인입니다. 한국 서비스라면 대부분 카카오 로그인이 1순위죠 — 사용자는 이미 카카오 계정이 있고, 클릭 한 번이면 끝이니까요.
카카오 로그인은 표준 OAuth 2.0 Authorization Code 방식입니다. 우리 앱은 이미 이 흐름(인가 요청 → 콜백 → 토큰 교환 → 세션 발급)이 구현되어 있어서, 카카오 개발자 콘솔에서 앱을 등록하고 키 3개를 .env 에 넣으면 바로 동작합니다.
OAuth 로그인 흐름 한눈에
핵심은 Redirect URI 입니다. 카카오가 로그인 성공 후 code 를 돌려보낼 주소인데, 콘솔에 등록한 주소와 앱이 요청하는 주소가 한 글자도 다르면 안 됩니다. 대부분의 에러가 여기서 납니다.
준비물
- 카카오 계정 (그리고 카카오 개발자 가입)
- 앱이 돌아가는 주소 (개발:
http://localhost:10380, 운영: 실제 도메인) -
.env파일 편집 권한
낯선 용어 사전
| 용어 | 쉬운 설명 |
|---|---|
| REST API 키 | 앱을 식별하는 공개 키. OAuth 의 client_id 로 쓰임 → KAKAO_CLIENT_ID |
| Client Secret | 토큰 교환 시 쓰는 비밀 값. 켜면 보안↑ (선택) → KAKAO_CLIENT_SECRET |
| Redirect URI | 로그인 후 카카오가 code 를 돌려보낼 앱 주소 |
| 동의항목(Scope) | 사용자에게 받는 정보(닉네임·프로필사진·이메일 등) |
| Authorization Code | 카카오가 잠깐 주는 1회용 코드. 이걸 액세스 토큰으로 교환 |
1단계 — 카카오 개발자 앱 만들기
- developers.kakao.com 로그인 → 우상단 내 애플리케이션.
- 애플리케이션 추가하기 → 앱 이름·사업자명(회사명) 입력 → 저장.
- 만들어진 앱을 클릭해서 상세로 들어갑니다.
2단계 — 앱 키 확인 (REST API 키) ⭐
좌측 메뉴 앱 키 에서 키들이 보입니다. 우리가 쓸 건 딱 하나:
- REST API 키 → 이게
KAKAO_CLIENT_ID입니다.
💡 JavaScript 키·네이티브 키가 아니라 REST API 키 입니다. 서버에서 토큰을 교환하는 OAuth 방식은 REST API 키를 씁니다. (JavaScript 키는 카카오톡 공유 같은 프론트 SDK 용 — 별개)
3단계 — 카카오 로그인 활성화 & Redirect URI 등록 ⭐
- 좌측 카카오 로그인 메뉴 → 활성화 설정 을 ON.
- 같은 화면 아래 Redirect URI 에 앱의 콜백 주소를 등록합니다. 이 프로젝트의 콜백 경로는
/api/auth/kakao/callback입니다.
# 개발
http://localhost:10380/api/auth/kakao/callback
# 운영 (실제 도메인으로)
https://your-domain.com/api/auth/kakao/callback
⚠️ 가장 흔한 실수 — Redirect URI 는 완전히 똑같아야 합니다.
http/https, 포트 번호, 끝 슬래시(/) 유무까지 정확히 일치해야 하고, 다르면KOE006/redirect_uri mismatch에러가 납니다. 개발용·운영용 주소를 둘 다 등록해 두세요.
4단계 — 동의항목(Scope) 설정
좌측 카카오 로그인 → 동의항목 에서 사용자에게 받을 정보를 켭니다.
| 항목 | 설명 | 비고 |
|---|---|---|
닉네임 (profile_nickname) | 기본 프로필 이름 | 대부분 필수로 사용 |
프로필 사진 (profile_image) | 프로필 이미지 URL | 선택 |
카카오계정(이메일) (account_email) | 이메일 주소 | 비즈니스 앱 심사 필요 |
- 최소 구성은 닉네임 하나면 로그인 자체는 됩니다.
- 이메일은 개인정보라 카카오의 비즈니스 앱 전환 + 검수를 거쳐야 실제로 받을 수 있습니다. 처음엔 닉네임만으로 시작하는 걸 권장합니다.
💡 이 앱은
.env의KAKAO_SCOPES로 요청 스코프를 지정합니다. 비워두면 콘솔에 "필수 동의"로 등록된 항목을 카카오가 알아서 사용하므로, 콘솔 설정과 어긋날 걱정이 없습니다.
5단계 — (선택) Client Secret & 보안 설정
- 보안 → Client Secret: 발급해서 사용함으로 켜면 토큰 교환이 더 안전해집니다. 발급한 값을
KAKAO_CLIENT_SECRET에 넣으세요. (안 켜면 이 값은 비워도 됩니다.) - 플랫폼 → Web: 사이트 도메인(
http://localhost:10380, 운영 도메인)을 등록해 두면 좋습니다.
6단계 — .env 에 값 넣기 ⭐
지금까지 얻은 값을 프로젝트 루트 .env 에 채웁니다.
# 카카오 REST API 키
KAKAO_CLIENT_ID=여기에-REST-API-키
# Client Secret (콘솔에서 켰을 때만, 아니면 비워둠)
KAKAO_CLIENT_SECRET=
# 콘솔에 등록한 것과 100% 동일하게
KAKAO_REDIRECT_URI=http://localhost:10380/api/auth/kakao/callback
# 요청 스코프 — 비우면 콘솔의 필수동의 항목을 사용 (권장)
KAKAO_SCOPES=
⚠️
.env는 git 에 커밋 금지 (.gitignore확인). 운영 환경(Vercel 등)에서는 대시보드의 환경변수로 같은 값을 넣고,KAKAO_REDIRECT_URI는 운영 도메인 주소로 설정하세요.
앱을 재시작하면 로그인 페이지의 카카오 로그인 버튼이 실제로 동작합니다.
npm run dev
자주 막히는 포인트
| 증상 | 원인 / 해결 |
|---|---|
KOE006 / redirect_uri mismatch | 콘솔의 Redirect URI 와 .env 의 KAKAO_REDIRECT_URI 불일치 — http/https·포트·슬래시까지 맞추기 |
KOE101 invalid client | REST API 키를 잘못 넣음(JavaScript 키를 넣지 않았는지 확인), 또는 앱을 잘못 지정 |
| 로그인은 되는데 이메일이 안 옴 | 이메일은 비즈니스 앱 심사 후에만 수집 가능 |
| 동의 화면에 항목이 안 뜸 | 콘솔 동의항목에서 해당 스코프가 꺼져 있음 |
| 포트 바꿨더니 안 됨 | 포트 변경 시 KAKAO_REDIRECT_URI 와 콘솔 등록값을 함께 수정 |
마치며
정리하면 카카오 로그인 연결은 콘솔 설정 → 키를 .env 로 옮기는 작업입니다.
- 카카오 개발자 앱 생성 → REST API 키 확보
- 카카오 로그인 ON + Redirect URI 등록 (
/api/auth/kakao/callback) - 동의항목(최소 닉네임) 설정
-
.env에KAKAO_CLIENT_ID·KAKAO_REDIRECT_URI채우기 → 앱 재시작
인증 흐름은 이미 코드에 있으니, Redirect URI 만 정확히 맞추면 대부분 한 번에 붙습니다. 문제가 생기면 십중팔구 Redirect URI 불일치이니 그 부분을 먼저 확인하세요.
Comments
No comments yet. Be the first to comment!