이 문서는 카카오 또는 공동체 서비스용 카카오 로그인과 관련 API를 소개합니다. 공통 설명은 오픈 문서를 참고합니다.

• 카카오 로그인 이해하기: 카카오 로그인 관련 핵심 내용 안내
• 카카오 로그인 활용하기: 카카오 로그인 관련 주요 추가 정보 안내

• 기능 소개
  • 카카오 로그인
  • 카카오싱크

인하우스 앱은 카카오 로그인 시 동의 화면 출력 및 사용자 동의 과정을 생략합니다. 단, 동의 화면이 출력되지 않더라도 사용자 정보 및 기능 제공을 위해 동의항목 설정이 필요합니다. 인하우스 앱에 설정된 동의항목에 대한 사용자 동의는 아래와 같이 처리됩니다.

• 연결(첫 카카오 로그인) 시
  • [필수 동의], [선택 동의] 동의항목에 대해 자동 동의 처리
  • 카카오계정에 수집되지 않은 정보도 자동으로 동의 처리되지만, 사용자가 해당 정보를 계정에 등록해야 사용자 정보 조회 API 응답에 포함됨
• 연결 이후
  • 앱에 추가로 설정했거나 앱과 최초 연결 시 동의받지 못해 미동의 상태인 동의항목이 있는 경우, 자동 동의 처리
  • 기존에 연결된 사용자에게 미동의 동의항목이 있는 경우, 카카오계정에 정보가 등록되어도 사용자의 인증 요청 전까지는 동의 처리되지 않음

카카오 통합 서비스 약관을 벗어나는 목적으로 개인정보 수집 및 이용이 필요한 경우 아래 절차로 사용자 동의를 받을 수 있습니다.

1. 개인정보보호 아지트에서 수집하고자 하는 개인정보 및 목적에 대한 검토 요청 및 승인 완료
2. [서비스] API플랫폼 아지트로 승인 내역과 함께 내용 전달
3. API플랫폼 내부 처리 후, [개인정보 수집 및 이용 동의] 항목으로 동의 화면에서 사용자 동의 가능

인하우스 앱이라도 카카오계정 직접 연동과 같이 카카오 로그인이 아닌 사용자 인증 방식을 사용한다면 아래 기능을 직접 구현해야 합니다.

• 카카오계정으로 정보 수집 후 제공 기능
• 카카오계정 제재 상태 확인
• 카카오계정 통합서비스 약관 동의 여부 확인 및 통합서비스약관 동의

• 도입 안내
  • 1. 서비스 요구 사항 확인
  • 2. 앱 생성과 설정
  • 3. 연동 개발

• 로그인
  • 로그인 과정
  • 인증
  • 인가
  • 토큰
  • 추가 기능
    • 카카오계정 간편로그인
    • 카카오톡에서 자동 로그인
    • 기존 로그인 여부와 상관없이 로그인
    • 카카오계정 가입 후 로그인
    • 동의항목 추가 동의 요청
    • 로그인 힌트
    • 간편가입
    • 서비스 약관 선택해 동의 요청
    • OpenID Connect ID 토큰 발급

• 연결
  • 기존 회원 여부 확인
  • 회원 등록
  • 회원 탈퇴
  • 연결 해제

카카오 또는 공동체 서비스 사용자의 앱 연결 상태는 아래 세 종류로 구분됩니다.

• 지원 범위
• 사용자 연결 상태에 따른 정보 제공 제한

연결된 서비스 관리의 기능과 화면 설명은 연결된 서비스 관리에서 확인할 수 있습니다. 연결된 서비스 관리의 [카카오 서비스], [제휴 서비스], [외부 서비스] 분류 기준은 아래를 참고합니다.

자동 연결 기능을 사용하지 않도록 설정한 서비스에서 원하는 시점에 사용자와 앱을 수동으로 연결하는 기능입니다. 개발 문서는 수동 연결 API에서 확인할 수 있습니다.

인하우스 앱, 또는 공동체 앱은 별도 권한 신청 없이 수동 연결 설정을 사용할 수 있습니다. 설정 방법은 로그인 시 앱 자동 연결을 참고합니다.

수동 연결을 사용하는 서비스는 사용자의 서비스 가입 상태와 앱 연결 상태가 서로 일치하는지 확인하고 직접 수동 연결, 연결 해제 API로 연결 상태를 관리해야 합니다. 불가피한 경우가 아니라면 기본 설정인 자동 연결 사용을 권장합니다.

• 사용자가 카카오 로그인을 완료해도 바로 서비스 가입이 완료되지 않는 경우
  • 서비스 가입에 정보 입력이나 인증과 같은 추가 가입 절차 필요
  • 서비스 가입을 일정 주기로 승인
• 서비스 가입 상태와 카카오디벨로퍼스 앱 연결 상태를 동일하게 관리하고 싶은 경우
  • 사용자 로그인 수단으로 카카오 로그인만 도입해 사용 중인 서비스
• 이 외, 서비스에서 사용자의 앱 연결 상태를 직접 관리해야 할 필요가 있는 경우

수동 연결 사용 여부에 따라 카카오계정 웹사이트의 [계정 이용] 또는 카카오톡의 [설정] > [개인/보안]의 [연결된 서비스 관리]에 앱이 노출되는 시점이 다릅니다. 아래 내용을 참고합니다.

• 자동 연결 설정: 사용자가 카카오 로그인으로 사용자 동의 및 토큰 발급을 완료했을 때
• 수동 연결 설정: 서비스가 사용자의 가입 절차를 모두 완료한 뒤 수동 연결 API로 연결 완료했을 때

아래는 사용자 탈퇴 또는 연결 해제 시 필요한 조치입니다.

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

• 동의항목
  • 동의 단계
  • 사용자 동의
  • 카카오계정으로 수집 후 제공
  • 동의 철회

인하우스 앱도 동의항목을 설정해야 합니다. 인하우스 앱은 비공개 동의항목, 별도 권한이 필요한 일부 동의항목을 제외한 모든 동의항목을 사용할 수 있습니다.

인하우스 앱의 동의항목은 서비스에 반드시 필요한 항목만 설정해야 합니다. 각 동의항목의 동의 단계는 [필수 동의]로 설정합니다.

카카오 및 공동체 서비스에는 오픈 API보다 다양한 개인정보 동의항목을 제공합니다. 오픈 API에 제공하는 개인정보 동의항목은 개인정보 동의항목에서 확인할 수 있습니다.

• 개인정보 동의항목은 모두 필수 동의 설정이 가능하지만, 일부 동의항목은 필수 설정을 위한 권한이 필요합니다.

Deprecated

: 신규 앱에는 더 이상 제공하지 않는 동의항목

카카오 및 공동체 서비스에는 오픈 API보다 다양한 접근권한 동의항목을 제공합니다. 오픈 API에 제공하는 접근권한 동의항목은 접근권한 동의항목에서 확인할 수 있습니다.

* 추가 권한 보유 시에만 제공, 이용 정책 참고

• 사용자 정보
  • 기본 제공 정보
  • 사용자 동의 필요 정보

• 배송지 피커

카카오 또는 공동체 서비스에 제공하는 피커 기능에 대한 안내는 피커에서 확인할 수 있습니다.

카카오 로그인을 사용하는 카카오 서비스는 연령인증 기능을 사용할 수 있습니다. 공동체 서비스는 연령인증 기능을 사용할 수 없습니다.

연령인증 정보는 사용자의 카카오계정에 저장되고, 카카오 서비스는 카카오계정에 저장된 연령인증 정보를 활용할 수 있습니다. 사용자 카카오계정에 저장된 연령인증 정보가 없거나 서비스의 연령인증 조건을 만족하지 않아 연령인증이 필요한 경우, 인하우스 앱: 연령인증 페이지 호출로 연령인증을 요청할 수 있습니다. (예: 사용자 연령인증 정보 초기화, 서비스의 연령제한 변경)

• 서비스 전체에 연령제한이 있는 경우로 사용자는 앱 연결 시 연령인증을 필수로 해야 합니다.
• 카카오 로그인 시, 앱에 설정된 연령인증 조건에 맞지 않으면 연령인증 페이지가 출력되고, 연령인증이 정상적으로 완료되면 가입 처리를 해야 합니다.
• 앱에 제한 연령 설정을 하려면 수동 연결을 설정하고, 가입 처리 시 직접 수동 연결 API를 호출해 사용자와 앱을 연결해야 합니다.
• 이 방식을 사용하는 앱은 제한 연령에 맞는 사용자만 연결할 수 있습니다. 연령인증을 완료하지 않은 사용자를 대상으로 수동 연결 API 요청 시, RequiredAgeVerificationException 에러가 발생합니다.

• 사용자가 앱 연결 시 연령인증을 필수로 거쳐야 하지 않지만, 서비스 전체에 연령제한이 있는 경우로써 연령인증이 필요한 서비스 콘텐츠 접근 시 연령인증을 해야 합니다.
• 서비스는 사용자가 연령인증이 필요한 서비스 콘텐츠에 접근했을 때 인하우스 앱: 연령인증 정보 조회 API로 해당 사용자의 연령인증 정보를 확인합니다.
  • 확인 결과, 사용자 카카오계정에 저장된 연령인증 정보가 없거나 서비스의 연령인증 조건을 만족하지 않아 연령인증이 필요한 경우 인하우스 앱: 연령인증 페이지 호출을 요청합니다.
  • 사용자의 연령인증 정보를 확인해 연령인증 필요 여부를 판단하지 않고 연령인증 페이지를 호출할 경우, 사용자가 매번 새로 연령인증을 받게 되므로 주의합니다.
• A. 강제 연령인증 방식과 달리 카카오 로그인 시 연령인증을 수행하지 않고, 필요 시점에 요청할 것이므로 연령인증에 lazy 설정을 해야 합니다.
• 앱에 제한 연령 설정을 하려면 수동 연결을 설정하고, 가입 처리 시 직접 수동 연결 API를 호출해 사용자와 앱을 연결해야 합니다.

• 서비스 전체에 연령제한이 있지 않고, 일부 콘텐츠에만 연령제한을 적용하는 경우입니다.
• 서비스는 연령인증이 필요할 때 인하우스 앱: 연령인증 정보 조회 API로 해당 사용자의 연령인증 정보를 확인하고, 연령인증이 필요할 경우 인하우스 앱: 연령인증 페이지 호출 API로 사용자에게 연령인증을 요청합니다.
• 사용자의 연령인증 정보를 확인해 연령인증 필요 여부를 판단하지 않고 연령인증 페이지를 호출할 경우, 사용자가 매번 새로 연령인증을 받게 되므로 주의합니다.

앱에 설정된 연령인증 방식에 따라 아래와 같이 확인할 수 있습니다.

• A. 강제 연령인증
  • 서비스에서 수동 연결 API 호출 시, 카카오 API 플랫폼이 연령인증 조건 충족 여부를 확인합니다. 사용자의 연령인증 정보가 초기화되었거나 서비스의 연령인증 조건을 만족하지 않으면 에러를 반환합니다.
• B. 필요 시 연령인증
  • 서비스에서 인하우스 앱: 연령인증 정보 조회를 호출해 사용자의 연령인증 정보를 자체적으로 확인합니다.
• C. 앱 설정 없음
  • 서비스에서 인하우스 앱: 연령인증 정보 조회를 호출해 사용자의 연령인증 정보를 자체적으로 확인합니다.
  • 이밖에 서비스 특성에 맞는 조건들로 연령인증 조건 만족 여부를 자체적으로 판단해야 합니다.

서비스에서 필요한 상황이거나 연령인증 조건 만족 기준을 만족하지 않아 에러가 발생한 경우 인하우스 앱: 연령인증 페이지 호출를 사용해 연령인증을 수행합니다. 아래 내용을 참고합니다.

앱에 설정된 연령인증 방식에 따라 연령인증 여부가 다릅니다. 앱에 연령인증 설정이 없거나 필요 시 연령인증 설정이 있을 때는 서비스 가입을 위해 연령인증 페이지를 호출할 필요가 없습니다. 필요 시 서비스는 연령인증 정보 조회로 연령인증 정보 확인 후 연령인증을 요청할 수 있습니다.

하지만 앱에 A. 강제 연령인증 방식(eager)이 적용되어 있다면, 서비스 가입을 위해 연령인증 페이지 호출이 반드시 필요할 수 있습니다. A. 강제 연령인증 방식을 사용하는 서비스에서 가입 시 연령인증 페이지를 호출해야 하는 경우는 아래와 같습니다.

1. 사용자가 카카오 로그인 동의 화면에서 앱에 설정된 제한 연령 이상임을 확인
   • 인하우스 앱의 경우, 동의 화면이 출력되지 않으므로 제한 연령이 노출되지 않음
2. 사용자 정보 조회 API 응답의 연결 여부(has_signed_up) 필드 값이 false라면 수동 연결 API 호출
   • A. 강제 연령인증 방식의 경우, 수동 연결 설정을 사용하므로 가입 처리 시 사용자 정보 조회 API를 호출해 가입에 필요한 정보와 연결 여부 확인 필요
3. 수동 연결 API 호출 시, 사용자의 연령인증 정보가 연령인증 조건 만족 기준을 만족하지 않으면 에러가 반환되며, 해당 에러가 -405 RequiredAgeVerificationException인 경우 연령인증 페이지 호출

사용자가 서비스에 가입해 앱과 연결된 후에도 서비스의 필요에 따라 연령인증 페이지를 다시 호출할 수 있습니다. 또한 연령인증이 필요한 사용자일 경우 RequiredAgeVerificationException 에러를 반환해 서비스에서 연령인증 페이지 호출을 요청하도록 안내합니다. 아래 내용을 참고합니다.

1. 앱에 설정된 연령인증 방식에 따라 아래와 같이 연령인증 정보를 확인합니다.
   • A. 강제 연령인증 방식: 서비스에서 API 호출 시RequiredAgeVerificationException 에러가 발생할 경우 사용자 연령인증이 필요합니다.
   • B. 필요 시 연령인증: 카카오 로그인 및 수동 연결에 연령인증이 영향을 미치지 않습니다. 사용자가 연령인증이 필요한 콘텐츠에 접근했을 때 연령인증 정보 조회로 서비스의 연령인증 조건 만족 기준을 만족하는지 확인합니다.
   • C. 앱 설정 없음: 앱에 연령인증 설정이 없는 경우, 사용자가 연령인증이 필요한 콘텐츠에 접근했을 때 연령인증 정보 조회로 서비스의 연령인증 조건 만족 기준을 만족하는지 확인합니다.
2. 사용자의 연령인증 정보가 서비스의 연령인증 조건 충족 기준을 만족하지 않거나 RequiredAgeVerificationException 에러가 발생해 연령인증이 필요한 경우, 서비스에서 연령인증 페이지를 호출합니다.

• 인하우스 앱: 카카오톡 친구 목록 조회 요청 시 나이(age)를 정렬 기준으로 할 경우, 이미 연령인증을 받았고 앱의 제한 연령에 맞지 않는 친구는 결과에서 제외됩니다.

• OpenID Connect
  • ID 토큰

카카오 로그인을 적용한 인하우스 또는 공동체 서비스에서는 아래의 웹훅을 사용할 수 있습니다.

• 연결 해제 웹훅: 사용자 카카오계정과 서비스 앱의 연결이 끊어졌을 때, 해당 사용자를 탈퇴 처리할 수 있도록 관련 정보를 서비스로 전달
• 로그아웃 웹훅: 서비스 외부에서 사용자의 로그아웃 요청 또는 기타 이유로 로그아웃이 발생한 경우, 관련 정보를 서비스로 전달
• 계정 상태 변경 웹훅: 앱 연결 및 해제, 비밀번호 변경, 비활성화와 같이 사용자의 계정 상태가 변경된 경우, 관련 정보를 서비스로 전달

• 보안
  • 클라이언트 시크릿
  • 보안을 위한 파라미터

SSO(Single Sign On)는 카카오톡에 이미 로그인된 세션을 활용하여, 별도의 앱 전환이나 UI 노출 없이 사용자를 서비스에 로그인시킬 수 있는 기능입니다. SSO를 적용하면 서비스의 로그인 사용자 비율을 높일 수 있습니다.

서비스에서 직접 사용자가 로그인할 계정을 선택하는 화면을 개발해 사용할 수 있습니다. 추후 Partner SDK에서 SSO 로그인 팝업 화면도 지원할 예정입니다.

• 사용 권한이 부여된 인하우스 앱만 이용할 수 있습니다. 사용 방법을 참고합니다.
• SSO 기능은 카카오 통합서비스약관에 동의한 통합계정 사용자만 이용할 수 있습니다.

SSO 동작 방식은 아래와 같습니다.

1. 카카오톡에 로그인된 사용자가 SSO 기능이 적용된 앱을 실행하면, 사용자에게 토큰이 발급되고, 이 중 리프레시 토큰을 SSO 세션으로 사용합니다.
2. SSO 세션 정보는 OS 저장소(Android: AccountManager, iOS: 키 체인)에 안전하게 저장하며, 카카오톡으로부터 전달 받은 카카오톡 프로필, DisplayID와 같은 사용자 정보도 함께 보관됩니다.
3. 사용자가 카카오톡에 로그인된 상태로 서비스에 진입하면 카카오톡에 저장된 로그인 세션(리프레시 토큰)을 이용해 자동 로그인됩니다.
   • OS 저장소에 저장된 SSO 세션 토큰이 삭제돼도, 카카오톡이나 SSO 연동된 서비스 앱은 로그아웃되지 않습니다.
   • 현재 기기에 저장된 카카오톡 계정의 정보를 조회해 그 중 원하는 사용자 계정으로 로그인하거나, 현재 활성화된 카카오톡 계정으로 로그인할 수 있습니다.

1. [서비스] API플랫폼 아지트에서 [SSO 사용 권한]을 요청합니다.
2. OS 환경별 사전 작업을 수행합니다.
   • Android
   • iOS
3. 개발 문서를 참고해 SSO 기능을 구현합니다.
   • Android
   • iOS

Android 환경에서 SSO를 구현하려면 아래 사전 작업이 필요합니다.

• 서비스 앱을 카카오톡과 동일한 서명 키로 서명 합니다. 다른 서명 키를 사용하고 있는 경우, Google 공식 문서(Play 앱 서명 사용하기)를 참고해 통해 앱 서명 키를 변경합니다.

iOS 환경에서 SSO를 구현하려면 아래 사전 작업이 필요합니다.

• 서비스 앱과 카카오톡 모두 동일한 Apple 팀 계정을 사용해야 합니다. 다른 Apple 팀 계정에서 카카오톡의 세션을 이용하고자 할 경우, SSO 인증이 불가능합니다.
• 서비스 앱과 카카오톡 모두 동일한 앱 그룹에 속해야 합니다.

SSO 기능을 이용하려면 Partner SDK를 사용하는 서비스 앱과 카카오톡이 같은 앱 그룹으로 묶여 있어야 합니다.

앱 그룹(App Groups)은 하나의 그룹에 속한 여러 앱이 데이터를 공유할 수 있도록 합니다. iOS 8부터 사용할 수 있으며, 키 체인 뿐만 아니라 UserDefaults 등 다양한 데이터 저장소에서 데이터를 공유하는 데 활용할 수 있습니다. 자세한 설정 방법은 Apple 공식 문서(Sharing access to keychain items among a collection of apps)를 참고합니다.

1. Apple 개발자 사이트에서 앱 그룹을 등록합니다.
   • 참고: Apple 공식 문서(앱 그룹 등록하기)
2. 앱 그룹을 활성화한 후, [Edit]을 눌러 그룹으로 묶을 서비스 앱과 Kakao SDK를 선택합니다.
   • 참고: Apple 공식 문서(앱 그룹 활성화하기)
   • 중요: 작업을 완료하면 기존 인증서가 만료되므로, 새 인증서를 발급 후 교체해야 합니다.
3. Apple 개발자 사이트에서 추가한 앱 그룹 ID과 동일한 값을 XCode 프로젝트에 등록해야 합니다.
   1. XCode에서 프로젝트를 열고 [Project] > [Target] > [Signing & Capabilities]에 접근한 뒤, [+ Capability] 버튼을 선택합니다. (참고: Apple 공식 문서(Configuring app groups))
   2. Apple 개발자 사이트에서 추가한 AppGroup과 동일한 키 값을 [App Groups] 항목에 추가합니다. 페이즈에 맞는 값을 추가해야 합니다. (예: group.com.example.SharedItems)

위 절차를 모두 마쳐야 iOS에서 SSO 로그인을 시도할 수 있습니다.

실제 카카오톡 세션 기반으로 저장된 키 체인 값은 SDK 구조에 따라 디코딩하여 확인 가능합니다. 키 체인에 저장되어 있는 값을 확인하려면 SDK 모델 정보를 확인하여 디코딩해 볼 수 있습니다.

• 이용 정책
  • 사용자 정보 관리
    • 회원 탈퇴 시 정보 파기
    • 정보 수집과 사용
    • 이메일 사용 시 주의 사항
    • 개인정보 국외이전
  • 서비스 약관 운용
  • 가입 미완료 사용자 연결 해제 처리
  • 스토어별 소셜 로그인 정책

카카오 로그인 동의 화면에서 사용자가 카카오톡 채널을 추가하도록 할 수 있습니다. 카카오톡 채널 추가 항목은 기본적으로 1개를 설정할 수 있고, 필요 시 2개까지 설정 가능합니다. 해당 항목의 문구는 정보통신망법을 기반으로 하는 KISA 가이드라인에 따라 정해져 있으며 다른 문구로는 변경할 수 없습니다.

이 기능을 사용하려면 앱 관리 페이지의 [카카오 로그인] > [카카오톡 채널] 메뉴에서 앱에 연결된 카카오톡 채널을 대표 채널로 설정하거나 [서비스] API플랫폼 아지트로 문의해 수동 설정해야 합니다.

또한 친구로 추가될 카카오톡 채널은 공개 상태여야 합니다. 카카오비즈니스의 [채널] > [프로필] > [프로필 설정]에서 [채널 공개] 설정을 [ON]으로 설정합니다. [OFF]인 경우 채널이 비공개되어 카카오톡 친구로 추가할 수 없습니다.

사용자의 앱 연결 상태에 따른 호출 제한, SDK 지원 여부, 권한 요구 사항은 지원 범위를 참고합니다.

* 오픈 문서