페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • JavaScript

카카오 로그인

JavaScript

이 문서는 Kakao SDK for JavaScript(이하 JavaScript SDK)를 사용한 카카오 로그인 구현 방법을 안내합니다.

이 문서에 포함된 기능 일부는 [도구] > [JS 데모]를 통해 사용해 볼 수 있습니다.

카카오 로그인 구현에 필요한 로그인 버튼 이미지는 [도구] > [리소스 다운로드]에서 제공합니다. 해당 로그인 버튼은 디자인 가이드를 참고하여 서비스 UI에 적합한 크기로 수정하여 사용할 수 있습니다.

애플리케이션 설정 확인

이 기능을 사용하려면 카카오디벨로퍼스(Kakao Developers, 이하 개발자 웹사이트) 애플리케이션(이하 앱) 설정에 Web 플랫폼 및 도메인 정보가 등록되어 있어야 합니다. 자세한 내용은 애플리케이션 등록을 참고합니다.

시작하기 전에

시작하기 > JavaScript를 참고하여 JavaScript SDK를 웹 페이지에 포함하고 초기화한 뒤 카카오 로그인 API를 호출해야 합니다.

로그인

카카오 로그인 함수인 Kakao.Auth.authorize API로 간편 로그인을 요청합니다. 간편 로그인은 카카오계정 ID 및 비밀번호 입력 없이 카카오톡을 통해 사용자를 인증하고 인가 코드를 발급받는 기능입니다. 사용자가 카카오 로그인 버튼을 클릭했을 때, 클릭 이벤트 핸들러에서 Kakao.Auth.authorize API를 호출하면 카카오 로그인 동의 화면을 띄울 수 있습니다. 동의 화면에서 사용자가 사용자 정보 제공 및 기능 활용 동의를 하고 [동의하고 계속하기] 버튼을 누르면 인가 코드 응답이 서비스 서버의 Redirect URIHTTP 302 리다이렉트(Redirect)됩니다.

서비스 서버에서 인가 코드를 사용해 REST API로 토큰 받기를 요청하여 로그인을 완료합니다. Redirect URI 등록 및 확인 방법은 설정하기 > Redirect URI 등록을, 인가 코드 발급 요청의 응답 및 토큰 발급 요청 방법은 REST API를 참고합니다.

주의

JavaScript SDK로 Kakao.Auth.authorize 함수를 호출할 때는 SDK 초기화 시 사용된 JavaScript 키를 사용합니다. 하지만 REST API로 토큰 받기를 요청할 때는 REST API 키를 사용해야 합니다.

회원 가입

카카오 로그인은 카카오 플랫폼 안에서 사용자를 인증하고 앱과 연결하는 기능입니다. 카카오는 서비스 데이터에 접근하지 않으므로, 서비스 회원 정보에 회원 가입 처리를 할 수 없습니다. 카카오 로그인 후 필요한 회원 가입 처리나 회원 정보 갱신은 서버에서 인가 코드 및 토큰을 받은 후 구현해야 합니다.

Request
Kakao.Auth.authorize(PARAMETER);
Parameter
Name Type Description Required
redirectUri String 인가 코드를 받을 URI O
state String 인가 코드 요청과 응답 과정에서 유지할 수 있는 파라미터 X
scope String 추가 항목 동의 받기 요청 시 사용
추가 동의 받을 동의 항목 ID 목록, 하나의 문자열에 여러 개의 ID를 쉼표(,)로 구분하여 전달
동의 항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의 항목] 참고
(예: 'account_email,gender')
X
throughTalk Boolean 간편 로그인 사용 여부 (기본값: true) X
Sample
Kakao.Auth.authorize({
  redirectUri: '{REDIRECT_URI}'
});

토큰 할당하기

로그인을 완료하여 토큰 값이 서비스 서버로 전달되면, 서비스 서버에서 토큰을 받아 사용자 정보 가져오기 등 카카오 API를 호출할 때 사용할 수 있습니다. 만약 로그인 이외의 카카오 API를 JavaScript SDK로 호출하려면 토큰 할당을 해야 합니다.

로그인 이후 다음과 같이 Kakao.Auth.setAccessToken 함수를 통해 서버에서 발급받은 토큰을 할당해야 합니다. 서비스 서버에서 로그인 응답을 통해 전달받은 액세스 토큰(Access Token) 값을 SDK에서 사용할 수 있도록 설정합니다.

Kakao.Auth.setAccessToken(ACCESS_TOKEN);

로그아웃

현재 로그인한 사용자를 로그아웃시킬 때 사용하는 기능입니다. 로그아웃은 토큰을 만료시켜 더 이상 해당 액세스 토큰으로 카카오 API를 호출할 수 없도록 합니다.

사용자가 로그아웃 버튼을 눌렀을 때, 클릭 이벤트 핸들러에서 Kakao.Auth.logout 함수를 호출하면 토큰을 만료시킬 수 있습니다. 로그아웃 성공 시, 콜백 함수를 통해 서비스의 로그아웃 로직을 수행하도록 구현해야 합니다.

주의

Kakao.Auth.logout 함수는 로그인 시 발급받은 토큰을 만료시키는 함수입니다. 카카오계정의 로그아웃이나 서비스의 로그아웃에 영향을 주지 않습니다. 서비스의 로그아웃은 직접 구현해야 합니다.

Parameter
Type Description Required
Function() 토큰 만료 시 호출되는 콜백 함수 X
Sample
if (!Kakao.Auth.getAccessToken()) {
  console.log('Not logged in.');
  return;
}
Kakao.Auth.logout(function() {
  console.log(Kakao.Auth.getAccessToken());
});

연결 끊기

앱과 사용자의 연결을 끊기 위해 호출하는 함수입니다. 사용자가 연결 끊기 버튼을 클릭했을 때, 클릭 이벤트 핸들러에서 Kakao.API.request 함수를 사용해서 연결 끊기를 요청할 수 있습니다.

Kakao.API.request 함수의 파라미터인 url에 '/v1/user/unlink'를 할당해서 사용합니다.

연결 끊기 후 서비스의 탈퇴 처리

서비스의 탈퇴 처리는 연결 끊기 후 직접 구현해야 합니다. 해당 함수는 사용자와 개발자 웹사이트 앱의 연결을 끊는 함수이며 서비스 탈퇴에 영향을 미치지 않습니다.

Parameter
Name Type Description Required
url String /v1/user/unlink로 고정 O
success Function(Object) API 호출이 성공할 때 실행되는 콜백 함수 X
fail Function(Object) API 호출이 실패할 때 실행되는 콜백 함수 X
always Function(Object) API 호출 성공 여부에 관계 없이 항상 호출되는 콜백 함수 X
Sample
Kakao.API.request({
  url: '/v1/user/unlink',
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
});

연결끊기 API를 호출한 경우가 아닌 사용자가 서비스와의 연결을 직접 끊었을 때 알림을 받으려면 '연결 끊기 알림 받기' 기능을 사용합니다. 자세한 구현 방법 및 콜백 요청 정보는 유용한 참고 정보 > 고급 > 연결 끊기 알림을 참고합니다.

사용자 정보 가져오기

동의 항목 설정 필요

이 API를 사용하려면 동의 항목 설정을 참고하여 필요한 사용자 정보 동의 항목을 설정해야 합니다.

현재 로그인한 사용자의 카카오계정 정보를 불러옵니다. Kakao.API.request 함수를 통해 사용자 정보 가져오기 API를 호출합니다. url 파라미터 값으로 사용자 정보 요청 주소인 /v2/user/me를 지정하여 Kakao.API.request 함수를 호출합니다. property_keys 파라미터를 통해 특정 사용자 정보만 지정해서 요청할 수도 있습니다. 해당 파라미터에 사용할 수 있는 키의 종류는 REST API를 참고합니다.

요청 성공 시 응답은 각 사용자 정보를 포함합니다. 응답 내용은 REST API와 동일하므로 이해하기 > 사용자 정보를 참고합니다.

Request
Kakao.API.request({
    url: '/v2/user/me'
});
Parameter
Name Type Description Required
url String /v2/user/me 로 고정 O
success Function(Object) API 호출이 성공할 때 실행되는 콜백 함수 X
fail Function(Object) API 호출이 실패할 때 실행되는 콜백 함수 X
always Function(Object) API 호출 성공 여부에 관계 없이 항상 호출되는 콜백 함수 X
data Object API에 전달할 파라미터, 자세한 내용은 data: 사용자 정보 가져오기 확인 X
data: 사용자 정보 가져오기
Name Type Description Required
property_keys String[] 요청할 사용자 정보 종류를 지정할 때 사용하는 사용자 정보의 키 목록
사용자 정보 참고
(예: ["kakao_account.email","kakao_account.gender"])
X
Sample
Kakao.API.request({
    url: '/v2/user/me',
    success: function(response) {
        console.log(response);
    },
    fail: function(error) {
        console.log(error);
    }
});
Sample: 이메일, 성별 정보 가져오기
Kakao.API.request({
    url: '/v2/user/me',
    data: {
        property_keys: ["kakao_account.email","kakao_account.gender"]
    },
    success: function(response) {
        console.log(response);
    },
    fail: function(error) {
        console.log(error);
    }
});

사용자 정보 저장하기

Kakao.API.request 함수를 통해 사용자 정보 저장하기 API를 호출합니다. 사용자 정보의 종류는 이해하기 > 사용자 정보를 참고합니다.

사용자 정보 저장하기 기능은 사용자 프로퍼티인 properties에 값을 저장합니다. 키 값은 [내 애플리케이션] > [사용자 프로퍼티]에 정의한 값을 사용해야 합니다. 사용자 프로퍼티에 대한 자세한 내용은 설정하기 > 사용자 프로퍼티를 참고합니다.

url 값을 사용자 정보 저장에 해당하는 /v1/user/update_profile로 지정하여 Kakao.API.request 함수를 호출합니다. 사용자 프로퍼티 저장에 성공하면 응답 코드와 함께 정보 저장에 성공한 사용자의 회원번호를 받습니다.

예를 들어 앱 설정에 nicknameage라는 부가 정보가 있고, 그 정보를 저장 또는 갱신하려면 아래 예제와 같이 요청합니다. 요청 성공 시 응답은 REST API를 참고합니다.

Request
Kakao.API.request({
    url: '/v1/user/update_profile'
});
Parameter
Name Type Description Required
url String /v1/user/update_profile 로 고정 O
success Function(Object) API 호출이 성공할 때 실행되는 콜백 함수 X
fail Function(Object) API 호출이 실패할 때 실행되는 콜백 함수 X
always Function(Object) API 호출 성공 여부에 관계 없이 항상 호출되는 콜백 함수 X
data Object API에 전달할 파라미터, 자세한 내용은 data: 사용자 정보 저장하기 확인 X
data: 사용자 정보 저장하기
Name Type Description Required
properties Object 저장할 사용자 정보, JSON 형식의 키와 값 쌍으로 구성
(예: {nickname:'홍길동',age:'22'})
X
Sample: nickname, age 사용자 정보에 저장
Kakao.API.request({
    url: '/v1/user/update_profile',
    data: {
        properties: {
            nickname: '홍길동',
            age: '22'
        },
    },
    success: function(response) {
        console.log(response);
    },
    fail: function(error) {
        console.log(error);
    }
});

추가 항목 동의 받기

동의 항목 설정 필요

이 API를 사용하려면 동의 항목 설정을 참고하여 필요한 동의 항목을 설정해야 합니다.

추가 항목 동의 받기는 사용자가 첫 카카오 로그인 시 동의 화면에서 동의하지 않았지만, 서비스 이용 중 추가로 동의해야 하는 항목을 동의 요청하는 기능입니다. 이해하기 > 추가 항목 동의 받기의 상세 설명을 확인한 후 이 API를 사용해야 합니다.

추가 항목 동의 받기는 로그인에 추가 파라미터를 전달하는 방식으로 사용합니다. 로그인을 시작하는 인가 코드 요청 함수인 authorize 함수를 호출합니다. authorize 호출 시 추가 동의받을 항목의 키를 쉼표(,)로 구분하여 scope 파라미터에 담아 JSON 형식으로 전달합니다.

아래 예제는 scope에 이메일 항목의 키(account_email), 성별 항목의 키(gender)를 전달해 사용자에게 추가 동의를 요청하는 내용을 담고 있습니다.

Request
Kakao.Auth.authorize({
    redirectUri: '{REDIRECT_URI}',
    scope: '{SCOPE}'
});
Parameter
Name Type Description Required
redirectUri String 인가 코드를 받을 URI O
scope String 추가 동의 받을 동의 항목 ID 목록, 하나의 문자열에 여러 개의 ID를 쉼표(,)로 구분하여 전달
동의 항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의 항목] 참고
(예: 'account_email,gender')
O
state String 로그인 과정 중 유지할 수 있는 파라미터 X
Sample: email, gender 제공 동의 요청
Kakao.Auth.authorize({
    redirectUri: '{REDIRECT_URI}',
    scope: 'account_email,gender'
});
Sample: Kakao.Auth.login 함수로 요청할 경우
Kakao.Auth.login({
    scope: 'account_email,gender',
    success: function(response) {
        console.log(response);
    },
    fail: function(error) {
        console.log(error);
    }
});

응답은 REST API > 인가 코드 받기와 같습니다. 요청 시 추가 항목 동의 받을 항목을 포함한 동의 화면이 나타난다면 올바르게 요청한 것입니다. 사용자가 해당 항목에 동의하면 추가 동의가 성공 및 완료되고, 사용자가 취소하면 추가 동의 요청이 실패합니다.

동의 화면을 팝업으로 띄워야 하거나 클라이언트에서 모든 인증 처리를 해야 할 경우 Kakao.Auth.login 함수를 사용할 수도 있습니다.

동의 내역 확인하기

사용자가 동의한 동의 항목의 상세 정보 목록을 조회합니다. [내 애플리케이션] > [카카오 로그인] > [동의 항목]에 설정된 동의 항목의 목록과 사용자가 동의한 동의 항목의 상세 정보를 반환합니다. 사용자가 기존에 동의했던 동의 항목이라면 현재 앱에 사용하도록 설정돼 있지 않아도 응답에 포함됩니다.

url 값을 동의 내역 확인하기에 해당하는 /v2/user/scopes로 지정하여 Kakao.API.request 함수를 호출합니다. 요청 성공 시 응답은 REST API를 참고합니다. 특정 동의 항목의 동의 내역만 확인하려면 scopes 파라미터로 동의 항목의 ID를 지정하여 요청할 수 있으며, 성공 시 응답은 지정된 동의 항목의 정보만 포함합니다.

Request
Kakao.API.request({
    url: '/v2/user/scopes'
});
Parameter
Name Type Description Required
url String /v2/user/scopes 로 고정 O
success Function(Object) API 호출이 성공할 때 실행되는 콜백 함수 X
fail Function(Object) API 호출이 실패할 때 실행되는 콜백 함수 X
always Function(Object) API 호출 성공 여부에 관계 없이 항상 호출되는 콜백 함수 X
data Object API에 전달할 파라미터, 자세한 내용은 data: 동의 내역 확인하기 확인 X
data: 동의 내역 확인하기
Name Type Description Required
scopes String[] 특정 동의 항목에 대한 동의 내역만 불러오려는 경우 사용하는 동의 항목의 ID 목록
동의 항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의 항목] 참고
(예: ["account_email","gender"])
X
Sample
Kakao.API.request({
    url: '/v2/user/scopes',
    success: function(response) {
        console.log(response);
    },
    fail: function(error) {
        console.log(error);
    }
});
Sample: 이메일, 성별 동의 내역 확인하기
Kakao.API.request({
    url: '/v2/user/scopes',
    data: {
        scopes: ["account_email","gender"]
    },
    success: function(response) {
        console.log(response);
    },
    fail: function(error) {
        console.log(error);
    }
});

동의 철회하기

사용자가 동의한 항목에 대해 동의를 철회합니다. 동의 내역 확인하기 API를 통해 조회한 동의 항목 정보 중 동의 철회 가능 여부(revocable) 값이 true인 동의 항목만 철회 가능합니다. 동의 철회가 불가능한 동의 항목을 대상으로 요청한 경우 에러 응답을 받습니다.

url 값을 동의 철회하기에 해당하는 /v2/user/revoke/scopes로 지정하고, scopes 값에 철회할 동의 항목의 ID를 지정하여 Kakao.API.request 함수를 호출합니다. 요청 성공 시 응답은 REST API를 참고합니다.

Request
Kakao.API.request({
    url: '/v2/user/revoke/scopes',
    scopes: '{SCOPES}'
});
Parameter
Name Type Description Required
url String /v2/user/revoke/scopes 로 고정 O
success Function(Object) API 호출이 성공할 때 실행되는 콜백 함수 X
fail Function(Object) API 호출이 실패할 때 실행되는 콜백 함수 X
always Function(Object) API 호출 성공 여부에 관계 없이 항상 호출되는 콜백 함수 X
data Object API에 전달할 파라미터, 자세한 내용은 data: 동의 철회하기 확인 O
data: 동의 철회하기
Name Type Description Required
scopes String[] 동의를 철회할 동의 항목 ID 목록
동의 내역 확인하기 API 응답에서 동의 철회 가능 여부(revocable) 값이 true인 동의 항목만 철회 가능
동의 항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의 항목] 참고
(예: ["account_email","gender"])
O
Sample
Kakao.API.request({
    url: '/v2/user/revoke/scopes',
    data: {
        scopes: ["account_email","gender"]
    },
    success: function(response) {
        console.log(response);
    },
    fail: function(error) {
        console.log(error);
    }
});

고급: 팝업 방식으로 로그인

카카오 로그인 동의 화면을 팝업으로 띄우거나 클라이언트에서 모든 인증 처리를 하고 싶은 경우 Kakao.Auth.login 함수를 사용할 수 있습니다.

클릭 이벤트 핸들러에서 함수를 호출하면 카카오 로그인 동의 화면을 띄울 수 있으며, 동의 화면을 통해 사용자로부터 사용자 정보 및 기능 활용 동의를 받을 수 있습니다.

함수 호출 시 팝업으로 카카오 로그인 동의 화면이 표시됩니다. 로그인 요청 결과 토큰이 발급되며, 이 토큰은 SDK 내부적으로 사용되고 있기 때문에 별도의 처리가 필요하지 않습니다.

로그인 성공 시 서비스의 로그인 및 회원 가입 처리가 필요합니다. 인증 성공 시 서비스의 로그인 처리는 success 콜백 함수를 사용해야 합니다.

Parameter
Name Type Description Required
success Function(Object) 로그인이 성공할 경우 토큰을 받을 콜백 함수 X
fail Function(Object) 로그인이 실패할 경우 에러를 받을 콜백 함수 X
always Function(Object) 로그인 성공 여부에 관계 없이 항상 호출되는 함수 X
scope String 추가 항목 동의 받기 요청 시 사용
추가 동의 받을 동의 항목 ID 목록, 하나의 문자열에 여러 개의 ID를 쉼표(,)로 구분하여 전달
동의 항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의 항목] 참고
(예: 'account_email,gender')
X
persistAccessToken Boolean 세션이 종료된 뒤에도 액세스 토큰을 사용할 수 있도록 로컬 스토리지에 저장합니다. (기본값: true) X
throughTalk Boolean 간편 로그인 사용 여부 (기본값: true) X
Sample
Kakao.Auth.login({
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
});

다음은 로그인 버튼에 이벤트 핸들러를 등록해주는 함수에 대한 예제입니다. createLoginButton을 사용합니다.

Sample: createLoginButton
Kakao.Auth.createLoginButton({
  container: '#CONTAINER_ID',
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
});
refresh_token, refresh_token_expires_in

JavaScript SDK의 보안 강화를 위해 리프레시 토큰을 취급하지 않도록 수정되었습니다. Kakao.Auth.login 및 Kakao.Auth.createLoginButton 함수를 사용한 로그인 시 발급되는 리프레시 토큰 정보(refresh_token, refresh_token_expires_in)는 2020년 7월 27일 응답에서 제외되었습니다. 서비스에서 리프레시 토큰을 사용하고 있다면 Kakao.Auth.authorize 함수를 사용해서 인가 코드 요청을 하고, REST API로 토큰 받기를 사용하도록 업데이트해야 합니다. 자세한 내용은 공지사항을 참고합니다.

더보기