페이지 이동경로
  • 문서>

카카오 로그인

카카오 로그인은 카카오계정과 애플리케이션(이하 앱)을 연결하고 카카오 API 사용 권한을 받습니다. 사용자는 '카카오계정으로 로그인' 또는 '카카오톡 간편로그인' 버튼을 눌러 서비스에 로그인할 수 있습니다. 로그인 버튼은 카카오가 제공하는 리소스를 다운로드 받아 사용하거나, 카카오 SDK의 로그인 버튼 추가 기능을 사용합니다.

카카오 로그인 기능은 iOS, Android, JavaScript, REST API로 제공되며 OAuth 2.0을 지원합니다. 로그인은 사용자 동선, 앱 정책이나 UI/UX 등에 따라 다양한 경로에서 시작합니다. 이 문서에서는 기본적인 로그인 절차를 기준으로 안내합니다.

OAuth2.0 OAuth 2.0은 공개 API(Open API)로 제공되는 표준 인증 방법입니다. 자세한 내용은 여기를 참고하세요.
로그인 과정
  • 사용자가 '카카오 로그인' 버튼을 클릭합니다.
  • 사용자가 '카카오톡으로 간편로그인'을 선택하면 카카오톡 실행 또는 실행 중인 카카오톡으로 연결되고, '다른 카카오계정으로 로그인'을 선택하면 직접 계정 정보를 입력하는 화면이 출력됩니다. 카카오톡이 설치되어 있지 않은 기기나 PC 웹 환경에서는 직접 계정 정보를 입력하여 카카오계정으로 로그인하게끔 진행됩니다.
  • '카카오톡으로 간편로그인'한 경우, 카카오톡에 연결된 카카오계정의 자격정보(Credentials)를 통해 사용자를 인식합니다. 직접 카카오계정을 입력해 로그인한 경우에는 해당 계정의 자격정보로 인식합니다.
  • 자격정보가 올바르다면 사용자(Resource Owner)로부터 접근 자원에 대한 동의 및 허가를 얻습니다.
  • 여기까지 성공적으로 수행됐다면 인증 코드(Authorization Code)가 발급됩니다. 이 코드는 Redirect URI 기반으로 앱에 전달됩니다.
  • 앱에서는 전달 받은 인증 코드를 기반으로 사용자 토큰을 요청하고 얻습니다.

로그인은 카카오계정의 사용자 자격정보로 인증 코드를 받아오고, 인증 코드로 액세스 토큰과 리프레스 토큰을 얻는 과정으로 돼 있습니다.

액세스 토큰은 사용자를 인증하고 카카오 API 호출 권한을 부여합니다. 리프레시 토큰(Refresh Token)은 사용자가 매번 카카오계정 정보를 입력하거나 카카오톡으로 로그인하지 않고도 액세스 토큰을 발급 받을 수 있게 합니다.

아래 플랫폼별 가이드는 카카오 로그인 사용법을 안내합니다. Web 플랫폼 가이드는 각 로그인 진행 단계를 자세히 설명하므로 카카오 로그인을 처음 접하는 사용자라면 꼭 읽어봐야 합니다.

로그인이 안 돼요! 로그인에 실패한다면 우선 파악해야할 것은 호출 결과입니다. 동작 중 에러가 난 게 아니라면 로그인 API가 유형에 따라 로그인에 실패한 이유를 응답에 명시합니다. 만약 호출 결과로 확인이 어렵다면 레퍼런스-응답 코드 중 해당 사항이 있는지 확인해 주세요.

Web

웹 환경에서는 JavaScript SDK와 REST API를 사용해 단계별로 카카오 로그인을 구현합니다. 로그인 과정은 연속적으로 진행되며, 앱에 RedirectURI 설정이 필요합니다. 로그인 동작을 순서대로 정리하면 다음과 같습니다.

  • 사용자가 카카오 로그인 버튼을 클릭합니다.
  • 브라우저가 Kakao.Auth.authorize 로그인 함수를 호출합니다. 호출 시, 이번 로그인 요청에 사용될 redirectUri 값을 포함합니다.
  • SDK 함수는 사용자 환경에 맞는 로그인 수단을 거쳐 카카오 인증 서버로 로그인 요청을 전달합니다.
  • 카카오 인증 서버가 로그인 요청을 받고 redirectUri로 인증 코드 응답을 보냅니다.
  • 서비스 서버에서 redirectUri로 전달된 인증 코드를 받습니다.
  • 서비스 서버에서 전달 받은 인증 코드를 포함해 카카오 인증 서버로 사용자 토큰 발급 요청을 합니다.
  • 카카오 인증 서버는 사용자 토큰 발급 요청을 받고 redirectUri로 사용자 토큰 정보를 응답합니다.
  • 서비스 서버에서 redirectUri로 전달된 사용자 액세스 토큰과 리프레시 토큰을 받습니다.
  • 서비스 서버에서 액세스 토큰으로 사용자 정보를 요청합니다.

인증 코드 받기

Request

  • Kakao.Auth.authorize()
Kakao.Auth.authorize({
    redirectUri: 'http://developers.kakao.com/kakaoLogin.jsp'
});
  • Param
Key Type Description Required
redirectUri String 인증코드를 받을 URI O
state String 로그인 이전 상태를 유지하기 위해 저장하는 값
결과가 리다이렉트될 때 입력한 state 값이 그대로 전달됨
Cross-site Request Forgery 공격을 보호하기 위해 활용 가능
X

JavaScript SDK를 사용해 로그인하려면 로그인 버튼 클릭 시 위와 같이 호출합니다. JavaScript SDK가 웹 페이지에 import되어 있어야 동작합니다.

redirectUri는 카카오 인증 서버의 응답을 받아 처리할 주소로, 앱 설정에서 등록한 값만 사용할 수 있습니다. state는 특정 값을 로그인 과정에서 전달 및 유지하고 싶을 때 활용합니다.

Response

  • 사용자 동의
HTTP/1.1 302 Found
Content-Length: 0
Location: {redirect_uri}?code={authorize_code}
  • 로그인 취소
HTTP/1.1 302 Found
Content-Length: 0
Location: {redirect_uri}?error=access_denied

로그인 화면에서 사용자가 동의 버튼을 클릭하면 인증 코드가 담긴 쿼리 스트링(Query String)을 요청 시 전달된 redirect_uri로 전송합니다. 사용자가 취소 버튼을 클릭하면 에러 쿼리 스트링이 redirect_uri로 전송됩니다.

서비스 서버는 redirect_uri로 받은 요청을 처리해 인증 코드를 얻거나 상황에 맞는 페이지를 보여주도록 처리해야 합니다.

사용자 토큰 받기

Request

  • URL
POST /oauth/token HTTP/1.1
Host: kauth.kakao.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
  • Param
설명 필수
grant_type authorization_code로 고정 O
client_id 앱 생성 시 발급 받은 REST API O
redirect_uri 코드가 리다이렉트될 URI O
code 코드 받기 요청으로 얻은 인증 코드 O
client_secret 앱 설정-고급-client_secret에서 설정 가능
ACTIVE 상태인 경우 필수 설정해야 함
X
  • Sample
curl -v -X POST https://kauth.kakao.com/oauth/token \
 -d 'grant_type=authorization_code' \
 -d 'client_id={app_key}' \
 -d 'redirect_uri={redirect_uri}' \
 -d 'code={authorize_code}'

인증 코드를 받은 뒤, 서비스 서버에서 REST API를 통해 사용자 토큰을 요청합니다. JavaScript SDK의 Kakao.Auth.authorize 함수로 인증 코드 받기를 요청한 경우에도 이후 진행이 같습니다. 위 파라미터 값들을 담아 POST로 요청합니다. 인증 코드 요청과 마찬가지로 필수 입력해야하는 파라미터에 주의합니다.

Response

Sample: Success

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type":"bearer",
    "refresh_token":"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "expires_in":43199,
    "scope":"Basic_Profile"
}
  • Key
Name Description
access_token 사용자 액세스 토큰 값
token_type 토큰 타입(OAuth2.0 bearer Authentication)
refresh_token 사용자 리프레시 토큰 값
expires_in 토큰 만료 시간(초)
scope 인증된 사용자의 정보 조회 권한 범위

응답은 json 객체로 Redirect URI에 전달됩니다. 두 가지 종류의 토큰과 타입, 초 단위로 된 만료 시간을 포함하고 있습니다. 사용자가 로그인에 성공하면 발급되는 액세스 토큰(Access Token)과 리프레시 토큰(Refresh Token)은 각각 역할과 유효기간이 다릅니다. 간략히 표로 정리해보면 아래와 같습니다.

  • Token Information
Token Type Role Valid
Access Token 사용자를 인증합니다. Android, iOS : 12시간
REST API : 6시간
Refresh Token 일정 기간 동안 다시 인증 절차를 거치지 않고도 액세스 토큰 발급을 받을 수 있게 해 줍니다. 2달
유효기간 1달 남은 시점부터 갱신 가능

실제 사용자 인증을 맡는 액세스 토큰은 비교적 짧은 만료 시간을 가집니다. 하지만 유효한 리프레시 토큰이 있다면, 사용자가 다시 로그인했을 때 리프레시 토큰으로 액세스 토큰을 다시 발급 받을 수 있습니다.

REST API 사용 시에는 사용자 토큰 관리를 참고해 사용자 토큰 유효성을 검사하거나 갱신하도록 합니다.

받은 사용자 토큰으로 할 수 있는 일 카카오 로그인을 성공적으로 구현해 사용자 액세스 토큰을 받았다면, 그 토큰 정보로 사용자 정보 요청을 통해 프로필 정보를 받아 봅니다. 이 밖에도 사용자 토큰으로 호출하는 API들이 있습니다.

iOS

Request

  • 로그인 버튼 생성
// button position
int xMargin = 30;
int marginBottom = 25;
CGFloat btnWidth = self.view.frame.size.width - xMargin * 2;
int btnHeight = 42;

UIButton* kakaoLoginButton
    = [[KOLoginButton alloc] initWithFrame:CGRectMake(xMargin, self.view.frame.size.height-btnHeight-marginBottom, btnWidth, btnHeight)];
kakaoLoginButton.autoresizingMask = UIViewAutoresizingFlexibleTopMargin | UIViewAutoresizingFlexibleWidth;

[self.view addSubview:kakaoLoginButton];

UIButton을 상속한 KOLoginButton을 이용해 카카오 로그인을 구현합니다.

  • 로그인 호출
[kakaoLoginButton addTarget:self
                     action:@selector(invokeLoginWithTarget:)
           forControlEvents:UIControlEventTouchUpInside];

생성한 버튼에 로그인 과정을 시작하는 method인 invokeLoginWithTarget을 연결합니다. 참고로 iOS SDK는 다음과 같이 로그인을 시도할 때마다 기존의 오래된 세션이 남아있지 않도록 닫고, 다시 세션을 엽니다.

// ensure old session was closed
[[KOSession sharedSession] close];

[[KOSession sharedSession] openWithCompletionHandler:^(NSError *error) {
    if ([[KOSession sharedSession] isOpen]) {
        // login success
        NSLog(@"login succeeded.");
    } else {
        // failed
        NSLog(@"login failed.");
    }
}];
다중 인증 선택창 로그인 시 상황에 따라 카카오톡, 카카오스토리, 다른 카카오계정으로 로그인의 다중 인증 선택창이 나타납니다. 인증 타입 종류를 직접 제어하고 싶을 경우, 원하는 인증 방식의 KOAuthType을 파라미터로 넘길 수 있습니다. 카카오톡으로 간편로그인만 제공하고자 할 때의 예제입니다.
```
[[KOSession sharedSession] openWithCompletionHandler:^(NSError *error) {
    ...
} authType:(KOAuthType)KOAuthTypeTalk, nil]];
```

Response

로그인 요청의 응답 결과는 리프레시 토큰, 액세스 토큰 두 종류의 사용자 토큰입니다. 사용자 토큰은 카카오 SDK가 기기에 저장하고 관리합니다. 이때 저장 보안 방식을 프로젝트의 info 설정, info.plist파일 등 plist 옵션으로 선택할 수 있습니다. 토큰 암호화 저장 기능을 활성화하려면 아래와 같이 설정합니다.

<key>KAKAO_SECURE_MODE</key>
<true/>

또한 iOS SDK는 API 호출 시 자동으로 사용자 토큰을 갱신하는 기능이 있습니다. 이 기능을 쓰려면 약간의 설정이 필요합니다. iOS 카카오 SDK에서는 두 가지 설정이 필요합니다.

  • AppDelegate-didFinishLaunchingWithOptions에서 automaticPeriodicRefresh 옵션을 활성화합니다.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    [KOSession sharedSession].automaticPeriodicRefresh = YES;
}
  • AppDelegate-applicationDidEnterBackground 부분에 아래 내용을 추가합니다.
- (void)applicationDidEnterBackground:(UIApplication *)application {
    ...
    [KOSession handleDidEnterBackground];
}

Android

Request

  • 로그인 버튼 생성
<com.kakao.usermgmt.LoginButton
    android:id="@+id/com_kakao_login"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:layout_weight="1"
    android:layout_marginBottom="30dp"
    android:layout_marginLeft="20dp"
    android:layout_marginRight="20dp"/>

Android SDK로 카카오 로그인 버튼을 구현하려면, 로그인 버튼을 포함하는 LoginButton FrameLayout을 활용합니다. 로그인 창 레이아웃(layout) 파일에 위 내용을 추가합니다.

Request

  • SampleLoginActivity
public class SampleLoginActivity extends Activity {
    private SessionCallback callback;

    /**
     * 로그인 버튼을 클릭 했을시 access token을 요청하도록 설정한다.
     *
     * @param savedInstanceState 기존 session 정보가 저장된 객체
     */
    @Override
    protected void onCreate(final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.layout_common_kakao_login);

        callback = new SessionCallback();
        Session.getCurrentSession().addCallback(callback);
        Session.getCurrentSession().checkAndImplicitOpen();
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (Session.getCurrentSession().handleActivityResult(requestCode, resultCode, data)) {
            return;
        }

        super.onActivityResult(requestCode, resultCode, data);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        Session.getCurrentSession().removeCallback(callback);
    }

    private class SessionCallback implements ISessionCallback {

        @Override
        public void onSessionOpened() {
            redirectSignupActivity();
        }

        @Override
        public void onSessionOpenFailed(KakaoException exception) {
            if(exception != null) {
                Logger.e(exception);
            }
        }
    }

    protected void redirectSignupActivity() {
        final Intent intent = new Intent(this, SampleSignupActivity.class);
        startActivity(intent);
        finish();
    }
}

안드로이드 카카오 SDK 샘플(kakao-open-android-sdk-sample)에 포함되어 있는 com.kakao.sdk.sample.common.SampleLoginActivity 예제 코드입니다. 위 클래스는 아래와 같은 다음 구성 요소들을 갖고 있습니다.

  • 세션 응답(SessionCallback)인 callback 객체
  • 응답 결과를 처리하는 onActivityResult 함수
  • 세션이 열려 있을 때 로그인 단계로 넘어가거나 실패 시 예외처리를 하는 SessionCallBack 함수
  • 로그인을 요청하는 Activity인 redirectSignupActivity 함수

이 객체와 함수들이 하는 일을 보면 로그인이 요청되기까지 세션을 확인하고 처리하는 동작이 어떻게 이뤄지는지 파악할 수 있습니다. 이를 참고해 로그인 과정을 구현합니다. Android 레퍼런스에서 각 클래스와 메소드가 하는 일들을 참고해 각각의 기능을 더 잘 이해할 수 있습니다.

KakaoAdapter 객체를 통해 애플리케이션은 카카오 SDK에 필요한 정보를 제공하고 서로 연결되어야 합니다. 이를 위해 IApplicationConfig의 getApplicationContext 메소드를 통해 Application Context를 얻습니다.

SessionCallback이 상속하고 있는 인터페이스(interface) ISessionCallback은 세션을 체크했을 때 상태 변경에 따른 응답으로, 세션이 닫혔을 때 세션 callback을 넘깁니다. 기본 설정은 KakaoAdapter에 정의돼 있으며, 설정 변경을 원할 경우 상속해 사용하는 추상 클래스(abstract class)입니다.

액세스 토큰(Access Token)을 성공적으로 발급 받아 유효한 토큰을 가지고 있는 상태일 때는 onSessionOpened이고 로그인 다음 Activity로 이동하게 됩니다. onSessionOpenFailed는 메모리나 캐시(memory)에 세션 정보가 전혀 없는 상태를 뜻하며, 로그인 버튼이 출력돼 사용자가 로그인을 시작하고 액세스 토큰을 요청할 수 있도록 합니다.

onCreate는 로그인 버튼을 찾아오고, 세션 상태가 변경될 때 불리는 세션 callback을 추가해 줍니다. 세션이 닫혀 있는지, 이미 열려있는지, 갱신 가능한지에 따라 다른 액션을 취합니다. 예제에서는 세션이 닫혀 있으면 로그인 버튼을 보여주고, 열려 있으면 로그인 버튼을 보여주지 않고, 갱신 가능할 때는 갱신까지 하게 돼 있습니다.

카카오 SDK에서 필요로 하는 Activity는 onActivityResult가 로그인 Activity를 이용하여 띄워주는데, 결과를 세션에도 넘겨 처리할 수 있도록 Session#handleActivityResult를 호출합니다.

세션 callback 삭제는 onDestroy가 합니다.

Response

로그인 요청 결과는 액세스 토큰, 리프레시 토큰 두 종류의 사용자 토큰입니다. 카카오 SDK는 사용자 토큰을 관리하는 기능을 갖고 있으며, Android 카카오 SDK는 토큰 관리를 위한 별도 설정이 필요하지 않습니다.