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

카카오 로그인

이해하기

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

기능 소개

카카오 로그인은 카카오계정으로 다양한 서비스에 로그인할 수 있도록 하는 OAuth 2.0 기반의 소셜 로그인 서비스입니다.

카카오 로그인 사용 시, 서비스는 서비스 ID 및 비밀번호를 입력받고 검증하는 과정을 직접 구현하지 않고도 사용자에 대한 인증과 인가를 간편하고 안전하게 처리할 수 있습니다. 사용자는 카카오 로그인이 적용된 서비스에 카카오톡 또는 카카오계정 ID와 비밀번호로 손쉽게 로그인할 수 있습니다.

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

참고: OpenID Connect 지원, 로그인 세션 대신 사용 가능한 ID 토큰 제공 가능
인가(Authorization) 사용자 개인정보와 같은 자원(Resource)에 대한 접근 권한 획득
카카오 로그인은 사용자 동의를 통해 사용자 정보나 기능에 대한 접근 권한을 서비스에 부여
서비스에서 부여받은 권한은 카카오 로그인 시 발급되는 토큰에 부여되며, 토큰을 사용해 해당 사용자에 대해 다양한 카카오 API 요청 가능
카카오 API를 통해 카카오 플랫폼에 저장된 사용자 정보를 제공받거나, 특정 기능이나 동작을 요청할 수 있음
OAuth 2.0과 OpenID Connect

OAuth 2.0은 인가를 위한 표준 프로토콜입니다. OpenID Connect는 인증을 위한 OAuth 2.0 확장 표준 프로토콜입니다. 카카오 로그인은 OAuth 2.0과 OpenID Connect 기반으로 인증과 인가를 모두 지원합니다.

서비스는 카카오 플랫폼을 이용하기 위해 서비스 정보를 카카오디벨로퍼스(이하 개발자 웹사이트)에서 애플리케이션(이하 앱)으로 등록해야 합니다. 그리고 앱에 서비스 이용을 위해 필요한 권한을 나타내는 동의 항목을 설정해야 합니다. 카카오 로그인을 통해 사용자는 앱 설정의 동의 항목에 대한 사용자 동의를 거쳐 서비스에 로그인할 수 있습니다.

카카오 로그인 완료 시 토큰이 발급됩니다. 토큰은 사용자를 인증하고 카카오 API 호출 권한을 부여하는 액세스 토큰(Access Token)와 액세스 토큰을 갱신하는 데 쓰는 리프레시 토큰(Refresh Token) 두 가지입니다. OpenID Connect를 사용할 경우, 사용자 인증 정보를 담은 ID 토큰이 함께 발급됩니다.

서비스 가입 시에는 인증과 인가 외에도 이용약관과 같이 사용자 동의가 필요한 사항들이 있습니다. 카카오 로그인의 확장 기능인 비즈니스 솔루션 카카오싱크를 도입하면, 카카오 로그인 시 사용자에게 이용약관 동의와 카카오톡 채널 추가까지 함께 요청할 수 있습니다.

주의: 서비스 회원 정보

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

아래는 서비스 로그인 및 가입 과정 중 카카오 로그인으로 대신할 수 있는 부분을 간략히 표현한 이미지입니다.

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

로그인

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

카카오 로그인은 카카오계정의 사용자 자격정보로 인가 코드를 받아오고, 인가 코드로 액세스 토큰과 리프레시 토큰을 얻는 두 단계로 구성돼 있습니다. 카카오 로그인의 진행 과정을 간략히 표현하면 다음과 같습니다.

카카오 로그인 과정

위 과정을 보다 자세히 설명하면 다음과 같습니다.

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

카카오 로그인이 완료되면 토큰이 발급됩니다. 사용자가 처음으로 해당 서비스에 카카오 로그인한 경우, 서비스의 앱과 사용자의 카카오계정이 서로 연결됩니다. 연결은 사용자의 해당 서비스 이용 상태를 나타내는 것으로, 자세한 설명은 연결과 연결 끊기에서 확인할 수 있습니다.

만약 서비스 앱이나 서버 에러가 아닌 요청 정보 문제로 로그인에 실패한다면 카카오 인증 서버로부터 에러 응답을 받습니다. 이 경우, 문제 해결에서 원인을 찾아 수정할 수 있습니다.

토큰 정보

카카오 로그인을 통해 발급받을 수 있는 토큰은 매번 인증을 거치지 않고도 일정 기간 카카오 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 사용 시에는 필요에 따라 토큰 정보 확인이나 갱신을 위한 요청 필요


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

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

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

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

* 모바일 앱에서 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: 카카오 로그인 요청 시 전달받은 임의의 문자열
자세한 정보는 인가 코드 받기 요청과 토큰 받기 응답 참고
서명(Signature) 카카오 인증 서버에서 kid에 해당하는 공개키로 서명한 값
RS256 방식으로 암호화된 값으로, ID 토큰 유효성 검증 시 서명

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

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 규격에 따라 서명 검증 과정 진행 가능
OpenID Connect 표준 규격에 맞춘 사용자 정보 가져오기

OpenID Connect를 활성화한 서비스의 로그인 및 가입 시, 데이터 매핑(Mapping)을 위해 표준 규격을 준수하여 사용자 정보를 조회해야 할 경우, OIDC: 사용자 정보 가져오기 API를 사용합니다.

사용자 동의

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

카카오 로그인 시 제 3자 정보제공 동의를 받을 항목들을 [내 애플리케이션] > [카카오 로그인] > [동의 항목]에서 설정할 수 있습니다. 동의 항목 설정을 바탕으로 카카오 로그인 시 동의 화면이 구성됩니다. 동의 항목에는 서비스의 필요에 따라 [필수], [선택], [이용 중 동의]와 같은 동의 단계를 개별 설정할 수 있습니다. 자세한 안내는 설정하기를 참고합니다.

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

참고: 추가 항목 동의 받기

사용자가 카카오 로그인 시 동의하지 않은 동의 항목이라도 서비스에서 필요한 시점에 다시 동의 요청할 수 있습니다. 자세한 안내는 추가 항목 동의 받기를 참고합니다.

참고: 이용 중 동의

[이용 중 동의]는 카카오 로그인 및 서비스 가입 시에 사용자 동의가 필요하지 않지만, 서비스 일부 기능 제공 시 사용자 동의가 필요한 경우에 사용하는 동의 단계입니다. 서비스의 특정 기능 제공에 필요한 동의 항목에 대해 추가 항목 동의 받기로 동의받기 위해 사용합니다. 자세한 안내는 설정하기를 참고합니다.

needs_agreement

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

  • true: 추가 제공 가능한 사용자 정보
  • false: 이미 제공되고 있는 사용자 정보, 또는 제공이 불가능한 사용자 정보
    • 값이 false지만 해당 사용자 정보에 값이 없다면 자체 수집하거나 관련 기능을 제공하지 않아야 함
    • 사용자가 아직 해당 정보를 제공하지 않은 경우라면 카카오계정에서 수집 후 제공 설정을 통해 값을 제공받을 수 있음
    • 사용자가 카카오계정 정보 수집에 동의하지 않은 경우에는 값을 제공할 수 없으므로, 해당 사용자 정보가 없는 경우를 서비스에 고려해야 함

카카오계정의 사용자 정보 값 보유 여부, 앱의 [카카오계정에서 수집 후 제공] 설정 여부에 따라 needs_agreement 값이 달라집니다. 아래 표를 참고합니다.

상태 사용자 정보 값 보유 사용자 정보 값 미보유
[카카오계정에서 수집 후 제공] 기능 사용 true true
[카카오계정에서 수집 후 제공] 기능 미사용 true false

사용자 정보

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

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

주의

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

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

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

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

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

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

카카오계정 정보에 포함된 각 항목은 정보 제공을 위해 사용자 동의가 필요한지 알려주는 needs_agreement 값을 포함합니다.

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

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

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

구성: 대표 이메일, 이메일 인증 여부, 이메일 유효 여부, 사용자 동의 시 제공 가능 여부
비고: 이메일 사용 시 주의사항
카카오계정(이메일)
Permission
연령대 카카오계정의 연령대, 한국 나이 기준

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

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

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

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

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

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

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

참고: 이메일 사용 시 주의사항

카카오로부터 제공받은 사용자 이메일 사용 시, 이메일과 함께 제공되는 이메일 유효 여부(is_email_valid)와 이메일 인증 여부(is_email_verified) 값으로 유효한 이메일인지 항상 확인해야 합니다.(OIDC: 사용자 정보 가져오기의 경우 email_verified) 이메일 유효 여부 값이 false인 경우 이메일이 유효하지 않은 사용자에 해당하며, 해당 사용자의 이메일은 일부 마스킹(Masking)하여 제공합니다. (예: ka***@kakao.com) 이메일 인증 여부가 false인 경우, 인증되지 않은 이메일이므로 사용자에게 서비스에서 발송한 이메일이 올바르게 전송되지 않을 수 있습니다. 또한 이메일은 사용자 요청에 따라 변경될 수 있으므로, 이메일을 ID로 사용하거나 이메일로 동일 사용자인지 확인하는 방식을 권장하지 않습니다.

다른 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 심사 지침에서 확인할 수 있습니다.

추가 항목 동의 받기

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

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

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

사용자가 아직 동의하지 않은 동의 항목의 키를 scope 파라미터에 명시하여 추가 항목 동의 받기를 요청할 수 있습니다. 자세한 사용 방법은 아래 단계별 안내를 참고합니다.

참고: scope 파라미터

OpenID Connect를 통해 발급받은 ID 토큰을 사용할 경우, 추가 항목 동의 받기 요청 시 scope 파라미터 사용에 유의해야 합니다. 카카오 로그인은 scope 파라미터 사용 여부에 따라 다르게 동작하기 때문입니다. 아래 내용을 참고합니다.

요청 구분 카카오 로그인 동작 ID 토큰 발급 여부
scope 파라미터 미포함 카카오 인증 서버가 서비스 대신 scope 파라미터 값을 앱의 동의 항목 설정에 따라 지정함
앱에 [필수] 또는 [선택]으로 설정된 동의 항목으로 구성된 동의 화면 출력
ID 토큰 발급
카카오 인증 서버가 앱의 OpenID Connect 활성화 설정을 확인하고, 활성화 상태인 경우 scopeopenid를 포함하여 요청 처리*
scope 파라미터 포함
(추가 항목 동의 받기)
특정 동의 항목에 대한 추가 항목 동의 받기 요청 시, 서비스에서 scope 파라미터 값에 필요한 동의 항목의 키를 직접 명시해야 함
지정된 동의 항목만으로 구성된 동의 화면 출력
scope 파라미터 값에 openid가 포함되지 않은 경우, ID 토큰 발급되지 않음*
OpenID Connect 사용 시, scope 파라미터를 사용해 추가 항목 동의 받기를 요청하려면 서비스에서 직접 scopeopenid를 포함하여 요청해야 함

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

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

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

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

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

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

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

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

{
  "id": 1633204891,
  "connected_at": "2021-02-18T06:13:55Z",
  "properties": {
    "${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}",
    ...
  },
  "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를 사용합니다.

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

주의: OpenID Connect

OpenID Connect를 사용하는 앱의 경우, 추가 항목 동의 받기 요청 시 동의 항목 키를 전달하는 scope 파라미터 값에 openid를 반드시 포함해야 합니다. 해당 파라미터 값을 포함하지 않을 경우, 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 및 기능의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.
API 및 기능 설명
로그인 카카오계정과 애플리케이션(이하 앱)을 연결하고 토큰을 발급받아 카카오 API를 사용할 수 있도록 하는 기능입니다.
카카오 로그인은 인가 코드 받기와 토큰 받기의 두 단계로 이뤄집니다.
인가 코드 받기: 카카오 로그인 동의 화면을 호출하고, 사용자 동의를 거쳐 인가 코드 발급을 요청합니다.
토큰 받기: 인가 코드로 액세스 토큰과 리프레시 토큰 발급을 요청합니다.
토큰 정보 보기 액세스 토큰의 유효성을 검증하거나 정보를 확인합니다.
토큰 갱신하기 액세스 토큰과 리프레시 토큰을 갱신합니다.
로그아웃 액세스 토큰과 리프레시 토큰을 모두 만료시킵니다.
연결 끊기 앱과 사용자 카카오계정의 연결을 끊습니다.
사용자 정보 가져오기 현재 로그인한 사용자의 정보를 불러옵니다.
사용자 정보 저장하기 사용자 프로퍼티 값을 저장합니다.
사용자 목록 가져오기 앱의 사용자 회원번호 목록을 불러옵니다.
여러 사용자 정보 가져오기 앱 사용자 여러 명의 정보를 불러옵니다.
추가 항목 동의 받기 사용자가 첫 카카오 로그인 시 동의 화면에서 동의하지 않았지만, 서비스 이용 중 추가로 동의해야 하는 항목의 동의를 요청합니다.
동의 내역 확인하기 사용자가 동의한 동의 항목의 상세 정보 목록을 조회합니다.
동의 철회하기 사용자가 동의한 항목에 대해 동의를 철회합니다.
OIDC: 메타데이터 확인하기 카카오 로그인의 OpenID Connect 서비스 제공자 설정을 확인합니다.
OIDC: 사용자 정보 가져오기 현재 로그인한 사용자의 정보를 불러옵니다. OpenID Connect 표준 규격에 맞춘 사용자 정보 조회가 필요한 경우, 사용자 정보 가져오기 대신 사용합니다.
OIDC: 공개키 목록 조회하기 카카오 인증 서버가 ID 토큰 서명 시 사용한 공개키 목록을 조회합니다.
OIDC: ID 토큰 정보 보기 ID 토큰 유효성 검증을 위한 참고 정보를 제공합니다.
연결하기 자동 연결을 [사용 안함]으로 설정한 앱에서 앱과 사용자를 수동으로 연결하는 기능
연결 끊기 알림 받기 사용자가 서비스 외부에서 각 서비스 애플리케이션(이하 앱)과의 연결을 해제할 경우 서비스 서버에 알려줍니다.