이해하기

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

기능 소개

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

카카오 로그인

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

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

참고: 토큰

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

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

카카오싱크

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

서비스 로그인 과정

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

1. 사용자가 서비스에서 카카오 로그인 버튼을 클릭합니다. 서비스는 카카오 인증 서버로 인가 코드 발급을 요청합니다.
2. 카카오 인증 서버는 사용자에게 인증을 요청합니다. (참고: 사용자 환경에 따른 인증 방법)
   • 카카오톡으로 로그인: 카카오톡 실행, 카카오톡에 연결된 카카오계정의 자격정보(Credentials)로 사용자 인증
   • 카카오계정으로 로그인: 계정 정보를 입력해 로그인하는 화면 출력, 해당 카카오계정의 자격정보로 사용자 인증
3. 카카오 인증 서버는 사용자 인증 성공 시, 서비스 앱의 동의항목 설정을 바탕으로 사용자에게 동의 화면을 출력합니다.
4. 사용자가 필수 동의항목에 동의하고 로그인을 요청하면, 카카오 인증 서버는 인가 코드(Authorization Code)를 발급해 서비스 앱에 등록된 Redirect URI로 전달합니다.
5. 서비스는 전달받은 인가 코드로 토큰을 요청하여 받습니다.

1. 서비스는 카카오 로그인을 완료하여 발급받은 토큰으로 사용자 정보 가져오기를 요청합니다.
   • OpenID Connect 사용 시: OIDC: 사용자 정보 가져오기 API로 대체 가능
2. 카카오 API 서버는 요청 시 사용된 토큰의 유효성을 검증하고, 요청을 처리하고 서비스에 응답합니다.
3. 서비스 서버는 카카오로부터 제공받은 사용자 정보로 해당 사용자가 서비스에 회원 가입되어 있는지 확인합니다.
   • 이미 회원 가입된 사용자: Step 3의 서비스 로그인 단계 수행
   • 아직 회원 가입되지 않은 사용자: 카카오에서 제공받은 사용자 정보로 서비스 데이터베이스에 회원 가입 처리

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

도입 안내

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

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

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

필수 사용자 정보와 선택 사용자 정보

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

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

• 필수 설정: 플랫폼 등록, 카카오 로그인 활성화, Redirect URI 등록, 동의항목
• 선택 설정: OpenID Connect 활성화, 카카오톡 채널 연결, Logout Redirect URI

• REST API
• JavaScript
• Android
• iOS
• Flutter

인증

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

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

사용자 환경별 인증 방법

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

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

카카오톡에서 자동 로그인

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

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

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

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

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

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

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

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

로그인 힌트 주기

카카오 로그인 요청 시 전달된 ID 값을 카카오계정 로그인 페이지의 ID란에 자동 입력해 주는 기능입니다. 이 기능은 기존에 카카오 로그인한 사용자가 보다 쉽게 재로그인할 수 있도록 지원하는 용도로 사용할 수 있습니다. 카카오 로그인 시 login_hint 또는 loginHint 파라미터를 사용해 로그인 힌트 주기를 요청할 수 있습니다.

참고: 로그인 힌트 주기 상세 동작 과정

로그인 힌트 주기는 사용자 환경, 카카오계정 로그인 상태에 따라 동작이 달라질 수 있습니다. 아래 이미지를 참고합니다.

로그인 힌트 주기는 REST API, JavaScript SDK를 사용해 요청할 경우 prompt 파라미터와 함께 사용 가능합니다. prompt 파라미터를 사용한 경우의 동작은 아래 이미지를 참고합니다.

카카오계정 간편로그인

카카오계정 간편로그인은 브라우저에 카카오계정 간편로그인 정보가 있을 경우 계정 선택 화면을 출력하는 기능입니다. 카카오 로그인 시 prompt 파라미터 값을 select_account로 지정해 사용합니다.

사용자는 카카오계정 로그인 페이지에서 [간편로그인 정보 저장]을 눌러 간편로그인 정보를 저장할 수 있습니다. 사용자의 간편로그인 정보가 저장된 브라우저에서 카카오 로그인 요청 시 계정 선택 화면이 출력됩니다. 사용자는 ID, 비밀번호 입력 없이 선택한 계정으로 로그인할 수 있습니다.

인가

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

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

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

참고: 동의 철회

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

동의항목

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

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

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

참고: 동의 단계

참고: scope 파라미터

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

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

추가 항목 동의 받기

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

HTTP/1.1 200 OK
{
    ...
    "kakao_account": {
        ...
        "email_needs_agreement": true    // 이메일 동의항목에 사용자 동의 필요
        ...
    }
}

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"
  ]
}

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":5184000,
    "scope":"account_email profile"     // 사용자가 동의한 동의항목 정보
}

연결

연결은 카카오계정의 서비스 이용 상태를 의미합니다. 카카오 플랫폼은 서비스의 회원 정보를 알 수 없으므로, 서비스의 앱과 사용자의 연결 여부로 사용자가 해당 서비스를 이용하고 있는지 확인합니다. 카카오 플랫폼에서 카카오 로그인이 필요한 기능사용자 정보 가져오기, 친구 목록 가져오기, 특정 사용자간 카카오톡 메시지 전송 등은 사용자가 앱과 연결된 상태여야 사용할 수 있습니다.

사용자가 서비스를 더 이상 이용하지 않아 탈퇴 처리하거나 카카오 로그인 연동을 해제할 경우, 서비스는 앱과 사용자의 연결을 끊어야 합니다. 서비스는 연결 끊기를 요청해 서비스의 앱과 사용자의 연결을 끊을 수 있습니다. 카카오 플랫폼은 연결 끊기 요청을 받으면 사용자가 서비스 이용을 위해 동의했던 동의항목의 동의를 철회하고 로그아웃시킵니다. 또한 사용자의 서비스 앱 이용 정보를 모두 삭제합니다.

연결과 서비스 가입

카카오 플랫폼은 사용자가 서비스에 처음 카카오 로그인할 때 앱과 사용자를 연결합니다. 다음은 카카오 로그인 및 서비스 가입 과정을 요약한 이미지입니다.

연결은 카카오 플랫폼이 내부적으로 수행합니다. 카카오 플랫폼은 ➎ 토큰 발급 시점에 ➏ 사용자와 앱을 연결합니다.

가입은 서비스가 직접 수행해야 합니다. 서비스는 ➎ 토큰 요청 및 발급을 통해 카카오 로그인을 완료한 후, ➐ 가입 및 로그인 처리를 해야 합니다. 카카오 로그인한 사용자의 사용자 정보로 해당 사용자의 가입 여부를 확인하고, 미가입 사용자인 경우 서비스 약관 동의와 추가 정보 입력 절차를 거쳐 서비스 회원 데이터 베이스에 가입 처리합니다. (참고: 가입 미완료 사용자 처리 안내)

연결 끊기와 서비스 탈퇴

서비스는 카카오 로그인 사용자의 서비스 탈퇴 과정에 연결 끊기를 포함해야 합니다. 다음은 카카오 로그인 사용자의 탈퇴 과정을 요약한 이미지입니다.

서비스는 ➊ 카카오 로그인을 통해 서비스를 이용 중이던 사용자가 탈퇴 또는 카카오 로그인 연동 해제를 요청하면 ➋ 해당 사용자에 대해 연결 끊기를 요청합니다. 카카오 플랫폼은 ➌ 사용자와 앱의 연결을 해제하고 로그아웃 처리합니다. 서비스는 연결 끊기 요청 성공 시 ➎ 해당 사용자를 탈퇴 또는 카카오 로그인 연동 해제 처리합니다.

사용자 정보

서비스는 카카오 로그인 후 사용자 정보 가져오기를 요청해 필요한 사용자 정보를 제공받을 수 있습니다.

참고: 카카오 플랫폼이 제공하는 모든 사용자 정보 목록

개인정보 동의항목에서 모든 사용자 정보의 종류와 각 사용자 정보를 제공하는 카카오 API의 목록을 확인할 수 있습니다. 카카오 플랫폼은 대부분의 사용자 정보를 사용자 정보 가져오기를 통해 제공합니다. 이밖에도 서비스는 카카오 로그인 시 동의항목 설정에 따라 여러 카카오 서비스의 사용자 정보를 제공받을 수 있습니다. 주민등록번호, 여권번호, 의류 사이즈 등 정보는 카카오 플랫폼에서 제공하지 않으므로 서비스가 직접 사용자로부터 수집해야 합니다.

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

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

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

참고: 사용자 프로퍼티

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

기본 정보

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

카카오계정 정보

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

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

²⁾ 개인정보 동의항목 권한 보유 시 [선택] 또는 [필수] 동의 단계 설정 가능

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

참고: 프로필

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

배송지

카카오 로그인한 사용자의 카카오계정에 등록된 배송지 정보를 제공합니다. 배송지는 Kakao SDK 또는 REST API로 요청 가능하며, Kakao SDK를 사용하면 더욱 편리하게 배송지 활용 기능을 구현할 수 있습니다.

이용 안내

배송지를 제공받으려면 아래 조건을 만족해야 합니다.

• 앱에 [배송지 정보] 동의항목 설정
  • [배송지 정보]는 앱 권한 신청을 통해 권한을 받아야 설정 가능
• 사용자가 카카오 로그인 시 [배송지 정보] 동의항목에 동의
  • 사용자가 [배송지 정보] 동의항목에 동의하지 않은 경우의 동작은 사용자 동의 참고

Kakao SDK 사용 시, 아래 순서로 배송지를 요청합니다.

1. 배송지 선택하기로 사용자가 선택한 배송지의 ID를 받습니다.
2. 배송지 가져오기로 ID에 해당하는 배송지의 상세 정보를 받습니다.

아래 시퀀스 다이어그램을 참고합니다.

1. 사용자가 서비스 페이지에서 배송지 선택 버튼을 누릅니다.
2. 서비스가 배송지 선택하기 API를 호출합니다.
3. 사용자에게 배송지 피커가 출력됩니다.
4. 사용자 카카오계정에 등록된 배송지의 유무에 따라, 사용자가 다음 중 한 가지 방법으로 배송지를 선택합니다.
   • 등록된 배송지 없음: 배송지 수집에 동의하고 새로운 배송지 입력, 새로 입력한 배송지가 자동 선택됨
   • 등록된 배송지 있음: 서비스에 제공할 배송지 직접 선택
5. 서비스에 배송지 선택하기의 응답으로 선택된 배송지의 ID가 반환됩니다.
6. 서비스가 배송지 ID로 배송지 가져오기 API를 요청합니다.
7. 서비스에 배송지 가져오기의 응답으로 해당 배송지 상세 정보가 반환됩니다.
8. 서비스는 배송지 상세 정보를 서비스 페이지에 출력합니다.

위 과정을 수행하는 동안, 사용자 카카오계정의 상태나 동작 등으로 인한 에러가 반환될 수 있습니다. 문제 해결을 참고해 예외 처리 및 재요청합니다.

참고: 전체 배송지 목록

배송지 가져오기 요청 시 배송지 ID를 지정하지 않으면 사용자의 전체 배송지를 제공받을 수 있습니다. 이 경우, 응답으로 받은 여러 배송지를 서비스 UI에 목록 형태로 출력하고 사용자가 선택할 수 있도록 하는 기능 구현이 필요합니다.

서비스 회원 연동

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

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

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

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

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

유형별 연동 안내

사용자 정보 일치

• 카카오 로그인 사용자 정보가 서비스의 기존 회원 확인 조건을 만족한 경우
  • 예: 이메일과 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를 사용하는 앱에서 카카오 로그인을 구현하는 과정은 다음 순서로 진행되어야 합니다.

보안 이벤트 구독

카카오 로그인은 보안 이벤트 구독 기능을 제공합니다. 보안 이벤트 구독 기능을 사용하면 앱 연결 및 해제, 비밀번호 변경, 비활성화와 같은 사용자의 보안 이벤트 정보를 제공받을 수 있어, 서비스에서 보다 적극적인 보안 조치를 취할 수 있습니다.

이용 정책

연결된 서비스 관리

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

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

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

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

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
  • 추가 항목 동의 받기 기능을 사용해도 카카오로부터 제공받을 수 없음
  • 서비스에 반드시 필요한 동의항목은 [필수] 동의 단계로 설정해야 함
• 카카오의 사용자 정보 보유 여부, 앱의 [카카오계정으로 수집 후 제공] 설정 여부에 따라 사용자 동의 시 정보 제공 가능 여부 값이 달라질 수 있음, 아래 표 참고

보안을 위한 파라미터

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

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

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

개인정보 국외이전

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

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

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

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

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

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

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

iOS

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

지원하는 기능

• 각 API 및 기능의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.