[Android] 카카오 소셜 로그인 구현 가이드 — 콘솔 설정부터 연동까지

목차

1. 카카오 개발자 콘솔 앱 등록
2. 카카오 로그인 활성화 및 동의 항목 설정
3. SDK 설치 및 초기화
4. AndroidManifest 설정
5. 로그인 구현 방식 선택
6. 로그인 흐름 이해하기
7. 토큰 관리 흐름
8. 사용자 정보 조회
9. 로그아웃 / 연결 해제
10. 추가 기능
11. 트러블슈팅 — KeyHash 에러

1. 카카오 개발자 콘솔 앱 등록

카카오 로그인을 연동하려면 먼저 카카오 개발자 콘솔에서 앱을 등록해야 합니다.

진행 순서

1. developers.kakao.com에 접속하여 카카오계정으로 로그인합니다.
2. 상단 메뉴에서 [내 애플리케이션] 을 클릭합니다.
3. [애플리케이션 추가하기] 를 선택하고 앱 이름, 사업자명을 입력한 뒤 저장합니다.
4. 생성된 앱을 클릭하면 앱 키 페이지로 진입합니다.

앱 키 확인

앱 키 페이지에서 아래 4가지 키를 확인할 수 있습니다. Android 연동에는 네이티브 앱 키를 사용합니다.

플랫폼 등록

앱 키를 확인했다면 Android 플랫폼을 등록해야 합니다.

1. 좌측 메뉴에서 [앱 설정] > [플랫폼] 으로 이동합니다.
2. [Android 플랫폼 등록] 을 클릭합니다.
3. 아래 정보를 입력합니다.

키 해시 등록 방법

키 해시는 앱의 서명 정보를 카카오 서버에 등록하는 값입니다. 개발 단계에서는 디버그 키 해시를, 배포 시에는 릴리즈 키 해시를 등록해야 합니다. 키 해시가 일치하지 않으면 로그인이 동작하지 않으므로 반드시 정확히 등록해야 합니다.

💡 키 해시는 Android Studio의 터미널 또는 코드 내에서 추출할 수 있습니다. 개발/운영 환경 각각 별도로 등록해야 합니다.

2. 카카오 로그인 활성화 및 동의 항목 설정

플랫폼 등록 후에는 카카오 로그인 기능 자체를 활성화하고, 수집할 사용자 정보를 설정해야 합니다.

카카오 로그인 활성화

1. 좌측 메뉴에서 [제품 설정] > [카카오 로그인] 으로 이동합니다.
2. 상단의 활성화 설정 토글을 ON 으로 변경합니다.
3. Redirect URI를 등록합니다. Android SDK를 사용하는 경우 아래 형식으로 자동 처리되므로, 별도 입력 없이 넘어가도 됩니다.

동의 항목 설정

1. [카카오 로그인] > [동의 항목] 으로 이동합니다.
2. 서비스에 필요한 항목을 선택하고 필수 또는 선택 동의로 지정합니다.

⚠️ 선택 동의 항목은 사용자가 거부해도 서비스 이용에 지장이 없도록 설계해야 합니다. 카카오 정책상 필수 여부를 남용하면 앱 검수에서 반려될 수 있습니다.

3. SDK 설치 및 초기화

콘솔 설정이 완료되면 Android 프로젝트에 SDK를 추가합니다.

저장소 추가

settings.gradle의 저장소 목록에 카카오 Maven 저장소를 추가합니다.

https://devrepo.kakao.com/nexus/content/groups/public/

의존성 추가

build.gradle (app) 에 카카오 로그인 SDK 의존성을 추가합니다. 필요한 기능에 따라 모듈을 선택적으로 추가할 수 있으며, 카카오 로그인만 사용할 경우 v2-user 모듈만 추가하면 됩니다.

SDK 초기화

Application 클래스의 onCreate()에서 네이티브 앱 키로 SDK를 초기화합니다. 이 초기화가 없으면 로그인 API 호출 시 오류가 발생합니다.

4. AndroidManifest 설정

카카오 인증 서버와의 통신을 위해 AndroidManifest.xml에 두 가지를 설정해야 합니다.

리다이렉트 URI 설정

카카오 인증 서버가 인가 코드를 앱으로 전달하려면 앱이 특정 URI를 수신할 수 있어야 합니다. 이를 위해 AuthCodeHandlerActivity를 등록하고, 스킴(scheme)을 kakao + 네이티브 앱 키 형식으로 지정합니다.

예를 들어 네이티브 앱 키가 123456789라면 스킴은 kakao123456789입니다.

⚠️ Android 12(API 31) 이상을 타깃으로 하는 앱은 android:exported="true" 를 반드시 선언해야 합니다. 누락 시 앱이 정상 빌드되어도 로그인이 동작하지 않습니다.

커스텀 URL 스킴 설정 (배송지 API 사용 시만 해당)

배송지 선택 기능을 사용하는 경우에만 AppsHandlerActivity를 추가로 등록합니다.

5. 로그인 구현 방식 선택

카카오 로그인은 총 3가지 방식을 제공합니다. 서비스 특성에 맞는 방식을 선택합니다.

두 방식을 조합해 사용하는 것이 일반적입니다. 카카오톡이 설치된 경우 카카오톡 로그인을 시도하고, 미설치이거나 기술적 오류가 발생하면 카카오계정 로그인으로 전환하는 방식입니다.

// 실전 권장 패턴: 카카오톡 설치 여부에 따라 분기
if (UserApiClient.instance.isKakaoTalkLoginAvailable(context)) {
    // 카카오톡으로 로그인 시도
    // 실패 시 → 취소면 종료, 기술적 오류면 카카오계정으로 폴백
} else {
    // 카카오톡 미설치 → 바로 카카오계정 로그인
}

6. 로그인 흐름 이해하기

카카오 로그인은 내부적으로 OAuth 2.0 인가 코드 방식으로 동작합니다. 전체 흐름은 아래와 같습니다.

사용자 로그인 요청
    │
    ├─ 카카오톡으로 로그인
    │       └─ 카카오톡 앱 실행 → 동의 화면 출력
    │
    └─ 카카오계정으로 로그인
            └─ 기본 브라우저 실행 → 계정 입력 → 동의 화면 출력
    │
    ▼
사용자가 동의 화면에서 [동의하고 계속하기] 선택
    │
    ▼
카카오 인증 서버 → 인가 코드 발급 → 앱으로 리다이렉트
    │
    ▼
Android SDK가 인가 코드로 액세스 토큰 + 리프레시 토큰 자동 발급
    │
    ▼
로그인 완료 (콜백으로 토큰 수신)

동의 화면 처리 시 주의 사항

사용자가 동의 화면에서 필수 항목에 모두 동의해야만 로그인이 완료됩니다. 동의하지 않고 취소한 경우는 에러로 처리되며, 이 경우 재시도 또는 종료 처리를 해야 합니다.

7. 토큰 관리 흐름

로그인 성공 후 발급되는 토큰은 SDK가 기기 내에 자동으로 저장합니다. 앱 재실행 시 매번 로그인을 요구하지 않으려면 아래 흐름으로 토큰 유효성을 먼저 확인해야 합니다.

앱 실행
    │
    ├─ 저장된 토큰 없음 (hasToken() == false)
    │       └─ 로그인 화면으로 이동
    │
    └─ 저장된 토큰 있음 (hasToken() == true)
            │
            └─ 액세스 토큰 유효성 검사 (accessTokenInfo())
                    │
                    ├─ 유효함 → 바로 서비스 진입 (로그인 불필요)
                    │
                    └─ 만료됨 → 로그인 화면으로 이동

💡 hasToken()이 true라도 토큰이 만료되어 있을 수 있습니다. 반드시 accessTokenInfo()로 유효성을 추가 확인해야 합니다.

8. 사용자 정보 조회

로그인 완료 후 me() API로 사용자 정보를 조회할 수 있습니다. 응답에는 회원번호, 이메일, 닉네임, 프로필 사진 등이 포함됩니다.

주요 접근 경로

주의 사항

동의 항목으로 설정되지 않았거나, 사용자가 동의하지 않은 항목은 null로 반환됩니다. 따라서 모든 사용자 정보에는 반드시 null 체크가 필요합니다.

사용자가 특정 항목에 동의하지 않은 상태에서 해당 정보가 필요한 시나리오에 진입하면, loginWithNewScopes()로 추가 동의를 요청할 수 있습니다.

사용자 프로퍼티 저장

카카오 기본 제공 정보 외에, 개발자가 직접 정의한 커스텀 데이터를 사용자에게 연결해 저장할 수 있습니다. 콘솔의 [카카오 로그인] > [고급] > [사용자 프로퍼티] 에서 키를 먼저 등록한 후 사용합니다.

9. 로그아웃 / 연결 해제

두 기능 모두 토큰을 폐기하지만 목적과 영향 범위가 다릅니다.

로그아웃 은 SDK에 저장된 토큰을 폐기합니다. 요청 성공 여부와 관계없이 토큰은 항상 폐기되므로 에러가 발생해도 로컬 상태는 초기화됩니다.

연결 해제 는 사용자의 동의를 철회하고 모든 토큰을 폐기합니다. 회원 탈퇴 시 반드시 사용해야 하며, 이후 재로그인 시 동의 화면이 다시 표시됩니다. 사용자가 서비스 앱이 아닌 카카오 측에서 직접 연결을 끊었을 때 알림을 받으려면 연결 해제 웹훅(Webhook) 을 별도로 설정해야 합니다.

10. 추가 기능

동의 항목 추가 동의 요청

처음 로그인 시 사용자가 거부한 항목에 대해 서비스 이용 중 추가 동의를 요청할 수 있습니다. 특정 기능 진입 시점에 loginWithNewScopes()를 호출해 필요한 항목만 선별적으로 요청합니다.

⚠️ OpenID Connect를 사용하는 앱은 추가 동의 요청 시 "openid" scope를 반드시 포함해야 합니다. 누락 시 ID 토큰이 재발급되지 않습니다.

동의 항목 동의 내역 조회 / 철회

scopes() API로 사용자가 현재 어떤 항목에 동의했는지 확인할 수 있습니다. 특정 항목의 동의를 철회하려면 revokeScopes()를 사용합니다. 단, revocable 값이 true인 항목만 철회 가능합니다.

배송지 조회

사용자가 카카오에 등록한 배송지를 조회할 수 있습니다. 배송지 피커(selectShippingAddress())를 통해 사용자가 직접 선택한 배송지 ID를 받고, 해당 ID로 상세 정보를 조회하는 2단계 구조로 동작합니다.

로그인 관련 추가 옵션

서비스 약관 (카카오싱크 전용)

카카오싱크를 도입한 서비스에서만 사용 가능합니다. 로그인 동의 화면에 포함할 서비스 약관을 지정하거나, 사용자의 약관 동의 내역을 조회/철회할 수 있습니다.

11. 트러블슈팅 — KeyHash 에러

증상

카카오 로그인 시도 시 아래와 같은 에러가 발생하며 로그인이 되지 않습니다.

statusCode=403, message=unauthorized, apiType=...

또는 로그인 요청 자체가 실패하거나 동의 화면이 뜨지 않는 경우가 해당됩니다.

원인

카카오 개발자 콘솔에 등록된 키 해시와 현재 앱의 실제 서명 키 해시가 일치하지 않는 경우 발생합니다. 주요 발생 시점은 아래와 같습니다.

해결 방법 — talker_flutter로 실제 키 해시 확인

키 해시를 직접 추출하기 어려운 경우, talker_flutter를 활용해 앱 실행 시점에 실제 키 해시 값을 로그로 출력하는 방법이 가장 간편합니다.

// 앱 초기화 시점에 실제 키 해시 출력
talker.info('🔑 Kakao keyHash: ${await KakaoSdk.origin}');

KakaoSdk.origin은 현재 앱이 사용 중인 실제 키 해시 값을 반환합니다. 위 코드를 앱 실행 초기(예: main() 또는 초기화 로직)에 추가하고 앱을 실행하면 talker 로그에서 키 해시 값을 바로 확인할 수 있습니다.

등록 절차

1. 출력된 키 해시 값을 복사합니다.
2. 카카오 개발자 콘솔 [앱 설정] > [플랫폼] > [Android] 로 이동합니다.
3. 키 해시 항목에 복사한 값을 추가하고 저장합니다.
4. 앱을 재실행하여 로그인이 정상 동작하는지 확인합니다.

💡 키 해시는 콘솔에 여러 개 등록이 가능합니다. 디버그/릴리즈/팀원별 키 해시를 모두 등록해두면 환경마다 반복해서 에러가 발생하는 상황을 방지할 수 있습니다.

⚠️ 배포 시 주의: Play App Signing을 사용하는 경우, 구글 플레이 콘솔의 [설정] > [앱 서명] 에서 확인한 SHA-1 또는 SHA-256 값을 기반으로 키 해시를 별도로 등록해야 합니다.

마무리 — 구현 체크리스트

📎 참고 자료

• Kakao Developers 공식 문서
• 에러 코드 목록
• 카카오 로그인 디자인 가이드