페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • FAQ

카카오 로그인

FAQ

이 문서는 카카오 로그인에 대해 자주 묻는 질문과 답변을 제공합니다.

개념 이해

Q. 리다이렉트 URI는 무엇인가요?

리다이렉트 URI는 사용자가 카카오계정으로 로그인하고 동의를 완료한 후 이동하게 될 주소입니다. 이 주소로 카카오에게 권한을 위임했다는 증거인 인가 코드도 함께 전달됩니다. 이를 위해 리다이렉트 URI를 카카오디벨로퍼스에 미리 등록해야 합니다.

카카오 로그인 화면에서 [동의하고 계속하기]를 누르면, 카카오는 사전에 등록한 리다이렉트 URI로 사용자(브라우저)를 자동으로 이동시킵니다. 

http://localhost:4000/redirect?code=abc123xyz

예를 들어, 위 주소에서 http://localhost:4000/redirect는 카카오디벨로퍼스에 등록한 리다이렉트 URI이고, /redirect? 뒤에 오는 code 값인 abc123xyz가 카카오 인증 서버가 전달한 인가 코드입니다.

인가 코드는 로그인에 성공했다는 증거이며, 서버는 이 코드를 사용하여 카카오로부터 액세스 토큰을 발급받을 수 있습니다.

Q. 인가 코드와 액세스 토큰이 무엇인가요?

웹사이트나 앱에서 카카오 로그인을 하면 아래와 같은 일이 차례로 발생합니다.

  1. 사용자가 어떤 사이트에서 카카오 로그인을 선택합니다.
  2. 카카오가 제공하는 로그인 페이지가 나타나며, 사용자는 로그인 페이지에서 카카오 계정으로 로그인합니다.
  3. 카카오는 사용자가 입력한 ID와 비밀번호로 사용자임을 확인(Verification)합니다.
  4. 카카오가 해당 사용자는 인증된 사용자라는 것을 증명하는 인가 코드를 사이트(리다이렉트 URI)로 전달합니다. 인가 코드는 임시 출입증과 같은 역할을 하는 임시 코드입니다.
  5. 사이트는 카카오에게 받은 이 임시 코드를 다시 전달해 해당 사용자가 허락한 정보에 접근할 권한(액세스 토큰)을 달라고 요청합니다.
  6. 카카오는 이 요청을 확인하고, 액세스 토큰을 발급합니다. 액세스 토큰은 실제 정보를 접근하거나 기능을 사용할 수 있는 열쇠 역할을 합니다.
  7. 사이트는 이 액세스 토큰을 사용해서 카카오로부터 사용자의 프로필 사진, 이름, 이메일과 같은 정보에 접근하거나 메시지를 보낼 수 있습니다.

한마디로 인가 코드(Authorization Code)는 로그인할 때 나를 인증하고 권한을 받을 때 사용하는 '임시 출입증' 같은 역할을 하며, 액세스 토큰은 실제로 사용자의 정보에 접근하거나 기능을 사용할 수 있는 '열쇠' 역할을 합니다.

카카오는 곧바로 열쇠(액세스 토큰)를 주는 대신, 먼저 유효 기간이 짦은 임시 출입증(인가 코드)을 발급함으로써 인증 절차를 더 안전하게 유지합니다. 인가 코드는 액세스 토큰을 발급받기 위해 사용하는 일회성 코드로, 짧은 시간 동안만 유효합니다. 짧은 유효 시간 덕분에 보안상의 위험을 최소화할 수 있습니다.

자세한 사항은 인가와 토큰을 참고합니다.

Q. 사용자 동의는 왜 필요한가요?

카카오 API를 통해 사용자 정보를 가져오려면 반드시 사용자의 동의가 필요합니다. 이는 개인정보 보호와 보안을 위해 카카오가 사용자에게 먼저 허락을 구하는 과정입니다. 예를 들어, 쇼핑몰, 배달앱과 같은 서비스가 사용자의 이름이나 프로필 사진을 알고 싶어 한다고 해도, 사용자가 이를 허락하지 않으면 카카오는 해당 정보를 제공하지 않습니다.

이 과정을 통해 사용자는 자신이 어떤 정보를 서비스에 제공하는지 확인하고, 불필요한 정보를 제공한다고 여길 경우 이를 거절할 수 있습니다.

Q. 사용자 동의를 어떻게 받을 수 있나요?

서비스는 정보의 필요 여부에 따라 아래와 같이 구분해 사용자에게 동의를 요청할 수 있습니다.

  • 필수 동의항목: 사용자가 동의하지 않으면 서비스에 로그인할 수 없는 동의항목입니다.
  • 선택 동의항목: 사용자가 동의하지 않아도 로그인은 가능하지만, 해당 정보를 제공하지 않겠다고 선택할 수 있는 동의항목입니다.

동의화면은 카카오가 제공하므로 서비스는 별도로 UI를 구현하지 않아도 됩니다. 서비스가 설정한 동의항목에 따라 동의화면이 구성돼어 아래와 같이 사용자에게 보여집니다. 서비스는 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 동의항목을 설정해 사용자 동의를 요청할 수 있습니다. 자세한 방법은 활용하기와 설정하기를 참고합니다.

동의 화면

Q. 카카오 로그인을 사용하면 무엇이 좋을까요?

카카오 로그인을 사용하면 서비스 개발자와 사용자 모두에게 여러 가지 이점이 있습니다.

서비스(개발자)
  • 카카오가 인증 과정을 대신 처리하므로 로그인 시스템을 직접 구축할 필요가 없습니다.
  • 회원가입이 번거로워 서비스를 이탈하는 사용자에게 간편하게 가입하거나 로그인하는 기능을 제공합니다.
  • 사용자가 제공에 동의한 정보(예: 이름, 이메일 등)를 API를 통해 간편하게 받아올 수 있습니다.
  • 모바일, 웹 모두에서 동일한 방식으로 연동할 수 있어 개발 효율이 높습니다.
  • 카카오 API 플랫폼에서 제공하는 친구 목록, 메시지 전송과 같은 다양한 기능을 확장해 활용할 수 있습니다.
사용자
  • 별도로 회원가입하지 않아도 카카오 계정 하나로 간편하게 로그인할 수 있습니다.
  • 자주 사용하는 카카오 계정을 활용하므로 로그인 과정이 빠르고 편리합니다.
  • 개인 정보 제공에 대해 명확히 동의할 수 있어 안심하고 서비스를 이용할 수 있습니다.

Q. 세션이란?

웹사이트는 기본적으로 사용자가 누군지 기억하지 못합니다. 그래서 서비스는 로그인한 사용자의 정보를 일시적으로 기억하기 위해 세션 이라고 하는 웹브라우저의 임시 공간에 저장합니다. 세션은 열쇠를 보관하는 보관함의 역할로 필요할 때마다 열쇠를 꺼내 쓸 수 있도록 합니다.

이를 통해,

  • 사용자는 매번 로그인할 필요 없이, 로그인 상태를 유지할 수 있습니다.
  • 서비스는 사용자가 브라우저를 새로고침하거나, 다른 페이지로 이동해도 사용자 정보를 기억할 수 있습니다.

사용자가 서비스에서 로그아웃하면, 서비스 내부에 저장된 액세스 토큰(열쇠)과 세션(열쇠 보관함)은 삭제됩니다. 하지만 카카오 계정 자체의 로그인 세션은 그대로 유지되므로, 사용자가 다시 로그인 버튼을 누르면 카카오 로그인 페이지를 건너뛰고 바로 로그인될 수 있습니다.

로그아웃 시 카카오 계정의 세션까지 함께 만료하려면 카카오계정과 함께 로그아웃을 사용합니다. (참고: 로그아웃 방식별 차이점)

카카오 로그인 연동

Q. 한 번에 로그인된 모든 기기에서 로그아웃할 수 있나요?

현재 제공하지 않는 기능입니다. 카카오계정은 여러 기기에서 로그인하는 것(Multi device)을 지원합니다. 따라서 로그아웃 요청은 현재 사용 중인 기기에서만 로그인을 해제하고, 다른 기기의 로그인 상태는 유지됩니다.

Q. 로그아웃 후 다시 로그인하면 ID가 변경되나요?

아닙니다. 각 서비스 사용자에게 발급되는 회원번호(user id)는 고유한 값이며 로그아웃이나 탈퇴를 하더라도 변하지 않습니다.

단, 2018년 9월 19일 이전 생성 앱은 연결 해제 후 재연결 시 회원번호가 변경되도록 설정되어 있을 수 있습니다. 이 경우, 앱 관리 페이지의 [카카오 로그인] > [고급]에서 [사용자 아이디 고정]을 활성화하면 회원번호가 변경되지 않습니다.

Q. 카카오계정 사용자 정보가 바뀌었을 때 어떻게 처리하나요?

사용자마다 고유하게 발급되는 ID나 본인 인증 정보인 CI를 제외하면, 사용자 정보는 항상 변경될 가능성이 있습니다. 로그인 시 사용자 정보 조회를 요청해 최신 정보로 갱신합니다.

Q. 가입에 필수는 아니지만 서비스 이용 중 필요한 추가 정보를 따로 받을 수 있나요?

동의항목 추가 동의 요청 기능을 사용합니다. 사용자가 간편가입 시 선택 항목이어서 제공 동의하지 않은 항목이라도, 해당 정보를 필요로 하는 기능을 사용자가 쓰려고 한다면 다시 정보 제공에 동의할 것인지 물어볼 수 있습니다. 하지만 추가 정보 동의 요청에도 사용자가 거부한다면 해당 기능을 제공하지 않아야 합니다.

Q. 카카오 로그인과 카카오싱크가 제공하는 사용자 정보 종류를 알려주세요.

카카오가 제공하는 사용자 정보의 종류는 사용자 정보에서 확인할 수 있습니다. 아래는 사용자 정보 제공 조건입니다.

  1. 각 사용자 정보 제공을 위한 동의항목을 설정해야 합니다.
  2. 설정된 동의항목에 대해 사용자가 인가해야 합니다.

Q. 사용자가 어떤 사용자 정보를 제공하기로 동의했는지 확인할 수 있나요?

네. 앱에서 어떤 동의항목을 설정했고, 사용자가 어떤 동의항목에 동의했는지 동의항목 동의 내역 조회 API로 확인할 수 있습니다.

혹은 사용자 정보 조회 API의 응답으로도 확인할 수 있습니다. 사용자가 동의한 정보와 함께 사용자 동의 시 정보 제공 가능 여부로 추가적인 동의가 필요한 항목을 확인할 수 있습니다.

Q. 전화번호는 수집 후 제공 옵션을 사용할 수 없나요?

카카오계정(전화번호) 동의항목은 수집 후 제공 설정을 사용할 수 없습니다. 전화번호는 카카오계정에 연결된 카카오톡에서 가져오며, 카카오톡을 사용하지 않는 카카오계정인 경우에는 전화번호를 확보할 수 없기 때문입니다. 만약 전화번호가 필수 동의항목으로 설정돼 있음에도 값이 비어 있는 사용자가 있다면, 해당 사용자는 카카오톡을 사용하지 않아 카카오에서 전화번호를 제공할 수 없는 경우입니다. 이 때는 자체적으로 전화번호를 수집 및 저장해야 합니다.

문제 해결

Q. KO101 에러가 발생해요.

API 호출 시 잘못된 앱 키를 사용한 경우 발생하는 에러입니다.

앱 관리 페이지의 [앱] > [일반] > [앱 키]에서 확인한 정확한 앱 키를 사용했는지, 사용하는 플랫폼에 맞는 앱 키를 사용했는지 확인합니다.

플랫폼별로 사용해야 하는 앱 키는 다음과 같습니다.

  • Android, iOS SDK 초기화 시: 네이티브 앱 키 사용
  • JavaScript SDK 초기화 시: JavaScript 키 사용
  • REST API 호출 시: REST API 키 사용

이 밖에 API 호출 시 발생하는 에러는 에러 코드를 참고합니다.

Q. KOE006 에러가 발생해요.

등록하지 않은 리다이렉트 URI를 사용해 인가 코드를 요청할 때 발생하는 에러입니다.

앱 관리 페이지의 [카카오 로그인]에서 리다이렉트 URI를 새로 등록합니다. 또는 등록된 리다이렉트 URI를 인가 코드 요청 시 redirect_uri 파라미터 값으로 사용합니다.

등록 방법은 리다이렉트 URI 등록을 참고합니다. 이 밖에 API 호출 시 발생하는 에러는 에러 코드를 참고합니다.

Q. "API limit has been exceeded." 에러가 발생합니다.

카카오 오픈 API는 매달 정해진 사용량만큼 무료로 제공됩니다. 사용량 제한(쿼터)을 넘어서면 에러가 발생하고 더 이상 해당 API를 사용할 수 없습니다. API마다 정해진 사용량 제한을 확인하려면 쿼터를 참고합니다.

만약 사용량 제한을 늘리고 싶다면 데브톡에 대상 앱과 이유를 담아 협의 또는 제휴를 요청합니다. 카카오맵 API에 대한 쿼터 상향이 필요한 경우에는 공지을 우선 확인합니다. 카카오는 요청 내용을 검토하고 제휴를 체결하거나 임시로 사용량 제한 범위를 조절할 수 있습니다.

Q. 동의 화면에 특정 필수 동의항목이 노출되지 않습니다.

특정 동의항목을 [필수 동의]로 설정했더라도, 사용자에게 정보가 없다면 동의 화면에 해당 동의항목이 노출되지 않습니다.

이 경우, 해당 동의항목에 카카오계정으로 수집 후 제공 옵션을 설정합니다. '수집 후 제공' 옵션은 카카오 로그인 시 사용자가 해당 동의항목의 정보를 갖고 있지 않다면, 사용자로부터 정보를 입력 받아 동의 화면에서 동의 받을 수 있도록 해 줍니다. 단, 전화번호는 '수집 후 제공' 옵션을 사용할 수 없으므로 유의합니다.

'수집 후 제공' 옵션에 따라 사용자의 정보 입력이 필요할 경우, 사용자는 추가정보 입력 단계를 거쳐 카카오 로그인 동의 화면으로 이동합니다. 아래는 추가정보 입력 단계에서 나타나는 화면의 예시입니다.

수집 후 제공 화면

Q. 카카오 로그인 시 카카오톡이 실행되지 않고 카카오계정 정보 입력 화면이 나타납니다.

로그인 버튼을 눌렀을 때 카카오톡으로 이동하며 간편로그인을 할 수 있어야 하는데, 카카오계정 정보 입력 화면이 나타난다면 인증 유형(Auth Type) 설정을 했는지 확인합니다.

카카오 로그인은 인증 유형에 따라 다르게 동작합니다. 아래와 같은 인증 유형이 있습니다.

  • 현재 사용할 수 있는 모든 인증 수단
  • 카카오계정 및 비밀번호
  • 카카오톡 사용자 정보

REST API를 사용할 때는 카카오계정 및 비밀번호로만 사용자 인증이 가능합니다. JavaScript SDK를 사용하면 아래와 같은 옵션이 제공됩니다.

플랫폼 파라미터 설명
JavaScript throughTalk 카카오톡 간편로그인 사용 여부, Boolean

위 옵션은 서비스 상황에 따라 인증 유형을 지정할 수 있도록 제공됩니다. SDK에서는 옵션마다 인증 수단 실행 경로가 상수로 지정돼 있으므로, 별도 지정이 필요하지 않습니다.

Q. 카카오톡으로 로그인한 뒤 서비스 페이지나 앱으로 돌아오지 않습니다.

모바일 웹에서 카카오톡 로그인 시 해당 현상이 발생한다면 정상 동작입니다. 스마트폰 OS 정책에 따라 앱에서 임의로 다른 앱을 불러올 수 없습니다. 사용자가 직접 서비스 웹 페이지(브라우저)로 돌아가야만 합니다. 카카오톡 로그인 화면에서도 안내 문구를 보여줍니다. 서비스 페이지로 이동했을 때 로그인이 완료된다면 기능이 정상 동작하는 것입니다.

Q. 회원 가입 후 다시 로그인했을 때 정상적으로 로그인 완료되지 않습니다.

웹 브라우저의 경우, 로그인한 사용자의 정보가 회원 정보에 잘 저장되어 있고 로그인 시 올바르게 불러와지는지 확인합니다. 로그인 후 사용자 정보를 호출해 회원번호(user id)를 받은 뒤, 이 정보로 서비스 회원 정보에서 해당 사용자의 정보를 불러오는 부분에 이상이 없어야 합니다.

네이티브 앱의 경우, 카카오 로그인 인증 정보는 토큰으로 관리됩니다. 토큰은 실제 인증을 담당하는 액세스 토큰, 액세스 토큰 만료 시 간편하게 재발급 받을 수 있도록 해 주는 리프레시 토큰 두 가지가 있습니다. 사용자가 로그아웃을 하지 않았다면, 일정 기간 내 다시 로그인했을 때는 액세스 토큰 또는 리프레시 토큰을 사용해 로그인할 수 있습니다. 토큰 유효 기간 동안은 다시 카카오톡이나 카카오계정으로 사용자 정보를 인증할 필요가 없습니다.

  • 사용자가 로그아웃하지 않았음
  • 토큰 유효 기간 이내임

위 두 가지 조건을 만족함에도 토큰을 사용한 재로그인이 불가능하다면, 아래와 같이 확인합니다.

  • 토큰 유효성을 검사합니다. 토큰이 유효하다면 아래 단계로, 토큰이 유효하지 않다면 폐기 후 사용자가 다시 로그인하도록 처리합니다.
  • 토큰이 유효하지만 정상적으로 로그인되지 않는다면 서비스에서의 로그인 절차를 확인합니다. 회원 가입 처리나 정보 갱신이 올바르게 이뤄지지 않았을 수 있습니다.
  • 이 외, 인증 과정에 에러가 발생해 로그인에 실패하는 경우가 있습니다. 에러 메시지를 참고해 원인을 파악합니다.

Q. 로그아웃이 올바르게 완료되지 않습니다.

REST API라면 로그아웃 요청에 사용된 토큰 정보가 올바른지 확인합니다. Kakao SDK 사용 시에는 로그아웃 요청과 함께 토큰과 쿠키가 폐기되기 때문에 함수 호출 결과와 무관하게 실질적인 로그아웃이 이뤄지므로, API 동작 외의 다른 부분에 실패 원인이 있을 가능성이 높습니다.

Q. 로그아웃 후 다시 로그인할 때 이전에 로그인한 계정으로 로그인됩니다.

로그아웃 처리가 올바르게 완료되지 않았거나, 브라우저에 저장된 쿠키 때문에 발생하는 현상입니다. iOS나 Android SDK 사용 시 정상적으로 로그아웃한 경우 토큰과 쿠키가 모두 지워지고, REST API 사용 시에는 액세스 토큰과 리프레시 토큰이 폐기됩니다. 현재 카카오계정 쿠키는 폐기되지 않으므로 다시 인증을 시도하면 같은 계정으로 로그인될 수 있습니다.

Q. 사용자 정보 조회 API로 필요한 사용자 정보를 제공받지 못했습니다.

원인
  • 동의항목 미설정 또는 동의 미획득
    • 앱의 동의항목 설정에서 해당 정보(예: 이메일, 배송지 등)를 [필수 동의] 또는 [선택 동의]로 지정하지 않은 경우, 해당 정보는 제공되지 않습니다.
    • 사용자가 로그인 시 동의 화면에서 해당 항목에 동의하지 않은 경우에도 값이 비어 있을 수 있습니다.
  • 카카오에 정보가 없는 경우
    • 사용자가 카카오 서비스 이용 중 해당 정보를 한 번도 입력하지 않은 경우, 동의 여부와 관계없이 값이 비어 있을 수 있습니다. 예를 들어, 이메일 동의항목을 [필수 동의]로 설정했더라도, 사용자가 카카오계정에 이메일을 등록하지 않았다면 이메일 값이 제공되지 않습니다.
  • 카카오계정으로 정보 수집 후 제공 옵션 미활성화
  • 사용자 거부
    • 사용자가 정보 제공을 거부한 항목은 카카오에서도 보유하지 않으므로, 해당 값은 빈 값으로 반환됩니다.
해결 방안

사용자 정보 조회 API로 필요한 사용자 정보를 제공받지 못했다면 아래 내용을 확인합니다.

  1. 제공받지 못한 사용자 정보에 대응하는 동의항목을 설정했는지 확인
    • 앱에 해당 사용자 정보의 동의항목을 [필수 동의] 또는 [선택 동의]로 설정해야 사용자 정보 제공 가능
    • 서비스에 반드시 필요한 정보는 [필수 동의] 동의항목으로 설정하고 카카오계정으로 수집 후 제공 옵션 사용
  2. 사용자 정보 조회 API 응답의 사용자 동의 시 정보 제공 가능 여부 값 확인
    • xxx_needs_agreement 값이 true이면 동의항목 추가 동의 요청으로 사용자 동의를 받은 후, 사용자 정보 조회 API를 다시 요청해 제공받을 수 있음

Q. 배송지 조회 응답에 배송지 정보가 없어요.

REST API 또는 JavaScript SDK를 사용해 배송지 조회 API 또는 사용자 정보 조회 API 호출 시, 성공 응답에 배송지 상세 정보인 shipping_addresses 필드가 포함되지 않은 경우가 발생할 수 있습니다.

{
  "user_id": 12345,
  "shipping_addresses_needs_agreement": true
}
원인
  • 배송지 정보를 제공받으려면 사용자의 동의가 필요하나, 사용자가 [배송지 정보] 동의항목에 동의하지 않은 경우
  • 사용자가 배송지 제공에 동의했으나 배송지 정보가 없는 경우
  • 선택한 배송지 ID가 유효하지 않은 경우
해결 방법

shipping_addresses_needs_agreement 필드의 값을 확인해 아래와 같이 조치합니다.

  • true: 사용자가 [배송지 정보] 동의항목에 동의하지 않은 경우, 사용자 동의 시 정보 제공 가능 여부와 동의항목 추가 동의 요청으로 사용자 동의 획득 후 재요청
  • false: 배송지 상세 정보를 제공받을 수 없는 경우
    • 배송지 ID가 유효하지 않은 경우: 배송지 선택 API로 올바른 배송지 ID 획득 후 재요청
    • 사용자가 배송지 제공에 동의했으나 배송지 정보가 없어 제공 불가, 서비스에서 직접 배송지를 입력받아야 함
카카오 로그인> FAQ