이 문서는 카카오 로그인 관련 추가 정보를 안내합니다.
이 문서의 API와 필드 명칭은 REST API를 기준으로 설명합니다. 다른 개발 플랫폼 내 명칭은 일부 상이할 수 있으므로 해당 개발 문서의 내용을 참고합니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
카카오 API 플랫폼에서 제공하는 로그인의 추가 정보를 안내합니다.
카카오 로그인 요청 시 브라우저에 카카오계정 간편로그인 정보가 있으면 계정 선택 화면을 표시하는 추가 기능입니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
prompt
파라미터 값을 select_account
으로 지정해 요청합니다.카카오 로그인으로 가입한 서비스 회원이 카카오톡 인앱브라우저로 서비스 페이지 진입 시, 로그인된 페이지로 바로 이동시키는 추가 기능입니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
UserAgent
값의 KAKAOTALK
포함 여부를 확인해 사용자의 카카오톡 인앱브라우저 사용 여부를 확인합니다. 카카오톡에서 자동 로그인은 사용자의 브라우저가 카카오톡 인앱브라우저인 경우만 사용할 수 있습니다.prompt
파라미터 값을 none
으로 지정해 요청합니다.consent_required
에러 응답: 비회원, 사용자에게 로그인되지 않은 상태의 서비스 페이지 표시카카오톡 인앱브라우저는 카카오톡 안에서 열리는 내장 브라우저로 UserAgent
값에 KAKAOTALK
문구를 포함합니다. (참고: User agent, User agent header)
브라우저 | UserAgent 예시 |
---|---|
Android 카카오톡 인앱브라우저 | Mozilla/5.0 (Linux; Android 14; SM-S908N Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/126.0.6478.134 Mobile Safari/537.36 KAKAOTALK/10.8.3 (INAPP) |
iOS 카카오톡 인앱브라우저 | Mozilla/5.0 (iPhone; CPU iPhone OS 17_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 Safari/604.1 KAKAOTALK/10.8.2 (INAPP) |
사용자 카카오계정의 서비스 로그인 여부에 상관없이 카카오계정 로그인 요청 페이지를 표시해 카카오계정으로 로그인을 요청하는 추가 기능입니다.
서비스가 인가 코드 받기 API의 prompt
파라미터 값을 login
으로 지정해 요청하면, 사용자는 인증부터 로그인 절차를 다시 수행해야 합니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
사용자에게 먼저 카카오계정 가입을 요청하고, 회원 가입을 완료하면 카카오 로그인을 요청하는 추가 기능입니다.
서비스가 인가 코드 받기 API의 prompt
파라미터 값을 create
으로 지정해 요청하면, 사용자에게 카카오계정 가입 페이지를 먼저 표시합니다. 회원 가입 완료 후 사용자에게 동의 화면으로 카카오 로그인을 요청합니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
서비스가 원하는 시점에 사용자에게 동의하지 않은 동의항목을 인가 요청하는 추가 기능입니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
아래 단계별 사용 안내를 참고합니다.
1. 요청 필요 동의항목 확인하기서비스는 사용자에게 추가 항목 동의 받기가 필요한 동의항목을 아래 방법으로 확인할 수 있습니다.
scopes
목록과 필요한 동의항목 목록 대조agreed
필드에서 사용자 동의 여부 확인-402
에러 코드가 포함된 API 응답의 required_scopes
필드 확인{
"id": "${USER_ID}",
"scopes": [ // 필요한 동의항목 목록과 대조
{
"id": "profile",
...
"agreed": 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"
]
}
서비스는 인가 코드 받기 API의 scope
파라미터에 동의항목 ID를 지정해 요청합니다. 동의항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의항목] 메뉴의 각 동의항목 [ID], 또는 -402
에러 응답의 required_scopes
값을 사용합니다. 인가 코드 받기 API의 scope 파라미터의 내용을 함께 확인합니다.
서비스가 추가 항목 동의 받기를 요청하면 사용자는 필요한 동의항목에 동의하거나, 동의하지 않고 취소 버튼을 눌러 동의 화면을 닫을 수 있습니다. 아래 사용자 동의 여부별 처리 방법을 참고해 서비스를 제공합니다.
scope
값으로 필요한 동의항목의 동의 완료 여부 확인access_denied
에러 응답 반환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는 서비스에서 매번 동의항목을 지정할 필요가 없도록, scope
파라미터 미포함 요청 시 앱에 설정된 동의항목 ID를 해당 파라미터의 기본값으로 적용합니다.
하지만, scope
파라미터를 포함한 인가 코드 받기 API 요청을 의미하는 추가 항목 동의 받기는 기본값을 적용할 수 없기 때문에 동의항목 ID를 직접 지정해야 합니다. 이 경우, OpenID Connect를 활성화한 앱은 scope
파라미터의 값에 openid
를 포함해야 토큰 받기 API 요청 시 ID 토큰을 발급받을 수 있습니다.
아래 OpenID Connect 활성화와 scope
파라미터 포함 여부에 따른 카카오 로그인 동작 표를 참고합니다.
scope 파라미터 |
일반 앱의 동의화면 | OpenID Connect 활성화 앱의 토큰 발급 |
---|---|---|
미포함 | 앱에 [필수 동의] 또는 [선택 동의]로 설정된 동의항목으로 구성된 동의 화면 표시 | 토큰 받기 요청 시 ID 토큰 발급 |
포함 (추가 항목 동의 받기) |
scope 파라미터에 포함한 동의항목만으로 구성된 동의 화면 표시 |
scope 파라미터 값에 openid 를 포함해야 토큰 받기 요청 시 ID 토큰 발급 |
카카오 로그인 요청 시 전달한 ID 값을 카카오계정 로그인 페이지에 자동 입력해 기존 사용자가 쉽게 다시 로그인 할 수 있도록 돕는 추가 기능입니다.
서비스가 인가 코드 받기 API의 login_hint
파라미터 값을 ID 항목에 자동 입력할 값으로 지정해 요청하면, 카카오계정 로그인 페이지에 해당 값이 자동 입력됩니다. 로그인하지 않은 사용자에게 카카오계정 로그인 페이지를 표시하는 상황에서만 동작합니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
카카오싱크를 도입한 서비스만 사용할 수 있는 기능입니다.
카카오 로그인 동의 화면에 서비스 약관과 동의항목을 함께 인가 요청하는 추가 기능입니다.
서비스가 간편가입을 사용 설정하면, 사용자는 카카오 로그인 동의 화면에서 동의항목과 서비스 약관에 한 번에 동의하고, 별도의 정보 입력 없이 서비스에 가입할 수 있습니다. 서비스는 서비스 약관 운용의 내용을 반드시 확인하고 준수해야 합니다.
설정 방법은 설정하기에서, 플랫폼별 사용 방법은 카카오싱크 시작하기와 개발 가이드에서 확인할 수 있습니다.
서비스 약관은 카카오가 아닌 서비스에 대한 사용자 의사표시를 위한 것으로, 관리와 사용에 대한 모든 책임은 서비스에 있습니다. 관련 피해가 발생하지 않도록 서비스 약관 운용을 반드시 확인하고 준수해야 합니다.
간편가입을 활성화한 서비스만 사용할 수 있는 기능입니다.
서비스 앱에 등록한 서비스 약관을 지정해 사용자에게 인가를 요청하는 추가 기능입니다. 사용자의 서비스 가입 유형에 따라 특정 서비스 약관 동의가 필요한 경우 사용합니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
service_terms
파라미터에 서비스 약관 태그를 지정해 요청합니다. [필수 동의]로 설정된 서비스 약관을 하나 이상 지정해야 합니다.OpenID Connect를 활성화한 서비스만 사용할 수 있는 기능입니다.
서비스가 로그인 세션 대신 사용 가능한 ID 토큰을 발급하는 추가 기능입니다.
OpenID Connect를 활성화한 서비스는 별도의 추가 파라미터 없이 토큰 받기 API 요청으로 ID 토큰을 발급받을 수 있습니다. ID 토큰 재생 공격을 방지하기 위한 nonce
파라미터를 함께 사용할 것을 권장합니다. (참고: 보안을 위한 파라미터)
설정 방법은 설정하기에서, 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
카카오 API 플랫폼에서 제공하는 연결의 추가 정보를 안내합니다.
카카오 API 플랫폼은 사용자가 연결된 앱 정보 확인, 연결 끊기, [선택 동의] 동의항목의 동의 철회를 직접 할 수 있는 연결된 서비스 관리 기능을 제공합니다. 사용자는 아래 경로에서 연결된 서비스 관리에 접근할 수 있습니다.
서비스의 연결 끊기 API 요청을 제외한 연결 끊기 발생 사실을 서비스 서버로 전달하는 기능입니다. 아래는 연결 끊기 알림으로 전달하는 연결 끊기 유형입니다.
카카오 API 플랫폼은 연결 끊기 처리 후 연결 끊기 알림을 전달합니다. 서비스 서버에서 연결 끊기 알림을 받은 것은 이미 사용자의 카카오계정과 서비스 앱 간 연결이 끊겼음을 의미하므로, 서비스에서도 회원 탈퇴 시 정보 파기를 포함한 개인정보 처리방침에 따른 조치와 회원 탈퇴 처리 후 카카오 API 플랫폼 서버로 응답해야 합니다.
연결 끊기 알림의 설정 방법은 설정하기에서, 개발 문서는 연결 끊기 알림에서 확인할 수 있습니다.
사용자와 서비스 앱 간 자동 연결 기능을 사용하지 않도록 설정한 경우, 원하는 시점에 사용자와 앱을 수동으로 연결할 수 있도록 제공하는 추가 기능입니다. 개발 문서는 고급: 연결하기에서 확인할 수 있습니다.
자동 연결을 사용하지 않는 서비스는 사용자의 서비스 가입 상태와 앱 연결 상태가 일치하는지 확인하고 반드시 직접 연결하기, 연결 끊기 API로 사용자의 연결 상태를 관리해야 하기 때문에, 불가피한 경우가 아니라면 기본 설정인 자동 연결 사용을 권장합니다.
카카오 API 플랫폼에서 제공하는 로그아웃의 추가 정보를 안내합니다.
사용자가 서비스에서 로그아웃 요청 시 서비스만 로그아웃할 것인지, 또는 카카오계정도 함께 로그아웃할 것인지 선택 가능한 연결 페이지를 제공하는 추가 기능입니다. 설정 방법은 Logout Redirect URI 등록에서, 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
항목 | 로그아웃 | 카카오계정과 함께 로그아웃 |
---|---|---|
로그아웃 호출 앱의 토큰 | 만료 | 만료 |
웹 브라우저의 카카오계정 로그인 상태 | 유지 | 만료 |
특징 | 서비스 로그아웃과 별도로 사용자가 카카오계정 로그아웃 수행 필요 | 카카오계정 로그아웃 후 서비스 로그아웃 페이지로 리다이렉트(Redirect) 처리 |
서비스가 카카오 API 플랫폼의 사용자 동의 필요 정보 또는 접근권한 필요 기능을 제공받기 위해 필요한 앱 설정 항목으로, 사용자 동의 필요 자원을 받기 위한 수단입니다.
카카오 API 플랫폼은 서비스가 설정한 동의항목으로 동의 화면을 구성해 로그인 시 사용자에게 인가를 요청하고, 동의받은 자원을 서비스에 제공합니다. 회원 체계가 없거나 사용자 정보를 활용하지 않는 서비스라면 동의항목 설정 없이 카카오 로그인을 사용할 수 있습니다. 앱에 설정된 동의항목이 없는 경우, 카카오 로그인 동의 화면은 서비스의 앱과 사용자의 연결에 대한 안내만 포함합니다.
서비스 앱에 동의항목을 설정하는 방법은 설정하기를 참고합니다.
서비스 운영 중 추가 설정한 동의항목이거나, 사용자가 카카오 로그인 및 서비스 가입 시 동의하지 않은 동의항목이라도 추가 항목 동의 받기로 동의받을 수 있습니다.
사용자에게 인가를 요청할 동의항목의 동의 요청 방식을 조정하는 설정입니다. 아래 표에서 자세한 내용을 확인합니다.
동의 단계 | 설명 |
---|---|
필수 동의 | 카카오 로그인 동의화면에서 사용자가 반드시 동의해야 합니다. 사용자가 동의하지 않으면 카카오 로그인을 완료할 수 없습니다. 필수 동의 설정 권한을 획득하면 선택 동의, 이용 중 동의 설정 권한도 함께 획득합니다. |
선택 동의 | 카카오 로그인 동의화면에서 사용자가 선택적으로 동의할 수 있습니다. 사용자가 동의하지 않아도 카카오 로그인을 완료할 수 있습니다. 사용자가 동의하지 않은 경우, 필요한 시점에 추가 항목 동의 받기으로 다시 동의를 요청할 수 있습니다. |
이용 중 동의 | 카카오 로그인 동의화면에서 사용자에게 동의를 요청하지 않습니다. 서비스에서 자원이 필요한 시점에 추가 항목 동의 받기으로 동의를 요청해야 합니다. 서비스의 특정 기능에만 필요한 자원에 설정합니다. |
권한이 필요한 동의항목은 앱 권한 신청으로 권한을 받아야 [필수 동의] 또는 [선택 동의] 동의 단계로 설정할 수 있습니다. 일부 항목은 카카오싱크 도입 후 설정할 수 있습니다. 카카오싱크의 설명과 도입 안내는 시작하기를 참고합니다.
사용 권한이 필요한 동의항목을 별도의 사용 권한 없이도 설정할 수 있지만, 아래 목록 중 하나 이상의 기능 제한이 적용됩니다.
서비스는 기능 제한으로 제공하는 동의 단계를 이용해 서비스의 기능을 구현한 후, 카카오 API 플랫폼에 심사를 요청하고 승인받아야 사용 권한을 획득할 수 있습니다. 아래 모든 사용자를 대상으로 서비스를 제공하기 위한 절차를 참고합니다.
테스트 앱(테스트 애플리케이션) 용으로 제공하는 권한입니다.
테스트 앱은 실제 서비스에 사용 중인 앱에 영향을 미치지 않고 신규 기능이나 업데이트를 개발하기 위해 사용합니다. 원본 앱이 가진 권한과 테스트 앱용 권한을 검수 신청 전에 함께 활용할 수 있습니다. 자세한 내용은 테스트 앱을 참고합니다.
서비스가 카카오 API 플랫폼에서 특정 사용자 동의 필요 정보를 제공받기 위해 앱에 설정해야 하는 동의항목 목록입니다.
이름(ID ) |
설명 | 지원 동의 단계와 필요 권한 | 관련 API |
---|---|---|---|
닉네임 ( profile_nickname ) |
카카오계정 프로필 닉네임 | 필수, 선택, 이용 중 동의: 기본 제공 | 사용자 정보 가져오기 카카오톡 프로필 가져오기 |
프로필 사진 ( profile_image ) |
카카오계정 프로필 사진 구성: 카카오계정 프로필 사진 URL, 썸네일 이미지 URL |
필수, 선택, 이용 중 동의: 기본 제공 | 사용자 정보 가져오기 카카오톡 프로필 가져오기 |
카카오계정(이메일) ( account_email ) |
카카오계정 대표 이메일 서비스에서 참고할 수 있는 이메일 인증 여부 제공 구성: 대표 이메일, 이메일 인증 여부, 이메일 유효 여부, 사용자 동의 시 정보 제공 가능 여부 비고: 이메일 사용 시 주의사항 |
필수, 선택, 이용 중 동의: 비즈 앱, 테스트 앱 | 사용자 정보 가져오기 |
이름 ( name ) |
카카오계정 이름 | 필수, 선택, 이용 중 동의: 동의 단계 설정 권한, 테스트 앱 | 사용자 정보 가져오기 |
성별 ( gender ) |
카카오계정의 성별 구성: 성별, 사용자 동의 시 정보 제공 가능 여부 |
필수, 선택, 이용 중 동의: 동의 단계 설정 권한, 테스트 앱 | 사용자 정보 가져오기 |
연령대 ( age_range ) |
카카오계정의 연령대, 한국 나이 기준 14세 미만, 14세 이상, 20대, 30대 등 대략적인 나이 구성: 연령대, 사용자 동의 시 정보 제공 가능 여부 |
필수, 선택, 이용 중 동의: 동의 단계 설정 권한, 테스트 앱 | 사용자 정보 가져오기 |
생일 ( birthday ) |
카카오계정의 생일 구성: 생일, 사용자 동의 시 정보 제공 가능 여부 |
필수, 선택, 이용 중 동의: 동의 단계 설정 권한, 테스트 앱 | 사용자 정보 가져오기 |
출생 연도 ( birthyear ) |
카카오계정의 출생 연도 구성: 태어난 해, 사용자 동의 시 정보 제공 가능 여부 |
필수, 선택, 이용 중 동의: 동의 단계 설정 권한, 테스트 앱 | 사용자 정보 가져오기 |
카카오계정(전화번호) ( phone_number ) |
카카오계정과 연결된 카카오톡에 등록된 전화번호 구성: 카카오톡 전화번호, 사용자 동의 시 정보 제공 가능 여부 주의: 카카오계정으로 수집 후 제공 설정 불가능 |
필수, 선택, 이용 중 동의: 동의 단계 설정 권한, 테스트 앱 | 사용자 정보 가져오기 |
CI(연계정보) ( account_ci ) |
카카오계정의 암호화된 이용자 확인 값 기존 회원과 대조 등 최소 목적의 참고용으로 제공 구성: 연계정보, 발급 시각, 사용자 동의 시 정보 제공 가능 여부 주의: 카카오는 본인인증기관이 아니므로 카카오계정의 연계정보로 서비스의 본인 인증을 대신할 수 없음 |
필수, 선택, 이용 중 동의: 동의 단계 설정 권한 | 사용자 정보 가져오기 |
배송지정보(수령인명, 배송지 주소, 전화번호) ( shipping_address ) |
카카오계정의 배송지 정보 구성: 수령인 이름, 수령인 연락처, 주소, 주소 유형, 우편번호 |
필수, 선택, 이용 중 동의: 동의 단계 설정 권한, 테스트 앱 | 배송지(REST API, JavaScript, Android, iOS, Flutter) |
카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함) ( friends ) |
카카오계정의 카카오톡 친구 정보 목록 구성: 친구 정보, 친구 수 |
필수 동의: 설정 불가 선택 동의: 사용 권한 신청 이용 중 동의: 기능 제한 제공, 사용 권한 신청 |
카카오톡 친구 목록 가져오기 |
카카오톡 채널 추가 상태 및 내역 ( plusfriends ) |
사용자와 서비스 앱에 연결된 카카오톡 채널의 친구 관계 구성: 채널 관계, 채널 추가 시간, 채널 수정 시간 |
필수 동의: 카카오톡 채널 연결 | 카카오톡 채널 관계 확인하기 |
보안 이벤트 정보 제공 ( openid_sse ) |
사용자의 보안 이벤트 정보 구성: 보안 이벤트 정보 |
필수 동의: 설정 불가 선택 동의: 사용 권한 신청 이용 중 동의: 사용 권한 신청 비고: OAUTH 카테고리는 기본 제공 |
보안 이벤트 구독 |
* 프로필 정보(닉네임/프로필 사진): Deprecated, [닉네임]과 [프로필 사진]으로 분리하여 제공, 공지 참고
서비스에서 카카오 API 플랫폼의 특정 접근권한 필요 기능을 사용하기 위해 앱에 설정해야 하는 동의항목 목록입니다.
이름(ID ) |
지원 동의 단계와 필요 권한 | 관련 API |
---|---|---|
카카오톡 메시지 전송 ( talk_message ) |
필수 동의: 설정 불가 선택 동의, 이용 중 동의: 기능 제한 제공, 사용 권한 신청 |
카카오톡 메시지 |
톡캘린더 및 일정 생성, 조회, 편집/삭제 ( talk_calendar ) |
필수 동의: 설정 불가 선택 동의: 사용 권한 신청 이용 중 동의: 기능 제한 제공, 사용 권한 신청 |
톡캘린더 |
톡캘린더 내 할 일 생성, 조회, 편집/삭제 ( talk_calendar_task ) |
필수 동의: 설정 불가 선택 동의: 사용 권한 신청 이용 중 동의: 기능 제한 제공, 사용 권한 신청 |
톡캘린더 |
카카오 API 플랫폼은 사용자가 동의하지 않은 동의항목에 해당하는 자원은 제공하지 않으며 에러 응답을 반환합니다. 에러 발생 시 추가 항목 동의 받기로 사용자에게 동의받아야 합니다. 서비스에 반드시 필요한 자원은 해당 동의항목을 [필수 동의]로 설정하고 카카오계정으로 수집 후 제공 설정을 사용하거나, 자원을 제공받지 못한 경우에 대한 예외 처리를 해야 합니다.
사용자가 동의한 동의항목에 해당하는 자원도, 카카오 API 플랫폼이 보유하고 있지 않거나 수집 또는 제공이 불가능한 경우 제공하지 못할 수 있습니다. 자세한 내용은 사용자 동의 시 정보 제공 가능 여부를 참고합니다.
카카오계정에 없는 사용자 동의 필요 정보를 사용자에게 동의 화면으로 제3자 제공 동의를 받은 후, 수집해 서비스에 제공하는 추가 기능입니다. 설정 방법은 설정하기에서 확인할 수 있습니다.
사용자는 카카오계정 웹사이트의 [계정 이용]이나 카카오톡의 [설정] > [카카오계정] > [연결된 서비스 관리] 메뉴에서 선택 동의항목에 대한 동의를 철회할 수 있습니다. 이때 동의 철회하기 API가 호출되며, 서비스에서도 해당 API를 요청해 사용자 동의를 철회할 수 있습니다. (참고: 연결된 서비스 관리)
개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
카카오 API 플랫폼에서 서비스에 제공하는 사용자 정보에 대해 안내합니다. 제공하지 않는 정보는 서비스가 직접 수집해야 합니다.
카카오 API 플랫폼을 이용하는 모든 서비스는 안전하게 보호하고 관리해야 합니다. 사용자 정보 관리에서 자세한 내용을 확인합니다.
모든 서비스에 기본으로 제공하는 정보입니다. 사용자 정보 가져오기 API의 응답으로 제공합니다.
사용자 정보 | 설명 |
---|---|
회원번호 | 각 서비스 앱 내 사용자 고유 ID, 카카오계정과 서비스 앱 연결 시 부여 카카오 API 호출 시 사용자 식별자로 사용 권장 |
연결 시각 | 사용자가 서비스 앱에 연결된 시각 |
간편가입 시각 | 사용자가 서비스 앱에 간편가입으로 처음 로그인한 시각 간편가입 사용자만 제공하며 연결 시각과 동일 |
사용자 프로퍼티 | 서비스에서 사용자 정보 저장하기 API로 카카오 API 플랫폼에 저장한 사용자 정보 |
서비스가 사용자별 정보를 사용자 정보 저장하기 API로 카카오 API 플랫폼에 저장하고, 사용자 정보 가져오기 API로 응답받을 수 있도록 제공하는 추가 기능입니다. 설정 방법은 설정하기에서, 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
대응하는 동의항목을 인가받은 서비스에 제공하는 정보입니다. 개인정보 동의항목에서 전체 목록과 자세한 내용을 확인할 수 있습니다.
사용자 동의 필요 정보 중 하나인 배송지에 대해 안내합니다.
카카오 API 플랫폼은 카카오 로그인한 사용자의 카카오계정에 등록된 배송지 정보를 제공합니다. 배송지는 Kakao SDK(JavaScript, Android, iOS, Flutter) 또는 REST API로 요청 가능하며, Kakao SDK를 사용하면 더욱 편리하게 배송지 활용 기능을 구현할 수 있습니다. 개발 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
아래 개발 플랫폼별 세부 내용을 확인합니다.
개발 플랫폼 | 설명 |
---|---|
REST API | 배송지 가져오기 API로 사용자의 전체 배송지 목록, 또는 특정 배송지 정보 제공 사용자가 전체 배송지 목록을 조회하고, 서비스에 제공할 배송지를 선택하는 배송지 목록 UI 직접 구현 필요 |
Kakao SDK | 배송지 가져오기 API와 함께 배송지 선택하기 API 추가 제공 배송지 선택하기 API 사용 시, 배송지 피커로 사용자가 서비스에 제공할 배송지를 선택할 수 있음 서비스는 특정 배송지 1건만 제공받아, 개인정보 취급을 최소화하고 UI 처리를 간소화할 수 있음 |
Kakao SDK 사용 시, 배송지 피커를 활용한 배송지 요청 순서는 아래 시퀀스 다이어그램을 참고합니다.
위 과정을 수행하는 동안, 사용자 카카오계정의 상태나 동작 등으로 인한 에러가 반환될 수 있습니다. 문제 해결을 참고해 예외 처리 및 재요청합니다.
배송지 가져오기 요청 시 배송지 ID를 지정하지 않으면 사용자의 전체 배송지를 제공받을 수 있습니다. 이 경우, 응답으로 받은 여러 배송지를 서비스 UI에 목록 형태로 표시하고 사용자가 선택할 수 있도록 하는 기능 구현이 필요합니다.
카카오 API 플랫폼은 개인정보 동의항목에 대응하는 사용자 정보가 포함된 API 응답에, 해당 사용자 정보의 제공 가능 여부 필드를 함께 제공합니다.
사용자 정보의 응답 필드명이 ${FIELD_NAME}
인 경우 제공 가능 여부 응답의 필드명은 ${FIELD_NAME}_needs_agreement
입니다. 아래 제공 가능 여부 응답별 세부 내용을 참고합니다.
true
: 제공 가능한 사용자 정보false
: 이미 제공 중 또는 제공 불가 사용자 정보${FIELD_NAME}
항목이 존재하는 경우, 이미 제공 중인 정보${FIELD_NAME}
항목이 없는 경우, 카카오 API 플랫폼에서 제공 불가능한 정보로 서비스에서 자체 수집 필요true
로 응답HTTP/1.1 200 OK
{
...
"kakao_account": {
...
"email_needs_agreement": true // 이메일 동의항목에 사용자 동의 필요
...
}
}
카카오 로그인은 OAuth 2.0 기반의 표준 인증 프로토콜인 OpenID Connect(OIDC)를 지원합니다. OpenID Connect를 서비스에 적용하면 사용자의 로그인을 더 안전하게 처리할 수 있습니다. 설정 방법은 설정하기에서, 플랫폼별 지원 여부와 개발 문서는 지원하는 기능에서 확인할 수 있습니다.
아래 OpenID Connect(OIDC)를 적용한 카카오 로그인 구현 방법을 참고합니다.
1. 메타데이터 확인하기OIDC: 메타데이터 확인하기 API로 카카오 로그인의 OpenID Connect 서비스 제공자 설정을 확인합니다. 카카오 API 플랫폼은 메타데이터(Metadata) 문서로 OpenID Connect Discovery 표준 규격을 준수한 서비스 제공자 설정을 제공합니다.
OpenID Connect 활성화 설정을 참고해 [내 애플리케이션] > [카카오 로그인]에서 [OpenID Connect]를 활성화 후, 각 플랫폼 개발 가이드를 참고하여 카카오 로그인을 구현합니다.
OpenID Connect를 활성화한 앱은 사용자 인증 정보가 담긴 ID 토큰을 액세스 토큰과 함께 발급받고, OIDC: 사용자 정보 가져오기로 표준 규격을 준수한 형태의 사용자 정보를 제공받을 수 있습니다.
발급받은 ID 토큰은 서비스 보안을 위해 유효성을 검증하고 사용해야 합니다. 페이로드 값 확인 시, 필요에 따라 디버깅 목적으로 제공하는 ID 토큰 정보 보기 API를 사용할 수 있습니다. 아래 순서로 ID 토큰을 검증합니다.
페이로드 검증
iss
: https://kauth.kakao.com
와 일치해야 함aud
: 서비스 앱 키와 일치해야 함exp
: 현재 UNIX 타임스탬프(Timestamp)보다 큰 값 필요(ID 토큰의 만료 여부 확인)nonce
: 카카오 로그인 요청 시 전달한 값과 일치해야 함서명 검증
kid
에 해당하는 공개키 값 확인ID 토큰은 서비스의 로그인 세션 대신 사용할 수 있는 JSON Web Token(이하 JWT) 형식의 토큰입니다. 서비스는 ID 토큰에 포함된 사용자 인증 정보를 서비스에 활용하거나, ID 토큰의 유효성을 검증할 수 있습니다. ID 토큰의 만료 시간은 액세스 토큰과 동일합니다.
ID 토큰은 아래 세 가지 영역으로 구성돼 있습니다.
구분 | 설명 |
---|---|
헤더(Header) | ID 토큰의 규격 정보 카카오 로그인을 통해 발급되는 ID 토큰의 헤더는 다음 정보를 포함함 alg : ID 토큰에 적용된 암호화 방식, RS256 으로 고정typ : ID 토큰의 형식, JWT 로 고정kid : ID 토큰 암호화 시 사용된 공개키 ID, OIDC: 공개키 목록 조회하기 API로 ID 토큰별로 사용된 공개키의 값을 확인할 때 필요한 정보 |
페이로드(Payload) | 사용자 인증 정보iss : ID 토큰을 발급한 인증 기관 정보, https://kauth.kakao.com 로 고정aud : ID 토큰이 발급된 앱의 앱 키sub : ID 토큰에 해당하는 사용자의 회원번호iat : ID 토큰 발급 또는 갱신 시각auth_time : 사용자가 카카오 로그인을 통해 인증을 완료한 시각exp : 만료 시간nonce : 카카오 로그인 요청 시 전달받은 임의의 문자열nickname : 닉네임picture : 프로필 사진email : 이메일nickname , picture , email 값 제공은 동의항목 설정 및 사용자 동의 필요자세한 정보는 인가 코드 받기 API 요청과 토큰 받기 API 응답 참고 |
서명(Signature) | 카카오 인증 서버에서 kid 에 해당하는 공개키로 서명한 값RS256 방식으로 암호화된 값으로, ID 토큰 유효성 검증 시 서명 |
ID 토큰은 세 영역의 값을 Base64 인코딩(Encoding) 한 후 온점(.)으로 이어 붙인 하나의 문자열로 생성됩니다. 따라서 온점을 기준으로 각 영역을 분리하고, Base64 디코딩(Decoding)하여 내용을 확인할 수 있습니다. 페이로드와 서명의 검증 방법은 ID 토큰 유효성 검증하기에서 확인할 수 있습니다.
ID 토큰은 OpenID Connect를 활성화한 상태에서 카카오 로그인 시 별도의 파라미터 없이 발급됩니다. 하지만, 추가 항목 동의 받기 API 요청 시에는 scope
파라미터에 openid
값을 전달한 경우에만 ID 토큰을 발급받을 수 있습니다. 인가 코드 받기 API의 scope 파라미터를 참고합니다.
카카오 API 플랫폼에서 제공하는 보안 기능의 추가 정보를 안내합니다.
카카오 로그인은 서비스에 사용자의 보안 이벤트 정보를 전달하는 보안 이벤트 구독 기능을 제공합니다. OpenID 재단의 SSE(Shared Signals and Events) 규격을 바탕으로 설계됐으며, 서비스에서 보다 적극적인 보안 조치를 취할 수 있도록 지원합니다. 자세한 내용은 보안 이벤트 구독에서 확인할 수 있습니다.
REST API 방식으로 카카오 로그인의 토큰 받기와 토큰 갱신하기 API 요청 시, 미리 발급받은 클라이언트 시크릿(Client secret) 코드를 client_secret
파라미터에 포함한 경우에만 성공 응답하도록 설정하는 보안 기능입니다. 설정 방법은 설정하기에서 확인할 수 있습니다.
클라이언트 시크릿 코드는 2년 이하 주기로 갱신할 것을 권장합니다. 클라이언트 시크릿 코드를 전달하지 않았거나 잘못된 값을 전달한 경우 KOE010
에러가 발생합니다.
카카오 로그인은 OAuth 2.0 및 OpenID Connect 표준에 따라, 인가 코드 받기 API에 보안을 위한 파라미터인 state
, nonce
를 제공합니다. 사용자가 안전하게 카카오 로그인을 완료할 수 있도록 해당 파라미터 사용을 권장합니다.
state
는 Cross-Site Request Forgery(CSRF) 공격으로부터 카카오 로그인 요청을 보호하기 위해 사용합니다. state
는 카카오 로그인이 시작될 때부터 완료될 때까지 고유하고 동일한 값을 유지해야 합니다.
nonce
는 OpenID Connect 사용 시 지원하는 파라미터로, ID 토큰 재생 공격을 방지하기 위해 사용합니다. 카카오 로그인 요청 시 전달한 nonce
값이 ID 토큰에 포함되어, 서비스는 ID 토큰 유효성 검증으로 두 값의 일치 여부를 확인해서 ID 토큰 재생 공격을 방지할 수 있습니다.