페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • 이해하기

카카오 로그인

이해하기

이 문서는 카카오 로그인 및 관련 기능을 소개합니다.

기능 소개

카카오 로그인은 카카오계정과 애플리케이션(이하 앱)을 연결하고 토큰을 발급받아 카카오 API를 사용할 수 있도록 하는 기능입니다. 토큰은 사용자를 인증하고 카카오 API 호출 권한을 부여하는 액세스 토큰(Access Token)와 액세스 토큰을 갱신하는 데 쓰는 리프레시 토큰(Refresh Token)이 있습니다.

로그아웃은 로그인을 통해 발급받은 토큰을 만료시켜 사용자가 서비스에서 로그아웃 요청했을 때나 서버에서 특정 사용자를 로그아웃하도록 요청할 때, 해당 사용자를 로그아웃시킬 수 있습니다.

한편, 연결 끊기는 연결과 대조되는 개념으로써 카카오계정과 앱의 연결을 끊는 기능입니다. 연결 끊기를 하면 앱에서 더 이상 해당 사용자 정보로 API를 호출할 수 없고, 카카오 플랫폼에서도 해당 앱에 대한 해당 사용자의 데이터가 모두 지워집니다.

로그아웃 또는 연결 끊기 후에도 다시 앱에 로그인 및 연결할 수 있습니다. 하지만 사용자가 연결을 끊었던 앱에 같은 카카오계정으로 다시 로그인 및 연결하더라도 기존 이용 정보는 남아 있지 않으며 복구도 불가능합니다.

Name Description Kakao API
로그인 카카오계정 정보로 사용자를 인증하고 API 호출 권한을 얻습니다. O
연결 카카오계정과 앱을 연결, 사용자가 해당 앱에서 카카오 API를 사용할 수 있게 합니다. O
가입 카카오계정 정보로 로그인한 사용자를 서비스 데이터베이스(DB)에 회원으로 등록합니다. X
서비스 자체 구현
로그아웃 로그아웃 요청한 사용자의 토큰을 만료시킵니다. O
연결 끊기 카카오계정과 서비스 사이의 연결을 해제합니다. O
탈퇴 회원 정보를 삭제하고 서비스를 더 이상 이용하지 않습니다. X
서비스 자체 구현
토큰 API 호출 권한을 증명하며, 로그인을 통해 발급받습니다. O

위 표에서 카카오 API가 제공되는 것으로 표시된 기능은 서비스에서 카카오 API를 사용해 보다 편리하게 구현할 수 있습니다. 예를 들어 카카오 로그인을 사용하면 직접 서비스 ID 및 비밀번호를 입력받고 검증하는 과정을 구현하는 대신, 카카오 로그인을 통해 사용자를 인증하고 회원 정보를 수집할 수 있습니다.

반면, 카카오 API가 제공되지 않는 가입 및 탈퇴 등 회원 정보에 대한 처리는 서비스에서 자체적으로 구현해야만 합니다. 카카오는 서비스 데이터에 접근하지 않기 때문에, 회원 정보를 대신 저장하거나 삭제할 수 없기 때문입니다.

로그인

카카오 로그인은 Kakao SDK for Android, iOS, JavaScript와 REST API로 제공되며 OAuth 2.0 기반입니다.

OAuth2.0

OAuth 2.0은 공개 API(Open API)로 제공되는 표준 인증 방법입니다.

카카오 로그인은 앱 정책이나 UI/UX 등에 따라 다양한 사용자 동선을 고려하여 편리하게 사용할 수 있도록 설계되었습니다. 사용자는 웹 브라우저(Web Browser)에서 서비스 홈페이지에 들어가 로그인하거나, 특정 서비스 게시판에 의견을 남기기 위해 로그인하기도 합니다. 카카오톡 채팅방에서 상품 정보 메시지를 보고 연 웹뷰(Web View)에서 로그인할 때도 있습니다.

카카오 로그인이 진행되는 과정을 간략히 표현하면 다음과 같습니다.

  • 사용자가 앱에서 카카오 로그인 버튼을 클릭합니다.
  • 사용자가 [카카오톡으로 로그인]을 선택하면 카카오톡 실행 또는 실행 중인 카카오톡으로 연결되고, [다른 카카오계정으로 로그인]을 선택하면 직접 계정 정보를 입력하는 화면이 출력됩니다. 카카오톡이 설치되어 있지 않은 기기나 PC 웹 환경에서는 직접 계정 정보를 입력하여 카카오계정으로 로그인하게끔 진행됩니다.
  • '카카오톡으로 간편로그인'한 경우, 카카오톡에 연결된 카카오계정의 자격정보(Credentials)를 통해 사용자를 인식합니다. 직접 카카오계정을 입력해 로그인한 경우에는 해당 계정의 자격정보로 인식합니다.
  • 자격정보가 올바르다면 카카오 로그인 동의 화면을 통해 사용자로부터 사용자 정보 및 기능 활용 동의를 받습니다.
  • 사용자가 필수 항목에 동의하고 로그인을 요청하면 인가 코드(Authorization Code)가 발급됩니다. 이 코드는 앱 정보의 Redirect URI에 전달됩니다.
  • 앱은 전달 받은 인가 코드를 기반으로 토큰을 요청하고 받습니다.
카카오 인증 서버와 카카오 API 서버

위의 로그인 진행 순서를 표현한 이미지에는 카카오 서버가 하나로 표현되어 있지만, 카카오 서버의 호스트는 인증 서버(kauth.kakao.com)와 API 서버들로 나뉩니다. 카카오 로그인은 인증 서버가, 사용자 정보 가져오기 등 다른 기능은 API 서버들이 각각 요청을 받고 작업을 수행합니다.

카카오 로그인은 카카오계정의 사용자 자격정보로 인가 코드를 받아오고, 인가 코드로 액세스 토큰과 리프레시 토큰을 얻는 과정으로 구성돼 있습니다. 액세스 토큰은 사용자를 인증하고 카카오 API 호출 권한을 부여합니다. 리프레시 토큰(Refresh Token)은 사용자가 매번 카카오계정 정보를 입력하거나 카카오톡으로 로그인하지 않고도 액세스 토큰을 발급받을 수 있게 합니다.

만약 서비스 앱이나 서버 에러가 아닌 요청 정보 문제로 로그인에 실패한다면 카카오 서버는 실패 원인을 응답으로 전달합니다. 이 때는 응답 코드를 참고해 원인을 찾아 수정할 수 있습니다.

로그인을 통해 앱과 사용자가 연결되고 토큰도 발급받았다면 사용자 정보 가져오기를 통해 현재 로그인한 사용자의 정보를 확인하여 서비스에 활용할 수 있습니다.

토큰 정보

토큰은 매번 인증을 거치지 않고도 일정 기간 카카오 API를 사용할 수 있도록 하는 권한 증명입니다. Kakao SDK는 토큰 관리 기능을 갖고 있습니다. REST API 사용 시에는 필요에 따라 토큰 정보 확인이나 갱신을 위한 요청을 해야 합니다.

토큰은 두 가지입니다. 보안상의 이유로 권한 증명 역할을 하는 액세스 토큰(Access Token)은 비교적 짧은 유효기간을 가지며, 일정 기간 동안 인증을 거치지 않고 액세스 토큰을 갱신할 수 있게 해주는 역할을 하는 리프레시 토큰(Refresh Token)은 보다 긴 유효기간을 가집니다.

토큰 유효기간은 플랫폼마다 다릅니다. 토큰의 역할과 유효기간을 표로 정리하면 다음과 같습니다.

Token Type Role Valid
Access Token 사용자를 인증합니다. Android, iOS : 12시간
JavaScript: 2 시간
REST API : 6시간
Refresh Token 일정 기간 동안 다시 인증 절차를 거치지 않고도 액세스 토큰 발급을 받을 수 있게 해 줍니다. 2달
유효기간 1달 남은 시점부터 갱신 가능

사용자 환경에 따른 인증 방법

카카오 로그인은 구현 방식과 사용자 환경에 따라 다르게 동작합니다. 차이점은 다음 표를 참고합니다.

구현 방법 환경 설명
Android SDK Android 스마트폰 카카오톡에 연결된 카카오계정 정보 이용
카카오톡 미설치 시, 카카오계정 정보 입력 웹 페이지 이용
iOS SDK iOS 스마트폰 카카오톡에 연결된 카카오계정 정보 이용
카카오톡 미설치 시, 카카오계정 정보 입력 웹 페이지 이용
JavaScript SDK PC 또는 모바일 웹 브라우저(Web Browser) 스마트폰 기기: 카카오톡에 연결된 카카오계정 정보 이용
PC 또는 Mac 기기: 카카오계정 정보 입력 웹 페이지 이용
REST API PC 또는 모바일 웹 브라우저(Web Browser) 스마트폰 기기: 카카오계정 정보 입력 웹 페이지 이용, 해당 웹 페이지에서 사용자가 '카카오톡으로 로그인' 선택 시 카카오톡에 연결된 카카오계정 정보 이용*
PC 또는 Mac 기기: 카카오계정 정보 입력 웹 페이지 이용

* 주요 웹 브라우저(Chrome, Safari 등)를 통한 로그인 요청에만 '카카오톡으로 로그인' 지원 가능

* 모바일 앱에서 REST API 방식으로 로그인을 요청한 경우 미지원

사용자 동의

카카오 로그인 후, 서비스는 카카오 API를 통해 사용자 정보 및 서비스 접근권한을 요청할 수 있습니다. 모든 사용자 정보와 서비스 접근권한은 사용자 동의가 있어야만 제공됩니다. 카카오계정에 저장되어 있는 정보라도 사용자가 앱에 제공하는 데 동의하지 않았다면 사용자 정보 가져오기를 통해 받을 수 없습니다.

[내 애플리케이션] > [카카오 로그인] > [동의 항목]에서 카카오 로그인 시 제 3자 정보제공 동의를 받을 항목들을 설정할 수 있습니다.

서비스 이용에 필수적인 동의 항목은 사용자가 처음으로 카카오 로그인 하는 시점에 제공 동의하도록 처리할 수 있으나, 카카오 API를 사용해 특정 정보가 필요한 시점에 동의를 요청할 수도 있습니다. 일부 동의 항목은 서비스에 회원 가입할 때에 필요하지 않지만, 일부 기능을 이용할 때 필요해질 수 있습니다. 사용자 정보를 과도하게 수집하지 않도록 해당 기능을 이용하려는 시점에 추가로 제공 동의받도록 하는 것이 좋습니다.

사용자 동의는 카카오 로그인 시 사용자가 직접 동의하여야 하지만, 동의 철회는 서비스에서도 동의 철회하기 API를 사용해 처리할 수 있습니다. 또한 사용자가 동의 철회 시에도 동의 철회하기 API가 호출됩니다. 사용자는 카카오계정 웹사이트의 [계정 이용]이나 카카오톡의 [설정] > [개인/보안] > [연결된 서비스 관리] 메뉴를 통해 선택 동의 항목에 대한 동의를 철회할 수 있습니다.

needs_agreement

needs_agreement사용자 정보 종류별로 포함되어 있는 키입니다. 각 서비스에서 사용하도록 설정한 동의 항목에 한해 제공되며, 사용자 동의 필요 여부를 의미합니다. 특정 사용자 정보에 대해, 서비스에서 카카오 로그인 또는 추가 항목 동의 받기를 통해 사용자로부터 제3자 제공 동의를 받으면 해당 정보를 받을 수 있는지 알려줍니다.

needs_agreement 값은 이미 제공되고 있는 사용자 정보의 경우 "false", 추가 제공이 가능한 사용자 정보의 경우 "true"입니다. 이 값이 "true"인 사용자 정보는 추가 항목 동의 받기로 사용자 동의를 거쳐 값을 제공 받을 수 있습니다.

needs_agreement 값이 "false"지만 사용자 정보의 값이 없다면, 해당 사용자 정보는 자체 수집하거나 관련 기능을 제공하지 않아야 합니다. 사용자가 해당 정보를 제공하지 않은 경우라면 카카오계정에서 수집 후 제공 기능을 사용해 값을 제공 받을 수 있습니다. 사용자가 카카오계정 정보 수집에 동의하지 않은 경우에는 값을 제공할 수 없으므로, 해당 사용자 정보가 없는 경우를 서비스에 고려해야 합니다.

이 외, needs_agreement 값에 영향을 주는 상태 조건은 다음 표를 참고합니다:

카카오계정의 사용자 정보 값, 수집 후 제공 기능 사용 여부에 따른 neeeds_agreement 값
상태 사용자 정보 값 보유 사용자 정보 값 미보유
"카카오계정에서 수집 후 제공" 기능 사용 true true
"카카오계정에서 수집 후 제공" 기능 미사용 true false

사용자 정보

카카오 로그인 후 사용자 정보 가져오기를 비롯한 카카오 API를 통해 사용자 정보를 제공받을 수 있습니다. 또한 사용자 정보를 제공 받으려면 해당 사용자가 카카오 로그인 시 동의 항목을 통해 앱에 정보를 제공하는 데 동의해야 합니다.

카카오 API를 통해 제공되는 사용자 정보의 종류는 다음의 각 항목을 참고합니다:

주의

카카오 API 응답은 새로운 항목이 추가되거나 기존 항목이 제외(Deprecated)될 수 있습니다. 새로운 응답이 추가되더라도 에러가 발생하지 않도록 응답 구문 분석(JSON parsing) 시 예외처리에 유의해야 합니다. 응답 구성이 변경되거나 삭제될 경우, 데브톡을 통해 공지되므로 미리 대비하여야 합니다.

사용자 정보 가져오기 API로 받는 사용자 정보

사용자 정보 가져오기 API를 통해 사용자의 정보를 제공합니다. 제공 받은 사용자 정보를 카카오 로그인 또는 카카오싱크 간편가입 시 서비스의 회원 정보로 활용할 수 있습니다. 카카오에서 취급하지 않는 정보(여권번호 등)는 서비스에서 직접 수집해야 합니다.

다음은 사용자 정보 가져오기 API를 통해 제공되는 정보입니다. 자료형과 형식을 포함한 상세 정보는 REST API 응답을 참고합니다.

Name Description
회원번호 서비스에서 각 사용자를 식별할 수 있는 고유한 값
카카오계정 정보 사용자의 카카오계정에 저장된 정보
프로필, 이메일과 같은 주요 사용자 정보 포함
연결 시각 사용자가 서비스 앱에 연결 완료된 시각
카카오싱크 간편가입 시각 사용자가 서비스 앱에 카카오싱크 간편가입을 통해 로그인한 시각
카카오싱크 간편가입 사용자라면 connected_at과 동일한 값으로 제공

제공 조건: 카카오싱크 사용
사용자 프로퍼티(Property) 서비스 정보 일부를 카카오 플랫폼에 저장하는 기능
설정하기 > 사용자 프로퍼티 참고

카카오계정 정보

카카오계정 정보에 포함된 각 항목은 정보 제공을 위해 해당 사용자 동의가 필요한지 알려주는 needs_agreement 값을 포함합니다. needs_agreement 값이 true라면 사용자 동의를 거쳐 해당 사용자 정보의 값을 받을 수 있는 상태입니다. 자세한 안내와 활용 방법은 needs_agreement를 참고합니다.

Permission: 필수 또는 선택 동의로 설정하기 위해 권한이 필요한 동의 항목, 설정 및 권한 획득 방법은 동의 항목 참고

사용자 정보 설명 필요한 동의 항목
프로필(닉네임/사진) 카카오계정의 프로필 정보

구성: 프로필 닉네임, 프로필 이미지 URL, 썸네일 이미지 URL, 기본 프로필 여부, 사용자 동의 시 제공 가능 여부
참고: 2021년 6월 25일부터 프로필 정보를 닉네임, 프로필 사진 중 필요한 항목만 선택하여 제공 받을 수 있음, 공지 참고
프로필 정보(닉네임/프로필 사진)
또는
닉네임
프로필 사진
이름 카카오계정 이름
카카오계정에 등록된 이름이 없다면, 수집 후 제공 설정을 통해 사용자 입력 후 제공받을 수 있음
이름
Permission
이메일 카카오계정 대표 이메일
사용자의 이메일 정보가 없을 수 있으므로 수집 후 제공 설정 또는 자체 수집이 가능해야 함
인증받은 이메일만 사용해야 하는 서비스라면 인증 여부를 참고해 미인증 이메일 사용자에게 자체적으로 인증 절차를 진행해야 함

구성: 대표 이메일, 이메일 인증 여부, 이메일 유효 여부, 사용자 동의 시 제공 가능 여부
주의: 사용자 요청에 따라 변경될 수 있으므로 이메일을 ID로 사용하거나 이메일로 동일 사용자인지 확인하는 방식을 권장하지 않음
카카오계정(이메일)
Permission
연령대 카카오계정의 연령대, 한국 나이 기준

구성: 연령대, 사용자 동의 시 제공 가능 여부
연령대
Permission
생일 카카오계정의 생일

구성: 생일, 생일 타입, 사용자 동의 시 제공 가능 여부
생일
Permission
출생 연도 카카오계정의 출생 연도

구성: 태어난 해, 사용자 동의 시 제공 가능 여부
출생 연도
Permission
성별 카카오계정의 성별

구성: 성별, 사용자 동의 시 제공 가능 여부
성별
Permission
전화번호 카카오계정의 전화번호

구성: 카카오톡에 등록된 전화번호, 사용자 동의 시 제공 가능 여부
주의: 수집 후 제공 설정 불가능
카카오계정(전화번호)
Permission
연계정보(CI) 카카오계정의 암호화된 이용자 확인 값
기존 회원 데이터베이스에 동일한 회원이 있는지 대조하는 등 최소한의 목적으로만 참고하도록 제공되는 정보

구성: 연계정보, 발급 시각, 사용자 동의 시 제공 가능 여부
주의: 카카오는 본인인증기관이 아니므로 카카오계정의 연계정보로 서비스에 필요한 본인 인증을 대신할 수 없음
CI(연계정보)
Permission
체크리스트: 필요한 사용자 정보 값을 제공 받지 못했을 때

사용자 정보 가져오기를 통해 원하는 사용자 정보를 응답 값으로 받지 못했다면 다음 사항들을 차례로 확인합니다. 1. 동의 항목에 해당 사용자 정보 동의 항목을 설정했는지 확인합니다. '필수 동의' 또는 '선택 동의'로 설정해야 사용자 정보를 받을 수 있습니다. 반드시 필요한 정보는 수집 후 제공 옵션을 사용합니다. 2. {FIELD_NAME}_needs_agreement의 값을 확인합니다.(예: email_needs_agreement) 값이 "true"이면 추가 항목 동의 받기를 통해 사용자에게 필요한 동의 항목의 동의를 받습니다.

다른 API로 받는 사용자 정보

Permission: 필수 또는 선택 동의로 설정하기 위해 권한이 필요한 동의 항목, 설정 및 권한 획득 방법은 동의 항목 설정 참고

사용자 정보 설명 필요한 동의 항목
배송지 정보 카카오계정의 배송지 정보 배송지정보(수령인명, 배송지 주소, 전화번호)
Permission
카카오톡 프로필 카카오톡 프로필
카카오계정 프로필과 별개

구성: 닉네임, 프로필 이미지, 썸네일 이미지
프로필
카카오톡 친구목록 카카오톡 친구 목록

주의: 검수를 통해 친구 목록 가져오기 API 사용 권한이 주어진 앱에서만 친구 목록을 받을 수 있으며, 권한을 받기 전에는 팀원으로 등록된 친구 목록만 받을 수 있음
검수를 통과해도 모든 카카오톡 친구 정보가 아닌 제공 조건에 만족하는 친구 정보만 받을 수 있다는 점에 유의
카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)
Permission
카카오톡 채널 추가 상태 및 내역 앱과 연결된 특정 카카오톡 채널과 사용자의 관계 정보
비즈니스 채널 연결 시 동의 항목 설정 권한 및 정보 제공 가능
카카오톡 채널 추가 상태 및 내역
카카오스토리 프로필 카카오스토리 프로필
카카오계정 프로필과 별개

구성: 닉네임, 프로필 이미지, 썸네일 이미지, 배경 이미지
프로필
카카오스토리 생일 카카오스토리 생일

구성: 생일, 생일 타입
생일
카카오스토리 프로필 URL 카카오스토리 프로필 URL 카카오스토리 프로필 URL

로그아웃

카카오 로그인의 로그아웃은 사용자가 카카오 로그인을 통해 발급받은 토큰을 만료시켜, 로그아웃을 요청한 서비스에서 해당 사용자 정보로 카카오 API를 호출할 수 없게 합니다. 이 로그아웃 처리는 카카오 API 이용에만 영향을 미치므로 서비스 회원 로그아웃은 자체 구현해야 합니다.

카카오계정의 로그아웃 처리는 다음과 같이 이뤄집니다:

  • 사용자가 같은 카카오계정으로 여러 기기에 로그인한 상태라면, 로그아웃을 요청한 기기에서만 로그아웃됩니다. 동일한 카카오계정으로 로그인되어 있는 다른 기기에서는 로그아웃 처리되지 않습니다.
  • 사용자가 같은 카카오계정으로 한 웹 브라우저에서 여러 서비스에 로그인한 상태라면, 로그아웃을 요청한 서비스에서만 로그아웃됩니다. 같은 웹 브라우저에 동일한 카카오계정으로 로그인되어 있는 다른 서비스에서는 로그아웃 처리되지 않습니다.

서비스 로그아웃 버튼을 통해 서비스와 카카오계정을 동시에 로그아웃 처리하고 싶다면 카카오계정과 함께 로그아웃 추가 기능을 사용합니다. 사용자가 로그아웃 버튼을 눌러 로그아웃을 요청했을 때, 사용자를 연결 페이지로 이동시켜 서비스만 로그아웃할 것인지, 카카오계정도 함께 로그아웃할 것인지 선택할 수 있도록 하는 기능입니다. 기본적인 로그아웃 기능은 토큰 만료 방식으로 동작하지만, 이 기능을 사용하면 요청한 서비스의 세션과 카카오 로그인의 세션을 만료하여 서비스와 카카오 계정에서 로그아웃 처리합니다.

카카오계정과 함께 로그아웃 기능을 사용하려면, 사용자가 로그아웃을 요청하고 리다이렉트될 Logout Redirect URI을 등록하고, 서비스 서버에서 서비스 세션을 만료시켜야 합니다. 기능 동작은 다음과 같이 이뤄집니다:

  • 사용자가 로그아웃 버튼을 눌러 연결 페이지로 진입합니다.
  • 사용자가 '서비스만 로그아웃', '카카오계정과 함께 로그아웃' 중 원하는 로그아웃 처리를 선택합니다.
  • 사용자가 서비스만 로그아웃을 선택했다면 즉시 앱 정보에 등록된 Logout Redirect URI로 리다이렉트됩니다.
  • 사용자가 카카오계정과 함께 로그아웃을 선택했다면 카카오계정 로그인 상태에 따라 다음과 같이 동작합니다.
    • 카카오계정 세션이 존재할 경우, 카카오계정 세션을 만료시킨 후 앱 정보에 등록된 Logout Redirect URI로 리다이렉트됩니다.
    • 카카오계정 세션이 존재하지 않을 경우, 즉시 앱 정보에 등록된 Logout Redirect URI로 리다이렉트됩니다.

카카오계정과 함께 로그아웃 기능은 REST API로 구현할 수 있습니다. 설정 및 구현 방법은 REST API 개발 가이드를 참고합니다.

연결과 연결 끊기

연결

연결은 카카오계정의 서비스 이용 상태를 의미합니다. 연결은 사용자가 서비스에 처음 로그인할 때 발생하며, 연결을 통해 서비스는 토큰 기반의 API를, 사용자는 해당 서비스에서 카카오 API를 각각 이용할 수 있게 됩니다. 서비스와 사용자가 서로 연결되어 있지 않다면 카카오 API 관련 기능을 이용할 수 없습니다.

연결은 카카오 로그인 시 카카오 플랫폼에서 처리하므로 서비스에서 별도 API를 호출해 요청할 필요가 없습니다. 하지만 연결을 끊는 것은 서비스에서도 가능합니다. 연결 끊기 API를 사용해 서비스와 사용자의 연결 상태를 해제할 수 있습니다.

연결 끊기

카카오 로그인 사용 시, 사용자가 앱과의 연결을 해제할 수 있는 수단도 제공해야 합니다. 연결 끊기 API를 통해 사용자와 앱의 연결을 해제할 수 있습니다. 카카오 로그인을 통해 서비스에 가입한 사용자가 탈퇴하거나, 카카오 로그인 연동 해제를 요청할 경우 연결 끊기 API를 호출해야 합니다.

연결 끊기는 사용자가 동의한 카카오 로그인 동의 항목에 대한 동의 철회 처리도 포함합니다. 따라서 연결 끊기 후에는 카카오 로그인 시 동의를 바탕으로 카카오 API를 통해 제공되는 사용자 정보를 더 이상 사용하지 않아야 합니다.

가입 미완료 사용자 처리 안내

2020년 12월 28일부터 가입 미완료 사용자에 대한 연결 끊기 처리가 매일 진행됩니다. 카카오 로그인 후, 서비스 가입에 필요한 사용자 정보를 요청하여 24시간 이내에 서비스 최종 가입을 완료하지 않은 사용자를 대상으로 합니다. 카카오 플랫폼에서 가입 미완료 사용자에 대한 연결 끊기 처리를 한 경우에도 연결 끊기 알림을 받을 수 있습니다. 자세한 내용은 공지사항을 참고합니다.

연결 끊기는 사용자가 직접 요청하기도 합니다. 사용자가 카카오톡 설정의 연결된 서비스 관리를 통해 연결 끊기를 요청한 경우, 카카오에서 서비스 서버에 알림을 보내 연결 끊기 및 사용자 정보 처리를 요청합니다. 자세한 내용은 연결 끊기 알림 받기를 참고합니다.

서비스 회원 가입 및 탈퇴

서비스 회원 가입은 카카오 로그인 사용자를 각 서비스 회원으로 등록하는 것으로, 연결과 별개로 서비스의 자체적인 회원 가입 처리가 필요합니다. 서비스에서 회원 가입 처리를 하지 않을 경우, 카카오 로그인한 사용자가 매번 새로 가입하는 과정을 거쳐야 하거나 이용에 불편을 겪을 수 있습니다. 다음은 일반적인 서비스 회원 가입 처리 과정입니다.

  1. 카카오 로그인을 완료하여 사용자 액세스 토큰을 받습니다.
  2. 사용자 정보 가져오기 API를 호출해 사용자 정보를 받습니다.
  3. 사용자 정보로 기존 회원인지 확인합니다.
  4. 기존 회원이 아닌 경우, 사용자 정보로 서비스 회원 가입 처리합니다.

서비스 회원 탈퇴 또한 서비스에서 자체적으로 구현하여 제공해야 합니다. 카카오는 서비스나 사용자의 연결 끊기 요청에 따라 연결을 해제할 수 있으나, 서비스의 회원 정보에 접근할 수는 없기 때문입니다. 다음은 일반적인 서비스 회원 탈퇴 처리 과정입니다.

  1. 사용자가 서비스에서 회원 탈퇴를 요청합니다.
  2. 해당 사용자에 대해 연결 끊기 API를 호출합니다.
  3. 연결 끊기 요청이 성공한 후, 해당 사용자를 서비스에서 회원 탈퇴 처리합니다.
iOS 앱 제공 시 소셜 로그인 관련 정책

iOS 앱을 제공하는 서비스인 경우, 애플 앱스토어(Apple App Store) 심사 지침에 따라 소셜 로그인 사용 시 앱 내에서 소셜 로그인 연동 해제 및 서비스 탈퇴 기능을 반드시 제공해야 합니다. 이 심사 지침은 오는 2022년 1월 31일 제출 건부터 적용되며, 자세한 사항은 App Store 심사 지침에서 확인할 수 있습니다.

추가 항목 동의 받기

추가 항목 동의 받기는 사용자가 첫 카카오 로그인 시 동의 화면에서 동의하지 않았지만, 서비스 이용 중 추가로 동의해야 하는 항목을 동의 요청하는 기능입니다. 추가 항목 동의 받기 API를 통해 사용자가 특정 기능을 이용하려고 할 때 필요한 사용자 정보나 서비스 접근권한에 동의하도록 할 수 있습니다.

주의: 이 기능으로 할 수 없는 일

사용자가 카카오에도 제공을 거부한 정보(needs_agreement = false)는 카카오도 수집할 수 없습니다. 이러한 정보는 서비스에서 추가 항목 동의 받기 기능을 사용해도 카카오로부터 제공 받을 수 없으므로, 자체적으로 사용자로부터 수집해야 합니다. 또한 서비스 약관은 이 기능로도 추가 동의받을 수 없습니다. 운영 중 추가되는 약관은 자체 페이지를 통해 사용자로부터 동의받아야 합니다.

Step 1. 필요한 동의 항목 확인하기

서비스 이용 중 사용자 추가 동의가 필요할 경우는 크게 다음 두 가지입니다:

  • 서비스 특정 기능 이용을 위해 추가 사용자 정보 제공이 필요한 경우
  • 카카오 API를 사용하기 위해 특정 동의 항목에 동의해야 하는 경우

추가 사용자 정보 제공을 위한 사용자 동의가 필요한 경우, 동의 내역 확인하기 API를 사용하면 사용자가 동의한 항목을 확인할 수 있습니다.

혹은 사용자 정보 가져오기 API를 통해서도 확인할 수 있습니다. 요청 시, 필요한 사용자의 동의가 없으면 해당 사용자 정보를 제외한 응답을 받습니다. 이 경우에는 {FIELD_NAME}_needs_agreement 값을 보고 사용자 동의가 필요한지 판단할 수 있습니다. 사용자가 동의하면 각 사용자 정보 제공이 가능할 경우에 true 값으로 반환되며, 자세한 정보는 needs_agreement를 참고합니다.

다음은 사용자가 이메일 동의 항목에 동의하지 않은 상태의 사용자 정보 가져오기 API의 응답 예제입니다.

Sample: 이메일 동의 항목에 사용자가 동의하지 않은 경우

{
  "id": 1633204891,
  "connected_at": "2021-02-18T06:13:55Z",
  "properties": {
    "nickname": "춘식이",
    "profile_image": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_640x640.jpg",
    "thumbnail_image": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_110x110.jpg"
  },
  "kakao_account": {
    "profile_needs_agreement": false,
    "profile": {
      "nickname": "춘식이",
      "thumbnail_image_url": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_110x110.jpg",
      "profile_image_url": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_640x640.jpg",
      "is_default_image": false
    },
    "email_needs_agreement": true       // 이메일 동의 항목에 사용자 동의 필요
  }
}

사용자가 이메일 동의 항목에 동의하지 않았으므로, 위 응답 예제에는 이메일 정보가 포함되어 있지 않습니다. 그러나 email_needs_agreement 값이 true이므로, 사용자가 동의하면 이메일 정보를 받을 수 있는 상태입니다. 서비스에서 해당 사용자의 이메일 정보를 사용하려면 추가 항목 동의 받기를 통해 이메일 동의 항목에 대한 동의를 요청해야 합니다.

사용자 동의가 없어 해당 카카오 API 요청이 실패했을 때, 에러 응답은 어떤 동의 항목에 대한 사용자 동의가 부족해서 api_type에 해당하는 API 요청이 실패하는지 required_scope로 알려줍니다. 또한 사용자가 이미 동의한 동의 항목 정보를 allowed_scopes로 확인할 수 있습니다. 사용자에게 required_scope의 동의 항목을 추가 항목 동의 받기 요청하고 동의 받아야 해당 API를 사용할 수 있습니다.

다음은 사용자가 필요한 동의 항목에 동의하지 않은 상태에서 카카오톡 메시지 API인 나에게 기본 템플릿으로 메시지 보내기를 요청하여 에러 응답을 받은 경우의 응답 예제입니다.

Sample: 카카오톡 메시지 보내기 기능 접근 권한이 없어 전송 실패
HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}

위 응답 예제의 경우, required_scopes 값으로 추가 동의받아야 할 항목이 talk_message임을 알려주고 있습니다. 따라서 추가 항목 동의 받기로 사용자에게 talk_message 동의를 요청하고, 사용자가 동의하고 나면 카카오톡 메시지 보내기를 할 수 있습니다.

Step 2. 추가 항목 동의 받기

사용자에게 필요한 동의 항목의 추가 항목 동의 받기를 요청합니다. 요청에 사용해야 할 동의 항목의 키는 [내 애플리케이션] > [카카오 로그인] > [동의 항목] 메뉴의 각 동의 항목 ID를 사용합니다.

자세한 구현 방법은 개발 가이드를 참고합니다:

Step 3. 토큰 재발급 및 결과 확인하기

사용자는 추가 항목 동의 받기를 통해 필요한 동의 항목에 동의하거나, 동의하지 않고 취소 버튼을 눌러 동의 화면을 닫을 수 있습니다. 따라서 사용자가 필요한 동의 항목에 동의했는지 확인하는 과정이 필요합니다.

사용자가 추가 동의를 요청한 동의 항목에 동의한 경우, 추가 항목 동의 받기의 응답은 인가 코드 받기와 동일합니다. 발급받은 인가 코드로 토큰 받기 요청을 하여 새로운 토큰을 발급받아야 합니다.

사용자 정보에 대한 추가 동의 여부를 확인하려면 토큰 받기 요청의 응답을 참고합니다. 토큰 받기 요청의 응답에 토큰 값과 함께 사용자가 동의한 동의 항목 정보가 scope로 포함돼 있으며, 추가한 동의 항목의 키가 응답에 포함되어 있는지 비교하여 확인합니다. 사용자가 필요한 동의 항목에 동의했다면 사용자 정보 가져오기를 통해 해당 동의 항목의 사용자 정보를 받아 사용할 수 있습니다.

Sample: 토큰 발급 받기 응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"{ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"{REFRESH_TOKEN}",
    "refresh_token_expires_in":25184000,
    "scope":"account_email profile"     // 사용자가 동의한 동의 항목 정보
}

카카오 API 사용에 필요한 추가 동의 여부 또한 토큰 받기 요청의 응답에 포함된 scope로 알 수 있으며, 해당 API 요청의 성공 여부로도 확인 가능합니다. 사용자가 필요한 동의 항목에 동의했다면 해당 카카오 API를 사용하는 서비스 기능을 이용할 수 있도록 합니다. 사용자가 동의하지 않았거나 에러 응답을 받는다면 다시 추가 항목 동의 받기를 요청하거나 해당 서비스 기능을 이용할 수 없도록 합니다.

지원 범위

API Android SDK iOS SDK JavaScript SDK REST API
로그인
로그아웃
연결 끊기
토큰 정보 보기
토큰 갱신하기
사용자 정보 가져오기
사용자 정보 저장하기
추가 항목 동의 받기
사용자 목록 가져오기
동의 내역 확인하기
동의 철회하기

REST API 로그인은 인가 코드 받기, 토큰 받기 두 단계로 구성되어 있으며, 서비스 관리자를 위한 기능인 사용자 목록 가져오기 기능을 지원합니다.