K2100: 인증 로그인

이 문서는 카카오톡 인증 서비스의 K2100 인증 로그인 API 사용법을 안내합니다.

시작하기 전에

기능 소개

K2100 인증 로그인은 소셜 로그인 서비스인 카카오 로그인과 카카오톡 인증 서비스의 전자서명이 결합된 형태의 로그인 서비스입니다.

사용자는 앱투앱(App to App) 또는 채널 메시지를 통해 카카오톡에서 간편하게 카카오톡 인증 로그인을 수행할 수 있습니다. 사용자는 카카오계정 또는 카카오톡에 연결된 카카오계정으로 로그인한 뒤, 이용기관 앱에 대한 개인정보제공 및 서비스 약관에 동의합니다. 이어 카카오톡의 카카오 인증서로 로그인에 대한 전자서명을 수행합니다.

이용기관은 사용자 비교 및 검증 용도의 서명자 정보를 서명자 정보 가져오기로 제공받을 수 있습니다. 이밖에 카카오톡 인증 로그인 과정에서 사용자로부터 동의받은 개인정보 항목을 카카오로부터 제공받을 수 있습니다. 이를 통해 별도의 사용자 정보 입력 과정이나 서비스 약관 동의를 거치지 않고도 회원가입 및 로그인 처리를 할 수 있습니다. 개인정보제공 및 서비스 약관 동의 화면 구성을 참고합니다.

카카오톡 인증 로그인은 사용자가 카카오톡 앱을 실행시키고 서명하는 '앱투앱(App to app) 방식', 사용자의 카카오톡 앱으로 서명 요청 메시지를 보내는 '채널 메시지 방식' 두 가지 인증 방식을 제공합니다. 인증 방식에 대한 정보는 카카오톡 인증 로그인을 참고합니다.

카카오톡 인증 서비스 API는 서버간 연동(Server to Server)을 원칙으로 합니다.

Kakao SDK 설치

카카오톡 인증 로그인은 JavaScript, Android, iOS용 Kakao SDK를 통해 제공합니다. Kakao SDK를 사용해 보다 쉽게 카카오톡 인증 로그인을 구현할 수 있으며, 이밖에 카카오에서 제공하는 다양한 API도 손쉽게 이용할 수 있습니다. Kakao SDK 설치 및 설정 안내는 아래를 참고합니다.

JavaScript SDK

아래 순서로 Kakao SDK for JavaScript(이하 JavaScript SDK)의 설정, 설치, 초기화를 완료합니다.

1. 플랫폼 등록
2. 설치
3. 초기화

Android SDK

아래 순서로 Kakao SDK for Android(이하 Android SDK) 설치 및 설정을 완료합니다.

1. 설치
2. 플랫폼 등록
3. 인터넷 사용 권한 설정
4. Java 8 사용 설정
5. 키 해시 등록
6. Redirect URI 설정

iOS SDK

아래 순서로 Kakao SDK for iOS(이하 iOS SDK) 설치 및 설정을 완료합니다.

1. 설치
2. 플랫폼 등록
3. 앱 실행 허용 목록 설정
4. URL Schemes 설정
5. 카카오톡으로 로그인을 위한 설정

iOS SDK 설치 및 설정 완료 후, 아래와 같이 이용기관 앱에서 Cert를 포함해 필요한 모듈을 사용하도록 설정해야 합니다.

import KakaoSDKCommon
import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKCert

카카오톡 인증 로그인 과정

카카오톡 인증 서비스의 카카오톡 인증 로그인은 OAuth 2.0 기반으로 사용자를 인증하고 인가 코드 및 토큰을 발급합니다. 아래는 카카오톡 인증 로그인의 진행 과정을 간략하게 표현한 시퀀스 다이어그램(Sequence Diagram)입니다.

위 과정을 요약하면 다음과 같습니다.

1. 사용자가 이용기관 서비스에서 카카오톡 인증 로그인을 요청합니다.
2. 이용기관이 카카오에 카카오톡 인증 로그인을 위한 인가 코드 받기를 요청합니다.
   • 서명 원문을 signData 파라미터로 전달할 수 있습니다.
   • 필요한 서명자 정보를 identifyItems 파라미터로 지정할 수 있습니다.
3. 카카오는 카카오톡 앱 실행 스킴(Scheme)을 실행하거나, 전자서명 대기화면을 출력하고 채널 메시지를 발송합니다.
4. 사용자는 카카오톡에서 이용기관 앱에 대한 개인정보제공 및 서비스 약관 동의를 수행한 뒤 전자서명합니다.
5. 카카오는 이용기관에 인가 코드를 반환합니다.
6. 이용기관은 인가 코드로 토큰을 요청합니다.
7. 카카오는 이용기관에 토큰 및 전자서명 검증을 위한 접수번호인 tx_id를 반환합니다.
8. 이용기관은 전자서명 검증하기 API를 호출해 서명 원문인 signData에 대한 전자서명 데이터 전문을 받아 검증하고, 서명자 정보 가져오기 API를 요청해 가입 및 로그인 처리를 완료합니다.
   • 연계정보(CI)를 제공받는 경우, 이용기관 서버에서 CI를 비교해 올바른 사용자인지 검증해야 합니다.
   • 필요 시 서명자 정보 외의 사용자 정보를 사용자 정보 가져오기 API로 요청할 수 있습니다.

위 과정 중 4번 단계에는 5분의 유효일시가 설정되어 있습니다. 사용자가 유효일시 이내에 인증을 완료하지 않을 경우, 기존 요청은 만료 처리되므로 인가 코드 받기를 다시 요청해야 합니다.

2번의 인가 코드 받기와 6번의 토큰 받기는 Kakao SDK for Android 또는 iOS 사용 시 한 번의 메서드 호출로 처리됩니다. 자세한 사항은 각 플랫폼 개발 가이드를 참고합니다.

사용자가 카카오톡에서 전자서명하는 과정은 아래 이미지를 참고합니다.

개인정보제공 및 서비스 약관 동의 화면 구성

개인정보제공 동의항목은 이용기관 앱에 설정된 동의항목과 서비스 약관에 따라 구성됩니다. 서비스 약관은 카카오싱크를 이용 중인 앱에만 제공됩니다. 동의항목에 대한 자세한 안내는 인가를, 서비스 약관에 대한 자세한 안내는 카카오싱크를 참고합니다.

아래는 개인정보제공 및 서비스 약관 동의 화면의 예시입니다.

사용자 인증 요청 안내문

채널 메시지 및 전자서명 인증 요청 정보 화면의 내용은 요청구분, 요청기관, 기기, 유효일시, 서비스 요청기관 고객센터로 구성됩니다. 각 항목의 값은 이용기관 등록 정보로 자동으로 지정되며, 이용기관 등록 정보를 변경하려면 계약을 체결한 딜러사를 통해 수정 요청해야 합니다. 아래 예시와 설명을 참고합니다.

JavaScript SDK를 통한 카카오톡 인증 로그인의 전자서명 대기화면 동작

지원 방식

동작

Windows 및 MacOS

• ID 및 비밀번호 입력을 통한 카카오계정 로그인만 가능
  1. 카카오계정 로그인 후, 카카오톡 인증 로그인을 위한 채널 메시지가 해당 카카오계정과 연결된 카카오톡으로 발송됨
  2. 사용자는 카카오톡에서 채널 메시지를 통해 이용기관 앱에 대한 제3자정보제공 및 서비스 약관 동의 후 전자서명을 수행

Android 및 iOS

• 카카오톡 앱이 설치돼 있는 경우: 카카오톡을 통한 간편로그인 가능
  1. 사용자는 카카오톡에서 이용기관 앱에 대한 제3자정보제공 및 서비스 약관 동의 후 전자서명 수행
  2. Android는 전자서명 완료 후 이용기관 서비스로 이동 지원, iOS는 사용자가 직접 이용기관 서비스로 이동해야 함
• 카카오톡 앱이 설치돼 있지 않은 경우: ID 및 비밀번호 입력을 통한 카카오계정 로그인만 가능
  • 해당 카카오계정과 연결된 카카오톡이 있을 경우, 해당 카카오톡으로 카카오톡 인증 로그인을 위한 채널 메시지가 발송됨
  • 해당 카카오계정에 연결된 카카오톡이 없을 경우, 카카오톡 인증 로그인 서비스 이용 불가

전자서명 대기화면 및 전자서명 요청 채널 메시지 예시 화면

전자서명 검증

카카오톡 인증 로그인 상품의 경우, 전자서명의 서명 원문은 요청 시 전달된 signData 값입니다. 카카오톡 인증 로그인의 사용자 전자서명을 검증하려면 REST API로 제공되는 전자서명 검증하기 API를 사용해야 합니다. 해당 API는 카카오톡 인증 상품을 이용하는 경우에만 호출할 수 있으며, 자세한 사항은 전자서명 검증하기를 참고합니다.

연결 끊기

사용자가 이용기관 서비스에서 카카오 로그인 연동 해제 또는 탈퇴 시, 연결 끊기 API를 호출해 이용기관 앱과 사용자의 연결을 끊어야 합니다.

연결 끊기 API 호출 없이 이용기관 서비스에서의 연동 해제 처리만 이뤄질 경우, 사용자가 다시 카카오톡 인증 로그인을 수행할 때 개인정보제공 및 서비스 약관 동의 절차를 거치지 않아 이용에 불편을 겪거나 문제가 발생할 수 있습니다. 자세한 사항은 연결을 참고합니다.

연결 끊기 API는 REST API 또는 Kakao SDK를 통해 호출할 수 있습니다. 다음 개발 가이드를 참고합니다.

• REST API
• JavaScript
• Android
• iOS

JavaScript

Kakao SDK for JavaScript(이하 JavaScript SDK)를 사용해 카카오톡 인증 로그인을 구현하려면 인가 코드 받기, 토큰 받기를 순서대로 호출합니다.

Kakao.Auth.authorizeForCert({
  redirectUri: '${REDIRECT_URI}',
  settleId: '${SETTLE_ID}',
  signData: '${SIGN_DATA}',
  identifyItems: 'ci,name,birthday,phone_number,gender',
});

Kakao.Auth.authorizeForCert({
  redirectUri: '${REDIRECT_URI}',
  settleId: '${SETTLE_ID}',
  signData: '${SIGN_DATA}',
  identifyItems: 'ci,name,birthday,phone_number,gender',
  prompt: 'login',
});

{
    "access_token": "Lj7QYZ39ieSlbon5a0JGPzey90vT3YkKTv4-9grKJuoAAAF7d9SaqQ",
    "token_type": "bearer",
    "refresh_token": "UHHQnTq8-gfgJTnQNAfvJWSnSvYRCyDS9yJbNArKJuoAAAF7d9SapA",
    "expires_in": 7199,
    "scope": "age_range birthday account_email profile_image talk_message gender profile_nickname friends",
    "tx_id": "01c6e5062c-81e1-4f07-aa36-9671bb1e7ae2",
    "refresh_token_expires_in": 86399
}

Android

Kakao SDK for Android(이하 Android SDK)를 사용해 카카오톡 인증 로그인을 요청하려면 CertApiClient가 제공하는 카카오톡 인증 로그인 전용 메서드를 사용합니다.

Android SDK의 경우, 인증 방식별로 메서드가 분리되어 있습니다. 다음 표를 참고하여 이용 중인 인증 방식에 맞는 메서드를 호출합니다.

각 메서드 호출 시 signData 파라미터로 서명 원문을 전달합니다. 전자서명 검증하기를 통해 전자서명 데이터 전문을 받을 수 있습니다.

필요에 따라 추가 파라미터를 사용할 수 있습니다. 서명자 정보가 필요한 경우, identifyItems 파라미터로 필요한 항목을 지정합니다. 카카오톡 인증 로그인 완료 후, 서명자 정보 가져오기로 서명자 정보를 제공받을 수 있습니다.

두 메서드의 파라미터 구성은 동일하며, 다음 파라미터 정보와 예제를 참고합니다.

파라미터

예제: App to App 방식

// 앱투앱 방식 카카오톡 인증 로그인
CertApiClient.instance.certLoginWithKakaoTalk(
    context, 
    CertType.K2100, 
    signData = "${SIGN_DATA}",
    identifyItems = listOf(IdentifyItem.CI, IdentifyItem.NAME, IdentifyItem.BIRTHDAY, IdentifyItem.PHONE_NUMBER, IdentifyItem.GENDER),
    settleId = "${SETTLE_ID}"
) { certTokenInfo, error ->
    if (error != null) {
        Log.e(TAG, "로그인 실패", error)
    }
    else if (certTokenInfo != null) {        
        Log.i(TAG, "로그인 성공 ${certTokenInfo.token.accessToken} ${certTokenInfo.txId}")    
    }
}

예제: 채널 메시지 방식

// 카카오계정으로 카카오톡 인증 로그인
CertApiClient.instance.certLoginWithKakaoAccount(
    context, 
    CertType.K2100, 
    signData = "${SIGN_DATA}", 
    identifyItems = listOf(IdentifyItem.CI, IdentifyItem.NAME, IdentifyItem.BIRTHDAY, IdentifyItem.PHONE_NUMBER, IdentifyItem.GENDER),
    settleId = "${SETTLE_ID}"
) { certTokenInfo, error ->
    if (error != null) {
        Log.e(TAG, "로그인 실패", error)
    }
    else if (certTokenInfo != null) {        
        Log.i(TAG, "로그인 성공 ${certTokenInfo.token.accessToken} ${certTokenInfo.txId}")    
    }
}

요청 성공 시, 사용자는 카카오톡에서 인증을 수행합니다.

사용자가 유효일시 이내에 카카오톡에서 동의 및 전자서명을 완료하면, Android SDK가 인가 코드를 받아 토큰 받기를 요청하는 과정을 내부적으로 수행하고 CertTokenInfo 객체를 응답으로 반환합니다. CertTokenInfo는 토큰과 함께 전자서명 접수번호인 txId를 포함합니다.

CertTokenInfo

요청 실패 시 문제 해결에서 에러 코드 정보를 확인합니다.

iOS

Kakao SDK for iOS(이하 iOS SDK)를 사용해 카카오톡 인증 로그인을 요청하려면 CertApi가 제공하는 카카오톡 인증 로그인 전용 메서드를 사용합니다.

iOS SDK의 경우, 인증 방식별로 메서드가 분리되어 있습니다. 다음 표를 참고하여 이용 중인 인증 방식에 맞는 메서드를 호출합니다.

각 메서드 호출 시 signData 파라미터로 서명 원문을 전달합니다. 전자서명 검증하기를 통해 전자서명 데이터 전문을 받을 수 있습니다.

필요에 따라 추가 파라미터를 사용할 수 있습니다. 서명자 정보가 필요한 경우, identifyItems 파라미터로 필요한 항목을 지정합니다. 카카오톡 인증 로그인 완료 후, 서명자 정보 가져오기로 서명자 정보를 제공받을 수 있습니다.

두 메서드의 파라미터 구성은 동일하며, 다음 파라미터 정보와 예제를 참고합니다.

파라미터

예제: 앱투앱 방식

if (UserApi.isKakaoTalkLoginAvailable()) {
    CertApi.shared.certLoginWithKakaoTalk(certType: .K2100, 
                                          signData: "${SIGN_DATA}",
                                          identifyItems: [.CI, .Name, .Birthday, .PhoneNumber .Gender],
                                          settleId:"${SETTLE_ID}") { (certTokenInfo, error) in
        if let error = error {
            print(error)
        }
        else {
            // 성공 시 동작 구현
            _ = certTokenInfo.oauthToken
            _ = certTokenInfo.txId
        }
    }
}

예제: 채널 메시지 방식

CertApi.shared.certLoginWithKakaoAccount(certType: .K2100, 
                                         signData: "${SIGN_DATA}", 
                                         identifyItems: [.CI, .Name, .Birthday, .PhoneNumber .Gender],
                                         settleId:"${SETTLE_ID}") { (certTokenInfo, error) in
    if let error = error {
        print(error)
    }
    else {
        // 성공 시 동작 구현
        _ = certTokenInfo.oauthToken
        _ = certTokenInfo.txId
    }
}

요청 성공 시, 사용자는 카카오톡에서 인증을 수행합니다.

사용자가 유효일시 이내에 카카오톡에서 동의 및 전자서명을 완료하면, iOS SDK가 인가 코드를 받아 토큰 받기를 요청하는 과정을 내부적으로 수행하고 CertTokenInfo 객체를 응답으로 반환합니다. CertTokenInfo는 토큰과 함께 전자서명 접수번호인 txId를 포함합니다.

CertTokenInfo

요청 실패 시 문제 해결에서 에러 코드 정보를 확인합니다.

더 보기

• 이해하기
• 문제 해결
• 디자인 가이드