소셜 로그인 직접 설정하기 ② 카카오
바이브코딩으로 만든 BackendX 앱에 카카오 로그인을 직접 연결하는 방법. 카카오 디벨로퍼스 앱 등록, REST API 키·클라이언트 시크릿, KOE006 오류까지 화면과 함께 정리했어요.
바이브코딩으로 BackendX에서 앱을 만들고 있다면, 로그인은 기본으로 들어가는 BackendX 로그인으로 충분한 경우가 많아요. 그래도 소셜 로그인을 내 앱에 직접 연결해야 하는 바이브코더를 위해, 그 방법을 제공자별로 정리하는 「소셜 로그인 직접 설정하기」 시리즈예요. 이번 편에서는 카카오에 내 앱을 등록하고, 그 값을 BackendX 앱에 넣는 방법을 화면과 함께 따라가 볼게요.
🤔 먼저, 이 설정이 정말 필요한가요?
BackendX로 만든 앱의 로그인은 기본으로 BackendX 로그인(Sign in with BackendX)을 써요. 따로 고르지 않아도 기본으로 들어가고, 제공자 콘솔에 들어갈 필요도, 키를 관리할 필요도 없어요. 대부분의 앱은 이 글의 설정이 필요 없어요.
아래 두 경우에만 카카오에 내 앱을 직접 등록하면 돼요.
- 백엔드엑스 채팅창에서 카카오 로그인을 BackendX 로그인을 거치지 않고 직접 연결해 달라고 요청한 경우
- BackendX 로그인에서 제공하지 않는 로그인 방식이 필요해서 카카오로 직접 연결하기로 한 경우
어느 쪽인지 헷갈린다면, 앱의 API 문서나 BackendX가 알려 주는 환경 변수 목록을 확인해 보세요. KAKAO_APP_ID 같은 값을 넣으라는 안내가 있다면 이 글이 필요한 경우예요.
📝 시작하기 전에: 내 앱의 "주소"를 정해 두세요
제공자 콘솔에는 로그인이 일어나는 웹 주소를 등록해야 해요. 주소는 앱을 어디서 실행하느냐에 따라 달라요. 가장 간편한 방법은 백엔드엑스를 통해서 배포하는 거예요.
- 백엔드엑스를 통해서 배포할 때 (BackendX 관리형 클라우드):
https://<프로젝트 ID>.app.pool1.backendx.cloud
<프로젝트 ID>는 BackendX 대시보드에서 프로젝트를 열었을 때 주소창에 보이는 긴 ID(예:4e51bf17-cc28-…, 36자리)예요. 이 주소는 프로젝트를 다시 배포해도 바뀌지 않아요. - 내 컴퓨터에서 실행할 때 (내려받은
docker-compose.yaml로docker compose up):http://localhost:8080
8080 포트를 이미 다른 프로그램이 쓰고 있다면,docker-compose.yaml옆에.env파일을 만들고BX_FRONTEND_PORT=5175처럼 다른 포트를 적으면 돼요. 그때는 주소도http://localhost:5175가 돼요.
⚠️ 이때 주소는 꼭http://localhost:포트를 쓰세요. docker compose가 함께 띄우는http://frontend.localhost주소는 제공자가 받아 주지 않을 수 있어요. - 내 서버에 직접 배포할 때: 내 도메인 주소 (예:
https://myapp.example.com)
내 컴퓨터에서도 시험하고 배포도 할 거라면, 두 주소를 모두 등록해 두면 편해요. 배포한 앱 주소는 꼭 https://로 등록하고, IP 주소나 http:// 주소는 쓰지 마세요.
카카오 디벨로퍼스에서 설정하기
카카오 디벨로퍼스에 로그인한 뒤 상단의 앱으로 들어가요.
① 앱 만들기
+ 앱 생성을 누르고 앱 이름, 회사명, 카테고리를 채워 저장해요. 앱 이름은 카카오 동의 화면에 그대로 보여요.

② 카카오 로그인 켜기
왼쪽 메뉴 제품 설정 → 카카오 로그인 → 일반에서 사용 설정을 ON으로 바꿔요. 화면 맨 위의 ID 숫자가 앱 ID예요. BackendX에 넣을 KAKAO_APP_ID예요.

③ 동의항목: 아무것도 켜지 않아도 돼요
카카오 로그인 → 동의항목에서는 사용자에게 어떤 정보를 받을지 고를 수 있어요. 그런데 BackendX의 카카오 로그인은 동의항목을 하나도 켜지 않아도 동작해요. 로그인에는 카카오가 항상 주는 회원번호만 쓰기 때문이에요.
- 닉네임·프로필 사진은 켜지 않아도 돼요. 이름 같은 정보는 앱의 프로필 화면에서 직접 받아요.
- 카카오계정(이메일)은 카카오의 비즈니스 인증을 마친 앱만 켤 수 있어요. 이메일을 켜지 않으면 로그인은 되지만 그 사용자에게는 앱에 저장된 이메일이 없어요. 이메일로 안내를 보내야 하는 서비스라면 비즈니스 인증 후에 켜 주세요.

④ REST API 키와 리다이렉트 URI
왼쪽 메뉴 앱 → 플랫폼 키로 가면 REST API 키가 보여요. 이 값이 KAKAO_REST_API_KEY예요.

REST API 키 카드를 눌러 REST API 키 수정 화면으로 들어간 다음, 카카오 로그인 리다이렉트 URI에 앱 주소 + /login을 추가하고 저장해요.
- 백엔드엑스를 통해서 배포한 앱:
https://<프로젝트 ID>.app.pool1.backendx.cloud/login - 내 컴퓨터:
http://localhost:8080/login(포트를 바꿨다면 그 포트로) - 내 서버에 직접 배포한 앱:
https://myapp.example.com/login

⑤ 클라이언트 시크릿
같은 화면을 조금 내리면 클라이언트 시크릿이 있어요. 새로 만든 REST API 키는 클라이언트 시크릿이 처음부터 켜져(ON) 있어요. 끄지 말고 그대로 두세요. 카카오 로그인 줄의 코드가 KAKAO_CLIENT_SECRET이에요.

BackendX 앱에 값 넣기
복사한 값 세 개를 이름 그대로 넣으면 돼요.
| 환경 변수 | 어디서 복사하나요 |
|---|---|
KAKAO_APP_ID | 카카오 로그인 → 일반 (맨 위 ID 숫자) |
KAKAO_REST_API_KEY | 앱 → 플랫폼 키 → REST API 키 |
KAKAO_CLIENT_SECRET | REST API 키 수정 → 클라이언트 시크릿 (카카오 로그인 줄의 코드) |
- 백엔드엑스를 통해서 배포할 때: 배포 단계에서 BackendX가 필요한 값을 물어봐요. 같은 이름의 칸에 넣으면 돼요. 값이 비어 있으면 배포 전에 알려 줘요.
- 내 컴퓨터에서 실행할 때: 프로젝트에서 내려받은 압축 파일의
env.txt에서 해당 줄을 찾아=뒤에 값을 붙여 넣고docker compose up -d를 실행해요. - 내 서버에 직접 배포할 때: 서버의
env.txt(또는 환경 변수)에 같은 이름으로 넣어 주세요.
앱을 열면 로그인 화면에 카카오로 계속하기 버튼이 생겨요. 앱에 닉네임 같은 프로필 항목이 있다면, 처음 로그인한 사용자는 프로필 입력 화면으로 이어져요.


🔒 키는 이렇게 다뤄 주세요
- 앱 ID와 REST API 키는 로그인할 때 브라우저 주소창에도 보이는 값이라 비밀은 아니에요.
- 클라이언트 시크릿은 서버만 쓰는 비밀값이에요. 화면 코드나 GitHub 저장소, 채팅방에 붙여 넣지 마세요. 혹시 노출됐다면 콘솔에서 코드 재발급을 누르고 새 값으로 바꿔 주세요.
- REST API 키로는 지도·검색 같은 다른 카카오 API도 부를 수 있어요. 로그인용 앱과 다른 API용 앱을 나눠 두면 더 안전해요.
🧯 이런 화면이 나오면
"앱 관리자 설정 오류 (KOE006)"
리다이렉트 URI가 등록되지 않았다는 뜻이에요. 앱 → 플랫폼 키 → REST API 키 수정 → 카카오 로그인 리다이렉트 URI에 앱 주소/login이 정확히 들어 있는지 확인해 주세요. (로그아웃 리다이렉트 URI 칸이 아니에요!) 카카오에 아직 로그인하지 않은 브라우저에서는 카카오 로그인 화면이 먼저 나와서, 이 오류가 로그인한 다음에야 보이기도 해요.

카카오에서 돌아왔는데 "로그인에 실패했습니다"
대부분 서버에 넣은 값 문제예요. KAKAO_CLIENT_SECRET이 콘솔의 카카오 로그인 줄 코드와 같은지 (비즈니스 인증 줄 코드가 아니에요), KAKAO_APP_ID가 같은 앱의 ID인지 확인해 주세요. 값을 고쳤다면 docker compose up -d로 다시 시작해요.
📚 「소셜 로그인 직접 설정하기」 시리즈
- ① Google
- ② 카카오 (이 글)
- ③ 네이버
- ④ Facebook
- ⑤ Apple (준비 중이에요)
설정이 번거롭게 느껴진다면, 키 관리 없이 바로 쓸 수 있는 BackendX 로그인도 언제든 선택할 수 있어요 🙂