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

카카오 로그인

이해하기

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

기능 소개

카카오 로그인을 통한 서비스 로그인 및 가입

카카오 로그인은 카카오계정으로 다양한 서비스에 로그인할 수 있도록 하는 소셜 로그인 서비스입니다. 카카오싱크는 서비스 간편가입 등 카카오 로그인에 더 다양한 확장 기능을 제공하는 비즈니스 설루션입니다. 카카오 로그인과 카카오싱크가 제공하는 핵심 기능은 다음과 같습니다.

기능 카카오 로그인 카카오싱크
카카오톡 또는 카카오계정으로 간편한 사용자 로그인
사용자 로그인 시 서비스의 카카오톡 채널 추가 유도
사용자 고유 식별자 및 인증 정보, 기본적인 사용자 정보인 프로필과 이메일 데이터 제공
이름, 연령대, 생년월일, 성별, 배송지 등 서비스 가입에 필요한 다양한 사용자 정보 제공
카카오 로그인 시 이용약관 동의를 통해 한 번의 동의 절차만으로 간편가입
애플리케이션

카카오 로그인을 사용하려면 카카오디벨로퍼스(이하 개발자 웹사이트) 애플리케이션(이하 앱)이 필요합니다. 도입 안내에서 자세한 카카오 로그인 도입 과정과 안내를 확인할 수 있습니다.

카카오 로그인

카카오 로그인은 OAuth 2.0 기반의 소셜 로그인 서비스입니다. 카카오 로그인을 사용하면 사용자가 카카오톡 또는 카카오계정으로 손쉽게 서비스에 로그인할 수 있습니다. 서비스는 서비스 ID 및 비밀번호를 입력받고 검증하는 과정을 직접 구현하지 않고도 사용자에 대한 인증인가를 간편하고 안전하게 처리할 수 있습니다.

구분 설명
인증(Authentication) ID와 비밀번호로 사용자 신원을 확인
각 서비스에 사용자가 카카오계정으로 로그인할 수 있는 기능 지원
서비스에서 각 사용자를 식별할 수 있는 고유한 회원번호 제공

참고: OpenID Connect 지원, 로그인 세션 대신 사용 가능한 ID 토큰 제공 가능
인가(Authorization) 사용자 개인정보와 같은 자원(Resource)에 대한 접근 권한 획득
사용자 동의를 바탕으로 사용자 정보나 기능에 대한 접근 권한을 토큰 형태로 서비스에 부여

서비스는 카카오 로그인 완료 시 발급받은 토큰으로 회원 가입이나 정보 갱신에 필요한 사용자 정보를 제공받을 수 있습니다. 카카오 로그인의 추가 기능을 제공하는 카카오싱크 도입 시, 사용자에게 이용약관 동의와 카카오톡 채널 추가까지 한 화면에서 요청할 수 있습니다.

참고: 토큰

토큰은 사용자의 카카오 로그인 인증인가 정보를 담은 권한 증명으로, 카카오 API 호출에 사용됩니다. 카카오 로그인은 OAuth 2.0 표준 규격에 따라 액세스 토큰(Access token), 리프레시 토큰(Refresh token) 두 종류의 토큰을 발급합니다. OpenID Connect 사용 시, 사용자 인증 정보를 담은 ID 토큰을 함께 발급합니다. 각 토큰의 역할과 만료 시간을 표로 정리하면 다음과 같습니다.

구분 설명 만료 시간
액세스 토큰
(Access token)
사용자 인증, 카카오 API 호출 권한 부여 Android, iOS : 12시간
JavaScript: 2 시간
REST API : 6시간
리프레시 토큰
(Refresh token)
액세스 토큰 재발급에 사용
유효한 리프레시 토큰이 있다면 사용자가 매번 카카오계정 정보를 입력하거나 카카오톡으로 로그인하는 인증 절차를 거치지 않아도 액세스 토큰 재발급 가능
2달
만료 시간 1달 남은 시점부터 갱신 가능
ID 토큰
(ID token)
카카오 로그인 사용자의 인증 정보를 제공하는 토큰
자세한 정보는 OpenID Connect 참고
액세스 토큰과 동일

* Kakao SDK는 토큰 관리 기능 내장, REST API 사용 시 필요에 따라 토큰 정보 확인하기 또는 토큰 갱신하기 요청 필요

카카오싱크

카카오싱크는 카카오 로그인에 서비스 약관 동의와 카카오톡 채널 추가 기능을 더해, 사용자가 한 번의 동의 과정만으로도 서비스의 신규 회원으로 가입할 수 있는 간편가입을 지원합니다. 카카오싱크 간편가입을 도입하면 서비스의 로그인 및 가입 절차를 대폭 간소화하여 더 쉽게 회원을 확보할 수 있습니다. 도입 안내 등 보다 자세한 정보는 시작하기에서 확인할 수 있습니다.

카카오 로그인으로 대신할 수 있는 서비스 로그인 절차

서비스 로그인 과정

아래는 카카오 로그인을 통한 서비스 로그인 과정을 단계별로 나타낸 시퀀스 다이어그램(Sequence diagram)입니다.

카카오 로그인 과정 Step 1. 카카오 로그인
  1. 사용자가 서비스에서 카카오 로그인 버튼을 클릭합니다. 서비스는 카카오 인증 서버로 인가 코드 발급을 요청합니다.
  2. 카카오 인증 서버는 사용자에게 인증을 요청합니다. (참고: 사용자 환경에 따른 인증 방법)
    • 카카오톡으로 로그인: 카카오톡 실행, 카카오톡에 연결된 카카오계정의 자격정보(Credentials)로 사용자 인증
    • 카카오계정으로 로그인: 계정 정보를 입력해 로그인하는 화면 출력, 해당 카카오계정의 자격정보로 사용자 인증
  3. 카카오 인증 서버는 사용자 인증 성공 시, 서비스 앱의 동의 항목 설정을 바탕으로 사용자에게 동의 화면을 출력합니다.
  4. 사용자가 필수 동의 항목에 동의하고 로그인을 요청하면, 카카오 인증 서버는 인가 코드(Authorization Code)를 발급해 서비스 앱에 등록된 Redirect URI로 전달합니다.
  5. 서비스는 전달받은 인가 코드로 토큰을 요청하여 받습니다.
Step 2. 회원 확인 및 가입
  1. 서비스는 카카오 로그인을 완료하여 발급받은 토큰으로 사용자 정보 가져오기를 요청합니다.
  2. 카카오 API 서버는 요청 시 사용된 토큰의 유효성을 검증하고, 요청을 처리하고 서비스에 응답합니다.
  3. 서비스 서버는 카카오로부터 제공받은 사용자 정보로 해당 사용자가 서비스에 회원 가입되어 있는지 확인합니다.
    • 이미 회원 가입된 사용자: Step 3의 서비스 로그인 단계 수행
    • 아직 회원 가입되지 않은 사용자: 카카오에서 제공받은 사용자 정보로 서비스 데이터베이스에 회원 가입 처리
주의: 서비스 회원 정보

서비스 데이터베이스(Database)의 가입, 탈퇴 등 회원 정보 처리는 서비스에서 자체 구현해야 합니다. 카카오는 서비스 데이터에 접근하지 않으므로 회원 정보를 대신 저장하거나 삭제할 수 없습니다.

Step 3. 서비스 로그인
  1. 서비스 서버는 서비스 클라이언트에 해당 사용자의 로그인에 대한 세션을 발급합니다.
    • OpenID Connect 사용 시: 토큰과 함께 발급된 ID 토큰으로 서비스 로그인 세션을 대신할 수 있음
  2. 서비스 클라이언트는 서비스 세션을 전달받아 로그인 완료 처리하고, 사용자를 로그인된 서비스 화면으로 이동시킵니다.

도입 안내

서비스에 카카오 로그인을 도입하는 과정을 안내합니다.

Step 1. 서비스 요구사항 확인

먼저 서비스에서 카카오 로그인 및 카카오 API를 통해 제공받고자 하는 요구사항, 개발 및 서비스 환경을 확인합니다. 아래 표의 참고 문서에서 각 요구사항의 지원 여부를 확인할 수 있습니다.

분류 설명 참고 문서
1. 데이터 요구사항 서비스 가입 및 이용에 필요한 사용자 정보의 종류와 규격 검토
카카오 로그인을 통해 제공받을 수 있는 사용자 정보인지 확인
카카오 로그인 최초 도입 시부터 카카오싱크로 도입하면 시 더 다양한 사용자 정보를 제공받을 수 있음
사용자 정보
카카오싱크
2. 기능 요구사항 서비스에서 제공받고자 하는 카카오 플랫폼 제품 및 기능 확인
카카오 로그인 도입 시, 토큰으로 요청하는 다양한 카카오 API 활용 가능
제품
3. 개발 및 서비스 환경 프로그래밍 언어, 프레임워크, 시스템 구조, 모바일 앱 또는 웹 지원 여부 등
카카오 로그인 구현 방법 검토 시 고려해야 할 서비스 환경과 제약조건 확인
지원 범위
필수 사용자 정보와 선택 사용자 정보

카카오는 개인정보 보호를 위해 사용자 정보를 필수 또는 선택으로 구분하여 서비스에 제공합니다. 서비스는 용도에 맞게 제공받을 사용자 정보의 필수 여부를 설정할 수 있습니다. 자세한 안내는 동의 항목을 참고합니다.

서비스 요구사항에 맞춰 더 다양한 데이터와 기능을 제공받을 수 있도록, 카카오 로그인과 카카오싱크를 함께 도입하기를 권장합니다. 아래의 카카오싱크 도입 필요 여부 판단을 위한 의사 결정 나무 이미지를 참고합니다.

카카오싱크 도입 여부 판단을 위한 의사 결정 나부
Step 2. 앱 설정

카카오 로그인을 사용하려면 개발자 웹사이트 앱이 필요합니다. 등록된 앱이 없다면 애플리케이션을 참고해 새로운 앱을 등록합니다. 서비스의 앱이 이미 등록돼 있다면, 새로운 앱을 등록하지 않고 기존 앱을 사용해야 합니다.

카카오 로그인 사용에 필요한 설정을 앱에 적용합니다. 설정은 카카오 로그인을 사용하기 위해 반드시 설정해야 하는 필수 설정, 필요에 따라 설정하는 선택 설정 두 종류로 나눌 수 있습니다. 아래 필수 설정과 선택 설정 목록을 참고합니다.

Step 3. 연동 개발

카카오 로그인은 앱 정책이나 UI/UX 등에 따라 다양한 사용자 동선을 고려하여 편리하게 사용할 수 있도록 설계되었습니다. 또한 다양한 서비스 개발 환경에서 손쉽게 사용할 수 있도록 REST API 뿐만 아니라 Android, iOS, JavaScript 플랫폼용 Kakao SDK(Software Development Kit)를 제공합니다.

개발 및 서비스 환경에 적합한 구현 방법을 선택하여 연동 개발과 테스트를 진행합니다. REST API와 Kakao SDK를 함께 사용할 수도 있습니다. 연동 개발에 필요한 요청 및 응답 규격, 예제 등 상세 정보는 아래 개발 가이드에서 확인할 수 있습니다.

문제 해결

카카오 인증 서버로부터 에러 응답을 받은 경우, 문제 해결에서 원인과 해결 방법을 확인합니다.

인증

사용자는 카카오 로그인을 통해 카카오톡 또는 카카오계정으로 서비스에 로그인할 수 있습니다. 카카오 로그인은 카카오톡에 연결된 카카오계정의 자격정보 또는 카카오계정 ID와 비밀번호로 사용자 신원을 인증합니다. 서비스는 카카오 로그인을 통해 신뢰할 수 있는 인증 정보를 제공받아, 직접 사용자 ID와 비밀번호를 입력받지 않고도 인증을 수행할 수 있습니다.

카카오 로그인은 다양한 서비스 환경과 요구사항을 지원할 수 있도록 편리한 사용자 환경별 인증 방법카카오톡에서 자동 로그인 기능을 제공합니다.

사용자 환경별 인증 방법

카카오 로그인은 사용자 환경에 적합한 방식으로 인증을 요청하도록 구현할 수 있습니다. 다음 표를 참고합니다.

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

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

카카오톡으로 로그인 과정 카카오계정으로 로그인 과정
카카오톡을 통한 간편 로그인

하이브리드 앱을 비롯한 모바일 웹 환경에서는 JavaScript SDK의 간편 로그인 함수 사용을 권장합니다. 간편 로그인을 사용해 서비스 웹 페이지에서 인가 코드를 요청하고, 서비스 서버에서 토큰 받기를 요청하는 구조로 더 편리하고 안전하게 카카오 로그인을 구현할 수 있습니다.

카카오톡에서 자동 로그인

카카오톡에서 자동 로그인(이하 자동 로그인)은 카카오톡 인앱브라우저를 통한 서비스 페이지 진입 시, 서비스 가입 여부에 따른 분기 처리를 지원하는 카카오 로그인의 추가 기능입니다. 카카오 로그인을 통해 가입한 사용자는 자동으로 로그인된 서비스 페이지로, 미가입 사용자는 로그인되지 않은 페이지로 각각 이동시켜 편리한 사용자 동선을 제공할 수 있습니다.

다음은 자동 로그인 예시 시나리오입니다.

  1. 자동 로그인 기능 적용 대상은 카카오톡 공유를 통해 전파될 가능성이 높은 상품 판매 페이지라고 가정합니다.
  2. 사용자가 카카오톡 인앱브라우저에서 대상 페이지에 들어왔는지 브라우저 정보를 확인합니다.
  3. 카카오톡 인앱브라우저를 통해 들어온 사용자로 판단되면 자동 로그인을 요청합니다.
  4. 사용자의 카카오싱크를 통한 가입 여부에 따라 인가 코드 또는 에러 응답을 받아 분기 처리합니다.
    • 가입한 사용자: 로그인된 상태의 상품 판매 페이지를 출력, 곧바로 상품을 구입할 수 있도록 처리
    • 미가입 사용자: 로그인되지 않은 상태의 상품 판매 페이지 출력, 필요 시 직접 로그인할 수 있도록 처리
카카오톡에서 자동 로그인 참고 화면

서비스는 다음 3단계의 과정을 구현하여 자동 로그인을 사용할 수 있습니다.

Step 1. 서비스 페이지 진입 시 브라우저 확인

자동 로그인은 카카오톡 안에서 열리는 인앱브라우저에서만 동작합니다. UserAgentKAKAOTALK이 포함돼 있는지 확인하여 카카오톡 인앱브라우저를 통한 서비스 페이지 진입인지 판단하는 로직을 서비스 페이지에 추가합니다.

UserAgent
Browser Rule Description
카카오톡 인앱브라우저 KAKAOTALK Mozilla/5.0 (Android; Mobile; rv:13.0) Gecko/13.0 Firefox/13.0 KAKAOTALK
Step 2. 자동 로그인을 위한 인가 코드 받기 요청

사용자 브라우저가 카카오톡 인앱브라우저로 확인되었다면, 인가 코드 받기prompt 파라미터 값을 none으로 지정하여 요청합니다. 카카오톡에서 자동 로그인를 참고합니다.

Step 3. 인가 코드 받기 응답에 따른 분기 처리

요청 성공 시 사용자의 서비스 가입 여부에 따라 구분된 응답이 반환되며, 다음과 같이 분기 처리합니다.

  • 카카오 로그인을 통해 서비스에 가입한 사용자인 경우
    • 카카오: 응답으로 인가 코드 반환
    • 서비스: 응답으로 받은 인가 코드로 토큰 받기를 요청해 카카오 로그인 및 서비스 로그인 완료 처리 후, 사용자에게 로그인된 상태의 서비스 페이지 출력
  • 서비스에 가입하지 않은 사용자인 경우
    • 카카오: 서비스 이용을 위해 사용자 동의가 필요하다는 에러 응답(consent_required) 반환
    • 서비스: 사용자에게 로그인되지 않은 상태의 서비스 페이지 출력

아래는 자동 로그인 과정을 간략히 표현한 시퀀스 다이어그램입니다.

카카오톡으로 자동 로그인 과정

기존 로그인 여부와 상관없이 로그인

기존 로그인 여부와 상관없이 로그인하기는 서비스의 필요에 따라 사용자 인증을 다시 수행하고자 할 때 사용하는 추가 기능입니다. 이 기능을 사용하면 사용자가 브라우저에 카카오계정으로 로그인되어 있는 상태라도 다시 카카오계정으로 로그인하는 과정을 거쳐 서비스에 카카오 로그인하도록 할 수 있습니다.

기존 로그인 여부와 상관없이 로그인하기는 OAuth 2.0 표준 규격에 따라 prompt 파라미터의 값을 login으로 지정해 요청할 수 있습니다. 각 개발 가이드의 예제를 참고합니다.

인가

카카오 로그인은 사용자 인증 성공 시 동의 화면을 통해 사용자에게 인가를 요청합니다. 인가는 카카오가 서비스에 자원 접근권한닉네임, 이메일과 같은 카카오계정의 사용자 정보나 카카오톡 메시지 전송과 같은 기능의 사용 권한을 제공해도 될지 사용자의 동의를 구하는 일입니다. 서비스는 개발자 웹사이트 앱에 동의 화면의 구성 요소인 동의 항목을 설정해 필요한 자원 접근권한을 인가받을 수 있습니다.

예를 들어, 서비스가 회원 가입에 필요한 프로필 사진과 닉네임을 앱의 동의 항목으로 설정하면, 카카오 로그인은 동의 화면에서 카카오계정 프로필 사진과 닉네임 제공에 대한 사용자의 동의를 구합니다. 사용자가 해당 서비스에 카카오 로그인하면 아래와 같은 동의 화면이 출력됩니다.

카카오톡에서 자동 로그인 참고 화면

사용자는 동의 화면에서 🅐 개인정보 제공 안내를 확인하고, 🅑 서비스 이용에 필요한 동의 항목에 동의할 수 있습니다. 사용자가 동의 화면에서 동의 항목에 동의하면, 카카오 로그인은 사용자의 동의 내역을 인가 코드에 담아 서비스에 전달합니다. 서비스가 인가 코드로 토큰을 발급받으면 카카오 로그인이 완료됩니다.

참고: 동의 철회

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

동의 항목

카카오 플랫폼을 통해 사용자 정보나 기능을 제공받으려면 카카오 로그인 시 자원 접근권한에 대한 사용자의 동의를 받아야 합니다. 사용자에게 인가받지 않은 사용자 정보나 기능은 카카오 API를 통해 제공받을 수 없습니다.

서비스는 서비스 제공을 위해 필요한 자원 접근권한을 개발자 웹사이트 앱에 동의 항목으로 설정해야 합니다. 닉네임, 프로필 사진, 이메일과 같은 종류별 사용자 정보나 카카오톡 메시지 전송 등 접근권한에 대해 개별 동의 항목이 제공됩니다. 앱에 설정된 동의 항목은 해당 서비스의 카카오 로그인 동의 화면에 반영됩니다.

각 동의 항목은 용도에 따라 [필수], [선택], [이용 중 동의]와 같은 동의 단계를 설정할 수 있습니다. 자세한 설정 안내는 설정하기를 참고합니다.

동의 항목 설정 없이 카카오 로그인을 사용할 수는 없나요?

회원 가입을 하지 않거나 사용자 정보 제공이 필요하지 않은 서비스라면 동의 항목 설정 없이 카카오 로그인을 사용할 수 있습니다. 앱에 설정된 동의 항목이 없는 경우, 카카오 로그인 동의 화면은 서비스의 앱과 사용자의 연결에 대한 안내만 포함합니다.

참고: 동의 단계
동의 단계 설명
필수 동의 사용자가 서비스 이용을 위해 반드시 동의해야 하는 항목으로 카카오 로그인 시점에 사용자의 동의를 요청합니다.
선택 동의 사용자가 서비스 이용을 위해 선택적으로 동의해야 하는 항목입니다. 카카오 로그인 시점에 사용자의 동의를 요청하나, 사용자가 동의하지 않아도 카카오 로그인을 완료할 수 있습니다. 사용자 미동의 시, 필요한 시점에 추가 항목 동의 받기로 다시 동의를 요청할 수 있습니다.
이용 중 동의 카카오 로그인 시 동의를 받지 않고, 정보가 필요한 시점에 사용자의 동의를 요청합니다. 서비스 가입 및 기본 기능 이용에 필요한 동의 항목이 아닌, 특정 기능 제공 시에만 필요한 동의 항목에 사용합니다. [이용 중 동의]로 설정된 동의 항목은 동의 화면에 기본적으로 노출되지 않으며, 필요한 시점에 추가 항목 동의 받기로 동의를 요청할 수 있습니다.
사용 안함 사용자의 동의를 요청하지 않습니다.
참고: scope 파라미터

OAuth 2.0 표준 규격에 따라, 카카오 로그인은 인가 코드 받기(로그인) 요청의 scope 파라미터에 지정된 동의 항목을 동의 화면에 출력합니다. 서비스에서 매번 동의 항목을 지정할 필요가 없도록, scope 파라미터 미포함 요청 시 앱에 설정된 동의 항목 키를 해당 파라미터의 기본값으로 적용합니다. 단, scope 파라미터 값을 특정해야 하는 추가 항목 동의 받기 시에는 반드시 scope 파라미터를 포함해 요청해야 합니다. 아래는 scope 파라미터 포함 여부에 따른 카카오 로그인의 동작 차이를 정리한 표입니다.

요청 구분 카카오 로그인 동작 OpenID Connect 사용 시 동작
scope 파라미터 미포함 앱에 [필수] 또는 [선택]으로 설정된 동의 항목으로 구성된 동의 화면 출력 토큰 받기 요청 시 ID 토큰 함께 발급
앱에 OpenID Connect 활성화 설정이 활성화인 경우 scopeopenid를 포함하여 요청 처리*
scope 파라미터 포함
(추가 항목 동의 받기)
scope 파라미터 값에 명시된 동의 항목만으로 구성된 동의 화면 출력 토큰 받기 요청 시 ID 토큰 발급하지 않음
OpenID Connect 사용 시, 추가 항목 동의 받기를 요청하려면 scope 파라미터 값에 openid를 포함하여 요청해야 ID 토큰 발급 가능*

* OpenID Connect 표준 규격에 따라, 카카오 로그인 시 ID 토큰을 발급받으려면 scope에 openid를 포함하여 요청해야 함

추가 항목 동의 받기

추가 항목 동의 받기는 사용자가 서비스 이용을 위해 추가 동의해야 하는 동의 항목의 동의를 요청하는 기능입니다. 추가 항목 동의 받기는 사용자가 동의해야 할 동의 항목의 키를 scope 파라미터에 명시하여 요청합니다. 요청 성공 시, 해당 동의 항목을 포함한 동의 화면을 출력해 사용자에게 동의받을 수 있습니다.

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

카카오 플랫폼은 추가 동의가 필요한 동의 항목이 무엇인지 다음과 같은 방법으로 안내합니다.

  1. 사용자 정보 가져오기 응답의 사용자 동의 시 정보 제공 가능 여부 필드
  2. 이 외 API 응답의 -402 에러 코드required_scopes 필드
  3. 필요한 동의 항목 목록과 동의 내역 확인하기 응답 대조

아래는 추가 항목 동의 받기 필요한 경우의 응답 예제입니다.

Sample: 이메일 동의 항목에 추가 항목 동의 받기 필요
HTTP/1.1 200 OK
{
    ...
    "kakao_account": {
        ...
        "email_needs_agreement": true    // 이메일 동의 항목에 사용자 동의 필요
        ...
    }
}
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"
  ]
}
Step 2. 추가 항목 동의 받기

필요한 동의 항목의 추가 항목 동의 받기를 요청합니다. 요청 시 사용할 동의 항목의 키는 [내 애플리케이션] > [카카오 로그인] > [동의 항목] 메뉴의 각 동의 항목 [ID], 또는 -402 에러 응답의 required_scopes 값을 사용합니다. 자세한 구현 방법은 개발 가이드를 참고합니다.

주의

OpenID Connect를 사용하는 앱의 경우, 추가 항목 동의 받기 요청 시 동의 항목 키를 전달하는 scope 파라미터 값에 openid를 반드시 포함해야 합니다. (참고: scope 파라미터)

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

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

  • 사용자가 필요한 동의 항목에 동의한 경우
    • 추가 항목 동의 받기 요청 성공, 인가 코드 발급
    • 인가 코드로 토큰 받기 요청, 응답의 scope 값으로 필요한 동의 항목의 동의 완료 여부 확인
    • 새로 발급받은 토큰으로 사용자 정보 가져오기 등 필요한 카카오 API 요청
  • 사용자가 취소한 경우
    • 추가 항목 동의 받기 실패, access_denied 에러 응답 반환
    • 서비스 이용을 위해 추가 동의가 필요함을 사용자에게 안내하고, 재요청 또는 이전 페이지 이동 등 예외처리
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의 목록을 확인할 수 있습니다. 카카오 플랫폼은 대부분의 사용자 정보를 사용자 정보 가져오기를 통해 제공합니다. 이밖에도 서비스는 카카오 로그인 시 동의 항목 설정에 따라 여러 카카오 서비스의 사용자 정보를 제공받을 수 있습니다. 주민등록번호, 여권번호, 의류 사이즈 등 정보는 카카오 플랫폼에서 제공하지 않으므로 서비스가 직접 사용자로부터 수집해야 합니다.

참고: 사용자 정보 제공을 위한 체크리스트

사용자 정보 가져오기를 통해 필요한 사용자 정보를 제공받지 못했다면 다음 사항을 확인합니다.

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

사용자 프로퍼티(User property)는 서비스 정보 일부를 카카오 플랫폼에 저장하는 기능입니다. 카카오는 서비스 데이터에 접근하지 않으므로, 서비스 데이터는 카카오 플랫폼에 저장되지 않습니다. 하지만 서비스의 필요에 따라 특정 정보를 카카오 플랫폼에 저장하고 사용자 정보 가져오기로 불러와 사용할 수 있는 저장 공간을 제공합니다. 사용자 프로퍼티 등록 방법은 설정하기에서 확인할 수 있습니다.

기본 정보

다음은 사용자 정보 가져오기를 통해 제공받을 수 있는 사용자의 기본 정보카카오계정 정보입니다. 이 정보들은 앱에 동의 항목을 설정하지 않아도 제공받을 수 있습니다.

사용자 정보 설명
회원번호 각 서비스의 사용자 식별자
서비스 앱에 카카오 로그인한 사용자마다 고유한 값 보유
연결 시각 사용자가 서비스 앱에 연결 완료된 시각
카카오싱크 간편가입 시각 사용자가 서비스 앱에 카카오싱크 간편가입을 통해 로그인한 시각
카카오싱크 간편가입 사용자라면 연결 시각과 동일

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

참고: 사용자 프로퍼티

카카오계정 정보

다음은 서비스에서 제공받을 수 있는 카카오 로그인 사용자의 카카오계정 정보입니다. 카카오계정 정보를 제공받으려면 앱에 개인정보 동의 항목을 설정해야 합니다. 모든 개인정보 동의 항목은 카카오싱크 도입 시 개인정보 제공 항목 검수를 거쳐 [필수] 동의 단계로 설정할 수 있습니다.

동의 항목
(ID)
설명 기본 제공 동의 단계
닉네임
(profile_nickname)
카카오계정 프로필 닉네임 필수
프로필 사진
(profile_image)
카카오계정 프로필 사진

구성: 카카오계정 프로필 사진 URL, 썸네일 이미지 URL
필수
카카오계정(이메일)
(account_email)
카카오계정 대표 이메일
서비스에서 참고할 수 있는 이메일 인증 여부 제공

구성: 대표 이메일, 이메일 인증 여부, 이메일 유효 여부, 사용자 동의 시 정보 제공 가능 여부
비고: 이메일 사용 시 주의사항
필수¹⁾
이름
(name)
카카오계정 이름 선택²⁾
성별
(gender)
카카오계정의 성별

구성: 성별, 사용자 동의 시 정보 제공 가능 여부
선택
연령대(age_range) 카카오계정의 연령대, 한국 나이 기준
14세 미만, 14세 이상, 20대, 30대 등 대략적인 나이

구성: 연령대, 사용자 동의 시 정보 제공 가능 여부
선택
생일
(birthday)
카카오계정의 생일

구성: 생일, 사용자 동의 시 정보 제공 가능 여부
선택
출생 연도
(birthyear)
카카오계정의 출생 연도

구성: 태어난 해, 사용자 동의 시 정보 제공 가능 여부
선택²⁾
카카오계정(전화번호)
(phone_number)
카카오계정과 연결된 카카오톡에 등록된 전화번호

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

구성: 연계정보, 발급 시각, 사용자 동의 시 정보 제공 가능 여부
주의: 카카오는 본인인증기관이 아니므로 카카오계정의 연계정보로 서비스에 필요한 본인 인증을 대신할 수 없음
미지원
배송지³⁾
(shipping_address)
카카오계정의 배송지 정보

구성: 수령인 이름, 수령인 연락처, 주소, 주소 유형, 우편번호
제공 조건: 비즈 앱 전환카카오톡 채널 연결
선택²⁾

¹⁾ 비즈 앱 전환 시 필수 동의 단계 설정 가능

²⁾ 비즈 앱 전환카카오톡 채널 연결 시 선택 동의 단계 설정 가능

³⁾ 배송지의 경우, 사용자 정보 가져오기가 아닌 배송지 조회하기를 통해 제공

주의: 필수 사용자 정보

서비스에 반드시 필요한 사용자 정보의 동의 항목은 [필수] 동의 단계로 설정하고 [카카오계정으로 수집 후 제공] 옵션을 사용해야 합니다. 카카오싱크 도입 시 필요한 모든 동의 항목을 [필수] 동의 단계로 설정할 수 있으므로, 카카오 로그인과 카카오싱크를 함께 도입할 것을 권장합니다. 단, 동의 항목을 설정했더라도 카카오에서 정보 제공이 불가능한 경우가 있으므로, 사용자 동의 시 정보 제공 가능 여부를 참고하여 서비스에서 자체 수집해야 합니다.

참고: 프로필

[닉네임], [프로필 사진] 동의 항목은 서비스의 필요에 따라 필수 또는 선택으로 설정할 수 있습니다. 앱의 동의 항목은 카카오 로그인 기능을 활성화하더라도 자동 설정되지 않으므로 서비스에서 직접 설정해야 합니다. [프로필(닉네임/프로필 사진)] 동의 항목을 사용 중인 앱은 [닉네임] 또는 [프로필 이미지] 중 필요한 항목만 개별 설정하려면 변경 신청을 해야 합니다.

서비스 회원 연동

회원 가입이 필요한 서비스는 카카오 로그인 사용자를 서비스 회원 가입 처리해야 합니다. 서비스 회원 가입 처리가 누락될 경우, 사용자가 로그인할 때마다 회원 가입 절차를 거치는 불편을 겪을 수 있습니다. 카카오 로그인 완료 시 필요한 사용자 정보를 카카오 플랫폼에 요청하거나 사용자에게 입력받아 서비스 회원 정보에 사용자를 등록하여 가입 처리합니다.

이미 운영 중인 서비스라면 카카오 로그인을 통해 로그인한 사용자가 기존 서비스 회원일 수 있습니다. 이 경우, 사용자를 신규 가입 처리하지 않고 기존 서비스 회원 계정에 카카오 로그인을 연동하는 것을 권장합니다.

다음은 일반적인 서비스 회원 계정 연동 과정을 나타낸 절차도와 단계별 안내입니다. 유형별 연동 안내를 함께 참고합니다.

회원 연동 시 의사 결정 나무 Step 1. 기존 서비스 회원 여부 확인
  • 카카오 로그인 완료 후 사용자 정보 요청, 제공받은 사용자 정보로 기존 서비스 회원 여부 확인
  • 유형별 연동 안내를 참고하여 기존 서비스 회원 정보와 카카오 로그인 사용자 정보 대조
  • 회원번호(필수), 이름, 이메일(권장), 생일, 출생연도, CI(권장) 참고 가능
  • CI의 경우, 서비스에서 CI를 보유한 경우에 한해 카카오싱크 도입 시 대조 목적으로 제공 가능
Step 2. 사용자에게 계정 및 연동 의사 확인
  • 타인 계정과 연동되지 않도록, 이메일 인증과 같은 확인 절차 필요
  • 마스킹(Masking) 처리된 서비스 회원 계정 ID, 가입일, 닉네임 등 정보로 확인
Step 3. 카카오 로그인과 서비스 회원 계정 연동
  • 사용자가 계정 확인 후 연동 동의 시, 카카오 로그인을 통해 기존 서비스 회원 계정으로 로그인할 수 있도록 회원번호로 연동 처리
    • 회원정보 외 카카오 로그인 사용자 정보로 서비스 회원 정보 갱신
    • 회원 가입을 위해 사용자 정보가 추가로 필요한 경우, 추가 항목 동의 받기를 요청해 카카오로부터 제공받거나 자체 수집
    • 카카오싱크 도입 서비스인 경우, 동의한 약관 확인하기를 요청해 사용자가 카카오싱크 간편가입 시 동의한 서비스 약관 확인, 추가 동의가 필요한 약관이 있다면 동의 절차 진행
  • 사용자가 연동 미동의 시, 서비스 회원 신규 가입으로 처리
주의: 사용자 정보 변경

회원번호와 CI를 제외한 카카오계정 정보는 사용자가 언제든지 변경할 수 있습니다. 이메일, 전화번호와 같이 변경 가능한 정보를 카카오 로그인 연동 사용자의 서비스 회원 ID로 삼거나 계정 확인 없이 연동 처리하지 않아야 합니다.

참고: 회원 정보 페이지 내 계정 연동 옵션 제공

서비스에 카카오 로그인 또는 카카오싱크 도입 후, 기존 회원에게도 카카오 로그인 연동 기능을 제공할 수 있습니다. 아래는 회원 정보 페이지를 통한 카카오 로그인 연동 예시입니다.

기존 회원 연동 예시 화면

유형별 연동 안내

사용자 정보 일치
  • 카카오 로그인 사용자 정보가 서비스의 기존 회원 확인 조건을 만족한 경우
    • 예: 이메일과 CI가 일치하는 서비스 회원 계정 존재
  • 사용자에게 기존 서비스 회원 계정에 대한 단서를 제공하고, 카카오 로그인 연동 의사 확인
사용자 정보가 일치할 경우 회원가입 처리
사용자 정보 일부 일치
  • 카카오 로그인 사용자 정보가 서비스의 기존 회원 확인 조건 중 일부만 만족한 경우
    • 예: 사용자 정보가 두 개 이상의 서비스 회원 계정과 일치하는 경우
  • 사용자에게 기존 서비스 회원 계정에 대한 단서를 제공하고, 사용자 로그인 등 계정 확인 절차 수행
  • 사용자가 계정 확인에 성공한 경우, 카카오 로그인 연동 의사 확인
사용자 정보가 일부 일치할 경우 회원가입 처리
일치하는 사용자 정보 없음
  • 신규 가입으로 처리
  • 가입 후 사용자에게 기존 가입 여부 등을 확인해 서비스 회원 계정과 연동하는 기능 제공
일치하는 정보가 없을 경우 회원가입 처리

서비스 회원 연동 시 주의사항

  • 회원정보가 완전히 일치하더라도 사용자에게 연동할 계정 정보와 계정 연동 의사를 확인하는 절차를 거쳐야 합니다.
    • 일부 회원의 경우 계정 연동을 원치 않거나, 서비스 이용을 시도하는 사용자와 실제 계정 정보의 소유자가 다를 수도 있습니다.
  • 서비스 회원 연동 설계 시, 카카오 로그인 및 서비스 가입 시점과 다른 사용자 정보가 제공될 수 있음을 고려해야 합니다.
    • 사용자 정보 가져오기를 통해 서비스에 제공되는 사용자 정보는 종류나 값이 달라질 수 있습니다.
    • 사용자는 카카오계정의 생일, 성별 등 개인정보를 추가 또는 변경할 수 있습니다.
    • 카카오계정의 연계정보(CI) 또한 사용자가 필요에 따라 삭제할 수 있습니다.

로그아웃

로그아웃은 사용자가 카카오 로그인을 통해 발급받은 토큰을 만료시키는 기능입니다. 카카오 로그인한 사용자가 서비스 로그아웃을 요청한 경우, 로그아웃을 통해 토큰을 만료시켜야 정상적으로 서비스 로그아웃 처리를 완료할 수 있습니다. 로그아웃은 요청 방법에 따라 다음과 같이 동작합니다.

  • 액세스 토큰으로 요청
    • Kakao SDK를 통해 로그아웃 요청 시 액세스 토큰으로 요청만 가능
    • 해당 액세스 토큰만 만료 처리
    • 만료된 액세스 토큰을 사용하는 모든 기기에서 로그아웃됨
  • 어드민 키로 요청
    • REST API를 통한 로그아웃 요청 시에만 어드민 키로 요청 가능
    • 해당 사용자의 모든 토큰 만료 처리
    • 모든 기기에서 로그아웃됨

공용 PC와 같이 사용자 계정 보안에 주의가 필요한 환경이거나, 사용자가 다른 카카오계정으로 다시 로그인하도록 해야 하는 상황이라면 카카오계정과 함께 로그아웃 기능을 사용합니다.

카카오계정과 함께 로그아웃

서비스 로그아웃 버튼을 통해 서비스 로그아웃 시 카카오계정도 동시에 로그아웃 처리하고 싶다면 카카오계정과 함께 로그아웃 기능을 사용합니다. 카카오계정과 함께 로그아웃은 서비스만 로그아웃할 것인지, 카카오계정도 함께 로그아웃할 것인지 선택할 수 있는 연결 페이지를 제공하는 기능입니다. 동작 과정은 다음과 같습니다.

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

카카오계정과 함께 로그아웃은 Logout Redirect URI 등록 후 REST API로 요청할 수 있습니다. REST API 개발 가이드를 참고합니다. 아래는 카카오계정과 함께 로그아웃의 연결 페이지 예시 화면입니다.

카카오계정과 함께 로그아웃 화면

OpenID Connect

OpenID Connect(OIDC)는 사용자가 안전하게 로그인하는 데 사용할 수 있는 OAuth 2.0 기반의 표준 인증 프로토콜입니다. 카카오 로그인의 확장 기능으로써 지원되며, [내 애플리케이션] > [카카오 로그인] > [OpenID Connect]에서 OpenID Connect 활성화 설정을 통해 사용할 수 있습니다.

OpenID Connect를 사용하는 앱에서 카카오 로그인을 구현하는 과정은 다음 순서로 진행되어야 합니다.

Step 1. 메타데이터 확인하기

먼저 카카오 로그인의 OpenID Connect 서비스 제공자 설정을 확인합니다. 카카오 로그인은 OpenID Connect Discovery 표준 규격에 따라 서비스 제공자 설정을 담은 메타데이터(Metadata) 문서를 제공합니다. OIDC: 메타데이터 확인하기에서 상세 규격을 확인할 수 있습니다.

Step 2. 카카오 로그인 구현

[내 애플리케이션] > [카카오 로그인] > [OpenID Connect]를 활성화한 뒤, 각 플랫폼 개발 가이드를 참고하여 카카오 로그인을 구현합니다. OpenID Connect를 활성화한 앱은 카카오 로그인을 통해 사용자 인증 정보가 담긴 ID 토큰을 액세스 토큰과 함께 발급받을 수 있습니다.

ID 토큰은 서비스의 로그인 세션 대신 사용할 수 있는 JSON Web Token(이하 JWT) 형식의 토큰입니다. 서비스는 ID 토큰에 포함된 사용자 인증 정보를 서비스에 활용하거나, ID 토큰의 유효성을 검증할 수 있습니다. ID 토큰의 만료 시간은 액세스 토큰과 동일합니다.

참고: ID 토큰 정보

ID 토큰은 다음 세 가지 영역으로 구성돼 있습니다.

구분 설명
헤더(Header) ID 토큰의 규격 정보
카카오 로그인을 통해 발급되는 ID 토큰의 헤더는 다음 정보를 포함함
alg: ID 토큰에 적용된 암호화 방식, RS256으로 고정
typ: ID 토큰의 형식, JWT로 고정
kid: ID 토큰 암호화 시 사용된 공개키 ID, OIDC: 공개키 목록 조회하기를 통해 ID 토큰별로 사용된 공개키의 값을 확인할 때 필요한 정보
페이로드(Payload) 사용자 인증 정보
iss: ID 토큰을 발급한 인증 기관 정보, https://kauth.kakao.com로 고정
aud: ID 토큰이 발급된 앱의 앱 키
sub: ID 토큰에 해당하는 사용자의 회원번호
iat: ID 토큰 발급 또는 갱신 시각
auth_time: 사용자가 카카오 로그인을 통해 인증을 완료한 시각
exp: 만료 시간
nonce: 카카오 로그인 요청 시 전달받은 임의의 문자열
nickname: 닉네임
picture: 프로필 사진
email: 이메일
nickname, picture, email 값 제공은 동의 항목 설정 및 사용자 동의 필요
자세한 정보는 인가 코드 받기 요청과 토큰 받기 응답 참고
서명(Signature) 카카오 인증 서버에서 kid에 해당하는 공개키로 서명한 값
RS256 방식으로 암호화된 값으로, ID 토큰 유효성 검증 시 서명

ID 토큰은 세 영역의 값을 Base64 인코딩(Encoding) 한 후 온점(.)으로 이어 붙인 하나의 문자열로 생성됩니다. 따라서 온점을 기준으로 각 영역을 분리하고, Base64 디코딩(Decoding)하여 내용을 확인할 수 있습니다. 서명의 경우에는 ID 토큰 유효성 검증을 통해서만 올바른 서명인지 확인할 수 있습니다.

OpenID Connect 표준 규격에 맞춘 사용자 정보 가져오기

OpenID Connect를 활성화한 서비스의 로그인 및 가입 시, 데이터 매핑(Mapping)을 위해 ID 토큰 페이로드에 기본적인 사용자 정보인 닉네임, 프로필 사진, 이메일 값을 제공합니다. 이밖의 기본적인 사용자 정보를 표준 규격을 준수하여 조회하려면 OIDC: 사용자 정보 가져오기 API를 사용합니다.

Step 3. ID 토큰 유효성 검증하기

ID 토큰은 제 3자인 카카오 인증 서버에서 발급하므로, 서비스 보안을 위해 유효한 ID 토큰인지 검증하고 사용해야 합니다. 다음 순서로 ID 토큰을 검증합니다. 페이로드 값 확인 시, 필요에 따라 디버깅 목적으로 제공되는 ID 토큰 정보 보기 API를 사용할 수 있습니다.

  1. ID 토큰의 영역 구분자인 온점(.)을 기준으로 헤더, 페이로드, 서명을 분리
  2. 페이로드를 Base64 방식으로 디코딩
  3. 페이로드의 iss 값이 https://kauth.kakao.com와 일치하는지 확인
  4. 페이로드의 aud 값이 서비스 앱 키와 일치하는지 확인
  5. 페이로드의 exp 값이 현재 UNIX 타임스탬프(Timestamp)보다 큰 값인지 확인(ID 토큰이 만료되지 않았는지 확인)
  6. 페이로드의 nonce 값이 카카오 로그인 요청 시 전달한 값과 일치하는지 확인
  7. 서명 검증

서명 검증은 다음 순서로 진행합니다.

  1. 헤더를 Base64 방식으로 디코딩
  2. OIDC: 공개키 목록 조회하기를 통해 카카오 인증 서버가 서명 시 사용하는 공개키 목록 조회
  3. 공개키 목록에서 헤더의 kid에 해당하는 공개키 값 확인
    • 공개키는 일정 기간 캐싱(Caching)하여 사용할 것을 권장하며, 지나치게 빈번한 요청 시 요청이 차단될 수 있으므로 유의
  4. JWT 서명 검증을 지원하는 라이브러리를 사용해 공개키로 서명 검증
    • 참고: OpenID Foundation, jwt.io
    • 라이브러리를 사용하지 않고 직접 서명 검증 구현 시, RFC7516 규격에 따라 서명 검증 과정 진행 가능

이용 정책

연결된 서비스 관리

사용자는 카카오톡 앱의 [더보기] > [설정] > [개인/보안] > [카카오계정] 또는 카카오계정 페이지의 [계정 이용]의 [연결된 서비스 관리] 메뉴에서 연결된 앱 정보를 확인하거나 연결 끊기를 요청할 수 있습니다. 사용자가 연결된 서비스 관리에서 연결 끊기를 요청한 경우에도 카카오 플랫폼은 서비스 앱과 사용자의 연결을 해제하고 앱 이용 정보를 삭제합니다.

연결된 서비스 관리

사용자가 연결된 서비스 관리에서 서비스 앱과 연결을 끊더라도, 카카오 플랫폼은 서비스 회원 정보에 접근하지 않으므로 서비스 회원 탈퇴 처리되지 않습니다. 따라서 서비스 가입 상태와 카카오 플랫폼에서의 연결 여부가 일치하지 않는 문제가 발생할 수 있습니다. 따라서 연결된 서비스 관리에서의 연결 끊기 요청 사실을 서비스 서버에 전달하는 연결 끊기 알림을 사용할 것을 권장합니다.

연결 끊기 알림을 사용하려면 앱에 연결 끊기 설정 후, 카카오 플랫폼에서 전달하는 콜백에 대한 처리를 서비스 서버에 구현해야 합니다. 연결 끊기 알림이 전달된 경우, 서비스는 카카오 플랫폼을 통해 제공받은 사용자 정보가 회원 정보에 남아 있지 않도록 해당 사용자를 탈퇴 또는 카카오 로그인 연동 해제 처리해야 합니다.

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

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

사용자 정보 주의사항

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

또한 카카오 플랫폼이 제공하는 사용자 정보는 값이 변경되거나 삭제될 수 있습니다. 사용자가 카카오 로그인할 때마다 사용자 정보 가져오기를 요청하여 서비스 회원 정보를 최신 정보로 갱신할 것을 권장합니다.

이메일 사용 시 주의사항

카카오로부터 제공받은 사용자 이메일 사용 시, 이메일과 함께 제공되는 이메일 유효 여부(is_email_valid)와 이메일 인증 여부(is_email_verified) 값으로 유효한 이메일인지 항상 확인해야 합니다. (OIDC: 사용자 정보 가져오기의 경우 email_verified)

이메일 유효 여부 값이 false인 경우 이메일이 유효하지 않은 사용자에 해당하며, 해당 사용자의 이메일은 일부 마스킹(Masking)하여 제공합니다. (예: ka***@kakao.com) 이메일 인증 여부가 false인 경우, 인증되지 않은 이메일이므로 사용자에게 서비스에서 발송한 이메일이 올바르게 전송되지 않을 수 있습니다.

또한 이메일은 사용자 요청에 따라 변경될 수 있으므로, 이메일을 ID로 사용하거나 이메일로 동일 사용자인지 확인하는 방식을 권장하지 않습니다.

사용자 동의 시 정보 제공 가능 여부

사용자 동의 시 정보 제공 가능 여부(${FIELD_NAME}_needs_agreement)는 앱에 사용 설정된 사용자 정보의 개인정보 동의 항목마다 제공되는 응답 필드입니다. 해당 사용자 정보를 서비스에 제공할 수 있는지 알려주는 필드로, 추가 항목 동의 받기 요청 시 참고할 수 있습니다.

  • true: 추가 제공 가능한 사용자 정보
    • 사용자가 카카오에 해당 사용자 정보를 아직 제공하지 않은 경우에도 카카오계정으로 수집 후 제공 설정을 하면 추가 항목 동의 받기를 거쳐 서비스에서 제공받을 수 있음
  • false: 이미 제공되고 있는 사용자 정보, 또는 제공 불가능한 사용자 정보
    • 응답에 해당 사용자 정보 값이 없다면 카카오에서 제공 불가능한 정보
    • 서비스에서 자체 수집하거나 관련 기능을 제공하지 않아야 함
  • 사용자가 카카오계정 정보 수집에 동의하지 않아 카카오도 보유하고 있지 않고, 수집도 불가능한 사용자 정보는 사용자 동의 시 정보 제공 가능 여부 값이 false
    • 추가 항목 동의 받기 기능을 사용해도 카카오로부터 제공받을 수 없음
    • 서비스에 반드시 필요한 동의 항목은 [필수] 동의 단계로 설정해야 함
  • 카카오의 사용자 정보 보유 여부, 앱의 [카카오계정으로 수집 후 제공] 설정 여부에 따라 사용자 동의 시 정보 제공 가능 여부 값이 달라질 수 있음, 아래 표 참고
상태 사용자 정보 보유 사용자 정보 값 미보유
[카카오계정으로 수집 후 제공] 기능 사용 true true
[카카오계정으로 수집 후 제공] 기능 미사용 true false

보안을 위한 파라미터

카카오 로그인은 OAuth 2.0 및 OpenID Connect 표준에 따라 보안을 위한 파라미터인 state, nonce 파라미터를 제공합니다. 사용자가 안전하게 카카오 로그인을 완료할 수 있도록 해당 파라미터 사용을 권장합니다.

stateCross-Site Request Forgery(CSRF) 공격으로부터 카카오 로그인 요청을 보호하기 위해 사용합니다. state는 카카오 로그인이 시작될 때부터 완료될 때까지 고유하고 동일한 값을 유지해야 합니다.

nonceOpenID Connect 사용 시 지원되는 파라미터로, ID 토큰 재생 공격을 방지하기 위해 사용합니다. 카카오 로그인 요청 시 전달된 nonce 값이 ID 토큰에 포함되며, ID 토큰 유효성 검증을 통해 요청 시 전달된 값과 ID 토큰에 포함된 값이 일치하는지 검증해야 합니다.

개인정보 국외이전

개인정보보호법 제39조의12(국외 이전 개인정보의 보호)에 따라, 카카오 API를 통해 제공받은 사용자의 개인정보를 국외에 제공, 처리위탁, 보관하려면 개인정보 국외이전에 관한 아래 사항을 사용자에게 고지한 후 동의를 받아야 합니다.

  1. 이전되는 개인정보 항목
  2. 개인정보가 이전되는 국가, 이전 일시 및 이전 방법
  3. 개인정보를 이전받는 자의 성명(법인인 경우에는 그 명칭 및 정보관리책임자의 연락처)
  4. 개인정보를 이전받는 자의 개인정보 이용목적, 보유 및 이용 기간

개인정보 국외이전에 해당하는 경우는 아래와 같습니다.

  • 국내 사용자 정보를 국외에 있는 사업자로 이전하여 처리하는 경우
  • 국외에 있는 사업자가 국내 사용자 정보를 조회, 저장 등 처리하는 경우

개인정보 국외이전 정보 등록 방법은 설정하기에서 확인할 수 있습니다.

오픈마켓별 소셜 로그인 정책

카카오 로그인을 사용하는 서비스에서 참고해야 할 주요 오픈마켓의 소셜 로그인 정책입니다. 자세한 사항은 각 오픈마켓의 이용 정책을 확인해야 합니다.

iOS

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

지원하는 기능

  • 각 API 및 기능의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.
기능 설명 문서
카카오 로그인 인가 코드 받기 카카오 로그인 동의 화면을 호출하고, 사용자 동의를 거쳐 인가 코드 발급을 요청합니다. REST API
토큰 받기 인가 코드로 액세스 토큰과 리프레시 토큰 발급을 요청합니다. REST API
간편 로그인 Kakao SDK for JavaScript로 제공하는 기능입니다.
인가 코드 받기와 동일한 기능으로, 서비스 웹 페이지에서 인가 코드 발급을 요청하고자 할 때 사용합니다.
JavaScript
카카오톡으로 로그인 Kakao SDK for Android, iOS, Flutter로 제공하는 기능입니다.
카카오톡에 연결된 카카오계정 및 인증 정보를 사용해 카카오 로그인합니다.
Android
iOS
Flutter
카카오계정으로 로그인 Kakao SDK for Android, iOS, Flutter로 제공하는 기능입니다.
기본 브라우저(Default Browser)를 통해 카카오계정 정보를 입력하고 카카오 로그인합니다.
Android
iOS
Flutter
추가 항목 동의 받기 사용자가 첫 카카오 로그인 시 동의 화면에서 동의하지 않았지만, 서비스 이용 중 추가로 동의해야 하는 항목의 동의를 요청합니다. REST API
JavaScript
Android
iOS
Flutter
약관 선택해 동의 받기 앱의 서비스 약관 중 일부만 지정하여 사용자에게 동의 요청합니다. REST API
JavaScript
Android
iOS
Flutter
토큰 할당하기 Kakao SDK for JavaScript로 제공하는 기능입니다.
카카오 API를 호출할 수 있도록 카카오 로그인을 통해 발급받은 토큰을 할당합니다.
JavaScript
토큰 존재 여부 확인하기 Kakao SDK for Android, iOS, Flutter로 제공하는 기능입니다.
카카오 API를 호출할 수 있도록 카카오 로그인을 통해 발급받은 토큰을 할당합니다.
Android
iOS
Flutter
토큰 정보 보기 액세스 토큰의 유효성을 검증하거나 정보를 확인합니다. REST API
Android
iOS
Flutter
토큰 갱신하기 액세스 토큰과 리프레시 토큰을 갱신합니다. REST API
사용자 정보 가져오기 현재 로그인한 사용자의 정보를 불러옵니다. REST API
JavaScript
Android
iOS
Flutter
여러 사용자 정보 가져오기 앱 사용자 여러 명의 정보를 불러옵니다. REST API
사용자 목록 가져오기 앱의 사용자 회원번호 목록을 불러옵니다. REST API
사용자 정보 저장하기 사용자 프로퍼티 값을 저장합니다. REST API
JavaScript
Android
iOS
Flutter
배송지 가져오기 앱 사용자의 배송지 정보를 불러옵니다. REST API
JavaScript
Android
iOS
Flutter
동의 내역 확인하기 사용자가 동의한 동의 항목의 상세 정보 목록을 조회합니다. REST API
JavaScript
Android
iOS
Flutter
동의 철회하기 사용자가 동의한 항목에 대해 동의를 철회합니다. REST API
JavaScript
Android
iOS
Flutter
동의한 약관 확인하기 사용자가 어떤 약관들에 동의하고 로그인했는지 확인합니다. REST API
JavaScript
Android
iOS
Flutter
OpenID Connect OIDC: 메타데이터 확인하기 카카오 로그인의 OpenID Connect 서비스 제공자 설정을 확인합니다. REST API
OIDC: 공개키 목록 조회하기 카카오 인증 서버가 ID 토큰 서명 시 사용한 공개키 목록을 조회합니다. REST API
OIDC: ID 토큰 정보 보기 ID 토큰 유효성 검증을 위한 참고 정보를 제공합니다. REST API
OIDC: 사용자 정보 가져오기 현재 로그인한 사용자의 정보를 불러옵니다. OpenID Connect 표준 규격에 맞춘 사용자 정보 조회가 필요한 경우, 사용자 정보 가져오기 대신 사용합니다. REST API
로그아웃 액세스 토큰과 리프레시 토큰을 모두 만료시킵니다. REST API
JavaScript
Android
iOS
Flutter
카카오계정과 함께 로그아웃 웹 브라우저에 로그인된 카카오계정의 세션을 만료시키고, 서비스에서도 로그아웃 처리할 때 사용하는 로그아웃 추가 기능입니다. REST API
연결 끊기 앱과 사용자 카카오계정의 연결을 끊습니다. REST API
JavaScript
Android
iOS
Flutter
고급: 연결하기 자동 연결을 [사용 안함]으로 설정한 앱에서 앱과 사용자를 수동으로 연결하는 기능 REST API
Android
iOS
Flutter
연결 끊기 알림 사용자가 서비스 외부에서 각 서비스 애플리케이션(이하 앱)과의 연결을 해제할 경우 서비스 서버에 알려줍니다. 콜백 알림 받기
설정하기