페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • 설정하기

카카오 로그인

설정하기

이 문서는 카카오 로그인 사용 시 필요한 설정에 대해 안내합니다.

카카오 로그인을 사용하려면 사용 설정, 리다이렉트 URI는 반드시 완료해야 합니다. OpenID Connect는 필요 시 설정합니다.

제목 태그

각 제목에 부착된 태그(Tag)는 아래와 같은 의미입니다.

태그 설명
필수 반드시 필요한 설정입니다.

일반

사용 설정 필수

카카오 로그인을 사용하려면 앱 관리 페이지의 [카카오 로그인] > [사용 설정]의 [상태]를 [ON]으로 설정해야 합니다. [상태]가 [OFF]인 경우, 카카오 로그인 요청 시 KOE004 에러가 발생합니다.

카카오 로그인 사용 설정

OpenID Connect

OpenID Connect를 활성화하면 카카오 로그인 시 액세스 토큰과 ID 토큰을 함께 발급받을 수 있습니다. 앱 관리 페이지의 [카카오 로그인] > [OpenID Connect]에서 아래 순서로 OpenID Connect를 사용하도록 설정할 수 있습니다.

OpenID Connect 사용 설정
  1. 🅐 [상태]를 [ON]으로 설정해 카카오 로그인을 활성화합니다. 카카오 로그인을 사용 중인 경우에만 OpenID Connect를 사용할 수 있습니다.
  2. 🅑 [상태]를 [ON]으로 설정해 OpenID Connect를 활성화합니다.
주의: OpenID Connect 비활성화

[OpenID Connect] 설정을 [OFF]로 변경하면, 설정 변경 시점부터 ID 토큰이 발급되지 않습니다. 서비스에서 ID 토큰을 사용 중인 경우에는 로그인이 불가능할 수 있으므로 주의합니다.

리다이렉트 URI 필수

REST API 또는 Kakao SDK for JavaScript로 카카오 로그인을 사용한다면 리다이렉트 URI를 반드시 등록해야 합니다. 리다이렉트 URI는 OAuth 2.0을 기반으로 동작하는 카카오 로그인의 핵심 요소입니다. 카카오 로그인은 서비스 로그인 과정에서 리다이렉트 URI로 서비스에서 요청한 인가 코드와 토큰을 전달합니다. 리다이렉트 URI가 올바르지 않은 경우, 카카오 로그인 시 KOE006 에러가 발생합니다.

앱 관리 페이지의 [카카오 로그인] > [일반] > [리다이렉트 URI]에서 리다이렉트 URI를 등록할 수 있습니다.

리다이렉트 URI 등록 화면

리다이렉트 URI는 아래 규칙에 맞게 등록해야 합니다.

  • 최대 10개까지 등록할 수 있습니다.
  • HTTP 및 HTTPS 프로토콜만 지원합니다.
  • HTTP, HTTPS 프로토콜을 구분하므로 각각 등록해야 합니다.
참고: 리다이렉트 URI 활용 안내
  • 여러 개의 리다이렉트 URI를 등록해 사용자를 카카오 로그인 후 상황에 맞는 서비스 페이지(랜딩 페이지, 추가 정보 입력 페이지 등)로 이동시킬 수 있습니다.
  • 리다이렉트 URI는 경로(path)에 임의의 파라미터를 포함할 수 없습니다. 로그인 과정 중 특정 정보를 유지하거나 전달하려면 state 파라미터를 활용합니다. state 파라미터에 대한 정보는 인가 코드 요청에서 확인할 수 있습니다.
  • 비즈 앱은 리다이렉트 URI의 도메인에 와일드카드 문자를 포함할 수 있습니다. 자세한 안내는 와일드카드 서브 도메인을 참고합니다.
  • 10개를 초과하는 리다이렉트 URI 등록이 필요한 경우, 데브톡으로 문의합니다.

Client Secret

카카오 로그인의 보안을 강화하기 위해 클라이언트 시크릿(Client Secret)을 사용할 수 있습니다.

앱 관리 페이지의 [카카오 로그인] > [일반] > [Client Secret]에서 [클라이언트 시크릿 발급]을 선택합니다.

Client Secret 설정 화면

🅐 삭제: 발급 받은 클라이언트 시크릿 삭제 🅑 재발급: 새로운 클라이언트 시크릿 발급, 클라이언트 시크릿을 갱신하거나 유출이 의심되는 상황에서 사용 🅒 설정: 클라이언트 상태 변경, [사용함]인 상태여야 해당 클라이언트 시크릿 사용 가능

주의: 삭제나 재발급 시 유의사항

클라이언트 시크릿을 삭제하거나 재발급하면 이전 코드는 복구할 수 없습니다. 이전 기존 클라이언트 시크릿 사용한 토큰 발급 요청이 모두 실패하므로, 운영 중인 서비스에서는 주의가 필요합니다.

참고: 운영 중 클라이언트 시크릿 코드 변경 방법
  1. 🅒 [설정]을 선택해 [상태]를 [사용 안 함]으로 변경
  2. 🅑 [재발급]을 선택해 새로운 클라이언트 시크릿 코드 발급
  3. 서비스에 새로운 클라이언트 시크릿 코드 적용
  4. 🅒 [설정]을 선택해 [상태]를 [사용함]으로 선택

동의항목 필수

동의항목은 서비스가 특정 정보 조회 또는 기능 사용을 사용자에게 허가받기 위한 설정입니다. 동의항목에서 자세한 내용과 전체 목록을 확인할 수 있습니다.

앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 동의항목을 사용하도록 설정할 수 있습니다. 자세한 설정 방법은 아래 항목별 설명을 확인합니다.

추가 기능 신청

일부 동의항목은 추가 기능 사용 권한이 있어야 설정할 수 있습니다. 동의항목을 설정하기 위해 필요한 항목별 권한은 개인정보 동의항목, 접근권한 동의항목에서 확인할 수 있습니다.

동의항목 권한 신청 방법은 추가 기능 신청을 확인합니다.

동의항목 설정

서비스의 정보 조회 또는 기능 사용을 위한 동의항목을 설정할 수 있습니다. 아래 단계별 안내를 참고합니다.

1. 동의항목 확인
동의항목 설정 화면

🅐 개인정보 동의항목과 🅑 접근권한 동의항목을 참고해 서비스에서 사용자에게 동의가 필요한 항목이 무엇인지 확인합니다.

[개인정보] 또는 [접근 권한]에서 원하는 동의항목의 [설정]을 선택합니다. 일부 동의항목은 설정하기 위해 먼저 추가 기능 신청을 완료해야 합니다.

2. 동의항목 설정
동의항목 설정 화면

🅐 [동의 단계]를 선택하고 🅑 [동의 목적]에 사용 목적을 작성한 뒤 [저장]을 선택합니다.

🅒 [카카오계정으로 수집 후 제공]의 체크박스를 선택하면, 카카오계정에 등록되지 않은 정보도 사용자에게 동의받은 후 수집해 제공합니다. 해당 기능에 대한 자세한 내용은 카카오계정으로 수집 후 제공을 확인합니다.

3. 동의 화면 미리보기

앱 관리 페이지의 [카카오 로그인] > [동의항목]의 하단에서 [동의 화면 미리보기]를 눌러 앱의 설정을 반영한 동의 화면을 미리 확인할 수 있습니다.

동의 화면 미리보기

대표 채널

대표 채널은 카카오 로그인 시 동의 화면에 노출되는 카카오톡 채널입니다.

동의 화면의 대표 채널 노출 위치
  1. 앱에 카카오톡 채널을 연결합니다.
  2. 앱 관리 페이지의 [카카오 로그인] > [동의항목] > [대표 채널]에서 [대표 채널 선택]을 선택해 연결된 카카오톡 채널 중 하나를 대표 채널로 선택합니다.
동의 화면의 대표 채널 노출 위치

개인정보 국외이전

앱 관리 페이지의 [카카오 로그인] > [동의항목] > [개인정보 국외이전]에서 개인정보 국외이전 정보를 등록할 수 있습니다.

개인정보 국외이전 설정

🅐 이전되는 국가: 개인정보가 이전되는 국가명 입력 🅑 법인명(업체): 개인정보를 이전받는 법인명 입력 🅒 연락처: 정보관리책임자의 이메일, 전화번호, 고객센터 URL 등 개인정보 관련 문의를 위한 🅑의 연락처 입력

입력한 정보로 카카오 로그인 동의 화면에 [개인정보 국외 이전 동의] 필수 동의항목이 추가되며, 사용자는 해당 항목의 [보기]를 선택해 자세한 내용을 확인한 후 동의할 수 있습니다.

간편가입

간편가입 기능을 이용하면 앱에 설정한 서비스 약관을 카카오 로그인 동의 화면에 노출시켜 사용자로부터 쉽게 약관에 동의를 받을할 수 있습니다.

사용 설정 필수

간편가입을 사용하려면 아래 요구사항을 만족해야 합니다.

  1. 추가 기능 신청 자격 확인
  2. 비즈니스 정보 심사 신청
  3. 앱에 카카오톡 채널 연결
  4. 서비스 약관 등록 후, 사용 설정을 [ON]으로 선택
  5. 앱 관리 페이지의 [카카오 로그인] > [간편가입]에서 [사용 설정]을 [ON]으로 설정 (최소 하나의 약관이 활성화되어 있어야 간편가입 설정 가능)
간편가입 설정 화면

서비스 약관 필수

앱 관리 페이지의 [카카오 로그인] > [간편가입]에서 🅐 [서비스 약관 추가]를 눌러 새로운 서비스 약관을 등록할 수 있습니다. 서비스 약관 운용을 준수해야 합니다.

기존 서비스 약관 설정 화면

🅐 서비스 약관 추가: 약관 추가 🅑 만 14세 이상 연령 동의 추가 🅒 사용 중인 약관 목록: 등록한 서비스 약관 중 사용 설정(ON)한 약관 표시 🅓 비활성 서비스 약관: 등록한 서비스 약관 중 사용하지 않는(OFF) 약관 표시 🅔 동의 화면 미리보기: 설정한 약관이 반영된 카카오 로그인 동의 화면 미리보기 창 표시 🅕 순서 변경: 카카오 로그인 동의 화면의 서비스 약관 노출 순서 변경, 상태와 무관하게 지정 가능 🅖 수정: 각 약관에 대한 설정 변경 🅗 사용 설정: 카카오 로그인 동의 화면에 노출 여부 선택

서비스 약관 필요 정보

서비스 약관 추가 시, 아래 정보를 설정해야 합니다.

신규 서비스 약관 등록 화면

🅐 제목: 한국어, 영어 모두 입력 필요 🅑 URL: 약관 내용을 확인할 수 있는 웹 페이지 URL 입력 🅒 동의 단계: 사용자에게 서비스 약관 동의를 요청할 동의 단계 선택(필수 또는 선택 동의항목) 🅓 태그: 각 서비스 약관을 구분하기 위한 고유값을 지정해 입력

항목별 등록 가능 형식은 아래를 참고합니다.

  • 제목
    • 한국어 서비스 약관 제목은 한글, 영문, 숫자, 공백, 키보드에서 직접 입력 가능한 특수문자만 지원(최대 45자)
    • 영어 서비스 약관 제목은 영문, 숫자, 공백, 키보드에서 직접 입력 가능한 특수문자만 지원(최대 100자)
    • 영문 서비스 약관이 없더라도 영어 서비스 약관 제목은 영어로 입력, 영어 약관 제목은 사용자 기기의 언어 설정이 영어일 때 사용됨
  • URL
    • 선택 서비스 약관에 한해 URL 생략 가능
  • 동의 단계
    • 가입 시 반드시 동의해야 하는 서비스 약관은 [필수 동의] 동의항목으로 설정
    • 서비스 제공 범위에 따라 사용자가 추가 동의할 수 있는 서비스 약관은 [선택 동의] 동의항목으로 설정
  • 태그
    • 아래 카카오 API 요청 시 태그 사용, 실제 서비스 개발 시 사용 가능한 값으로 입력
    • 영문, 숫자, 하이픈(-), 언더스코어(_)만 입력 가능
    • ${KEYWORD}_${DATE}, ${KEYWORD}_${ORDER} 등 형식 권장(예: terms_20220701, terms_01)

고급

로그아웃 리다이렉트 URI

앱 관리 페이지의 [카카오 로그인] > [고급] > [로그아웃 리다이렉트 URI]에서 로그아웃 리다이렉트 URI를 등록해 카카오계정과 함께 로그아웃 기능을 사용할 수 있습니다.

로그아웃 리다이렉트 URI 설정 화면

로그아웃 리다이렉트 URI는 HTTP/HTTPS 프로토콜 및 80, 443 포트를 지원하며, HTTP/HTTPS 프로토콜을 구분하므로 각각 등록해야 합니다. 최대 10개의 로그아웃 리다이렉트 URI 등록이 가능하며, 10개 초과 등록이 필요한 경우 데브톡으로 문의합니다.

사용자 프로퍼티

앱 관리 페이지의 [카카오 로그인] > [고급] > [사용자 프로퍼티]에서 사용자 프로퍼티 키를 등록하고 앱에 연결된 멤버를 대상으로 저장된 값을 확인할 수 있습니다. 서비스마다 총 5개의 사용자 프로퍼티 키(사용자 프로퍼티 예약어 제외)를 등록할 수 있습니다.

사용자 프로퍼티 설정 화면

🅐 프로퍼티 추가 🅑 프로퍼티 삭제 🅒 계정 정보: 앱에 연결된 멤버의 계정 정보 🅓 예약된 프로퍼티: 사용자 프로퍼티 예약어와 저장된 값 🅔 사용자 프로퍼티: 추가한 사용자 프로퍼티 키와 저장된 값

참고: 사용자 프로퍼티 예약어

nickname, profile_image, thumbnail_image는 카카오 플랫폼에서 사용하는 예약어이므로 사용자 프로퍼티 키 등록 시 사용할 수 없습니다.

사용자 프로퍼티 프로필 관련 정책 변경

2022년 5월 12일부터 프로필 정보 저장을 위해 기본 제공하던 프로퍼티인 nickname, profile_image, thumbnail_image의 값이 실시간 카카오계정 프로필 값으로 변경되고, 사용자 프로퍼티 저장로 값 업데이트를 지원하지 않습니다. 자세한 사항은 공지를 참고합니다.