카카오 로그인을 Supabase 프로젝트에 붙이는 과정 자체는 대시보드에서 키 두 개를 입력하고 함수 한 줄을 호출하면 끝이지만, 그 뒤에서 동작하는 OAuth 2.0 인가 코드 플로우, 토큰 수명 주기, 세션 갱신 전략을 이해하지 못하면 운영 단계에서 예기치 않은 세션 만료, 토큰 탈취 취약점, RLS 정책 충돌 같은 문제를 마주하게 된다.
카카오 로그인은 OAuth 2.0 기반 소셜 로그인 서비스로, 사용자 인증(Authentication)과 인가(Authorization)를 분리해 처리한다. Supabase Auth는 이 과정에서 인가 코드 수신, 토큰 교환, 세션 생성, 리프레시 토큰 관리를 자동화하는 미들웨어 역할을 한다. 즉 개발자가 직접 카카오 API 서버와 토큰을 주고받는 코드를 작성할 필요가 없고, Supabase가 중간에서 인가 코드를 액세스 토큰으로 교환한 뒤 자체 JWT 세션을 발급하는 구조다.
이 문서는 공식 문서 기반으로 Supabase Auth의 카카오 연동 구조를 기술적으로 분석하고, 카카오 측 토큰 정책과 Supabase 측 세션 정책이 어떻게 맞물리는지 설명한다. 아울러 Clerk, Auth0, Firebase, Logto, NextAuth.js 등 다른 인증 서비스에서 카카오를 어떤 수준으로 지원하는지도 함께 비교한다.
1. 카카오 OAuth 2.0 인가 코드 플로우의 동작 구조
카카오 로그인의 핵심은 인가 코드(Authorization Code) 플로우다. 사용자가 카카오 로그인 버튼을 누르면 브라우저가 카카오 인증 서버로 리다이렉트되고, 사용자가 동의 화면에서 권한을 승인하면 카카오가 인가 코드를 리다이렉트 URI로 전달한다. 서비스 서버는 이 코드를 다시 카카오 토큰 엔드포인트에 보내 액세스 토큰과 리프레시 토큰을 발급받는다.
| 순서 | 위치 | 작업 | 비고 |
|---|---|---|---|
| 1 | 카카오 디벨로퍼스 | developers.kakao.com에 카카오계정으로 로그인 | 계정이 없으면 카카오 회원가입부터 진행 |
| 2 | 카카오 디벨로퍼스 | 새 애플리케이션 등록 | 앱 이름·회사명·카테고리 등 필수 정보를 채워서 저장한다 |
| 3 | 카카오 디벨로퍼스 | 등록한 애플리케이션의 대시보드로 진입 | 이후 카카오 관련 설정은 모두 이 앱 내부에서 이뤄진다 |
| 4 | 카카오 디벨로퍼스 | 이메일을 필수 동의로 받아야 하는 경우 비즈니스 인증 메뉴에서 비즈 앱으로 전환 | 사업자번호 없는 개인 개발자는 카카오 데브톡에 전환 요청 게시글을 작성하면 담당자가 수동 처리한다. 이메일을 선택 동의로만 쓸 경우 이 단계는 건너뛴다 |
| 5 | 카카오 디벨로퍼스 | 카카오 로그인 > 사용 설정에서 상태를 ON으로 전환 | 비활성 상태에서 로그인을 시도하면 KOE004 에러가 반환된다 |
| 6 | 카카오 디벨로퍼스 | 카카오 로그인 > 동의항목에서 수집할 사용자 정보 범위 지정 | Supabase 공식 문서 권장값: profile_nickname·profile_image는 기본, account_email은 서비스 정책에 따라 선택 또는 필수로 설정 |
| 7 | 카카오 디벨로퍼스 | 앱 설정 > 앱 > 플랫폼 키 페이지에서 REST API 키 확인·복사 | Supabase에 입력할 Client ID 역할을 한다 |
| 8 | 카카오 디벨로퍼스 | 플랫폼 키 페이지에서 REST API 키를 클릭해 상세 페이지 진입 → 클라이언트 시크릿 코드 확인·복사 | Supabase에 입력할 Client Secret 역할을 한다. 카카오는 REST API 키 생성 시 시크릿을 기본 활성화 상태로 부여하므로 별도 발급 절차가 없다. 활성화 상태인지 반드시 확인할 것 |
| 9 | Supabase 대시보드 | 프로젝트 선택 후 Authentication 메뉴 진입 | 왼쪽 사이드바의 자물쇠 아이콘 |
| 10 | Supabase 대시보드 | Configuration > Providers 목록에서 Kakao를 펼친 뒤 Enabled 토글을 ON으로 전환 | ON으로 바꿔야 Client ID·Secret 입력 필드가 활성화된다 |
| 11 | Supabase 대시보드 | 7번에서 복사한 REST API 키를 Kakao Client ID 필드에 붙여넣기 | 앞뒤 공백이 포함되지 않도록 주의 |
| 12 | Supabase 대시보드 | 8번에서 복사한 클라이언트 시크릿을 Kakao Client Secret 필드에 붙여넣기 | 시크릿이 비활성 상태이면 카카오 디벨로퍼스에서 먼저 활성화해야 한다 |
| 13 | Supabase 대시보드 | 이메일 미수집 또는 선택 동의인 경우 Allow users without an email 옵션 체크 | 이메일 필수 동의를 설정한 비즈 앱이면 체크하지 않아도 된다 |
| 14 | Supabase 대시보드 | 하단에 표시된 Callback URL 값을 복사 | 형식은 https://<project-ref>.supabase.co/auth/v1/callback이며 프로젝트마다 고유하다 |
| 15 | 카카오 디벨로퍼스 | 앱 설정 > 앱 > 플랫폼 키 > REST API 키 상세 페이지의 카카오 로그인 리다이렉트 URI 필드에 14번에서 복사한 Callback URL을 등록하고 저장 | 프로토콜(https)·경로·슬래시까지 한 글자라도 다르면 KOE006 에러가 발생한다 |
| 16 | Supabase 대시보드 | Save 버튼을 눌러 Kakao 프로바이더 설정 저장 | 이 시점부터 카카오 로그인 테스트가 가능하다 |
| 17 | 프로젝트 코드 | supabase.auth.signInWithOAuth({ provider: 'kakao' 한 줄 호출 |
브라우저가 카카오 동의 화면으로 리다이렉트되고, 동의 완료 후 자동으로 Supabase 세션이 생성된다 |
| 18 | 프로젝트 코드 | (서버사이드 렌더링 환경만 해당) 콜백 라우트에서 supabase.auth.exchangeCodeForSession(code) 호출 |
Next.js App Router·SvelteKit 등 SSR 환경에서는 PKCE 플로우가 필요하므로 이 단계가 필수다. 순수 클라이언트 앱은 생략 가능 |
1.1 Supabase가 처리하는 영역
- 사용자가 프론트엔드에서
signInWithOAuth를 호출하면 Supabase Auth 서버가 카카오 인증 URL을 생성해 브라우저를 리다이렉트시킨다 - 사용자가 카카오 동의 화면에서 승인하면, 카카오는 인가 코드를 포함해 https://
.supabase.co/auth/v1/callback 으로 리다이렉트한다 - Supabase Auth 서버가 이 인가 코드를 카카오 토큰 엔드포인트(https://kauth.kakao.com/oauth/token)에 보내 액세스 토큰을 수신한다
- 수신한 액세스 토큰으로 카카오 사용자 정보 API를 호출해 프로필, 닉네임, 이메일 등을 가져온다
- 가져온 정보를 기반으로 auth.users 테이블에 사용자를 생성하거나 기존 사용자와 매칭하고, Supabase 자체 JWT(액세스 토큰)와 리프레시 토큰을 발급한다
이 과정에서 개발자가 카카오 토큰 엔드포인트를 직접 호출하는 코드를 작성할 필요가 없다. Supabase Auth 서버가 백엔드에서 토큰 교환을 전부 처리하고, 프론트엔드에는 Supabase 자체 세션 토큰만 전달한다.
핵심 포인트: Supabase는 카카오의 액세스 토큰을 직접 프론트엔드에 노출하지 않는다. 카카오 토큰은 Supabase Auth 서버 내부에서만 사용되고, 프론트엔드에는 Supabase JWT가 발급된다. 카카오 provider token이 필요한 경우 세션 객체에서 별도로 추출해야 한다.
2. 카카오 디벨로퍼스 앱 구성과 Supabase 대시보드 연결 절차
Supabase에서 카카오 로그인을 활성화하려면 카카오 디벨로퍼스 포털에서 앱을 생성하고, 해당 앱의 인증 정보를 Supabase 대시보드에 등록해야 한다. Supabase 공식 문서에서 안내하는 전체 절차는 크게 여섯 단계로 구성된다.
2.1 카카오 디벨로퍼스 포털 설정
- 카카오 디벨로퍼스(developers.kakao.com)에 로그인한 뒤 상단 메뉴에서 앱 관리 페이지로 이동한다. 등록된 앱이 없으면 새 앱을 생성하고, 앱 아이콘·앱 이름·회사명·카테고리·도메인 등 기본 정보를 입력한다
- 앱 생성이 완료되면 앱 설정 > 앱 > 플랫폼 키 메뉴에서 REST API 키를 확인한다. 이 키가 Supabase에서 Client ID 역할을 한다
- 같은 페이지에서 REST API 키를 선택하면 클라이언트 시크릿(Kakao Login Client Secret code)을 확인할 수 있다. 카카오는 REST API 키에 클라이언트 시크릿 기능을 기본 활성화 상태로 추가하므로, 토큰 발급 시 반드시 이 시크릿 값을 함께 전달해야 한다. 이 값이 Supabase에서 Client Secret 역할을 한다
- 제품 설정 > 카카오 로그인 > 일반 메뉴에서 카카오 로그인 사용 설정을 ON으로 전환한다. 이 설정이 OFF인 상태에서 로그인을 시도하면 KOE004 에러가 발생한다
- 제품 설정 > 카카오 로그인 > 동의항목 메뉴에서 서비스에 필요한 사용자 정보 수집 범위를 설정한다. Supabase 공식 문서에서 권장하는 기본 동의항목은 profile_nickname, profile_image, 그리고 선택적으로 account_email이다
- REST API 키 상세 편집 페이지에서 카카오 로그인 리다이렉트 URI 필드에 Supabase의 Callback URL을 등록한다. 이 URL 형식은 https://
.supabase.co/auth/v1/callback 이며, Supabase 대시보드의 Authentication > Providers > Kakao 섹션에서 복사할 수 있다. 리다이렉트 URI가 불일치하면 KOE006 에러가 발생한다
2.2 Supabase 대시보드 설정
- Supabase 프로젝트 대시보드에서 왼쪽 사이드바의 Authentication 아이콘을 클릭한다
- Configuration 섹션 아래의 Providers 메뉴로 이동한다
- 프로바이더 목록에서 Kakao를 찾아 확장하고 Kakao Enabled를 ON으로 전환한다
- 앞서 카카오 디벨로퍼스에서 확보한 REST API 키를 Kakao Client ID 필드에, 클라이언트 시크릿을 Kakao Client Secret 필드에 입력한다
- 카카오에서 account_email 동의항목을 요청하지 않는 경우, Allow users without an email 옵션을 활성화한다
- Save 버튼을 클릭해 설정을 저장한다
2.3 이메일 동의항목과 비즈 앱 전환
account_email 동의항목을 필수 동의로 설정하려면 카카오 디벨로퍼스에서 앱을 비즈 앱으로 전환해야 한다. 사업자등록번호가 있는 경우 앱 설정 > 비즈니스 인증 메뉴에서 직접 전환이 가능하고, 사업자등록번호가 없는 개인 개발자는 카카오 데브톡(devtalk.kakao.com)에 비즈 앱 전환 요청 게시글을 작성하면 카카오 담당자가 수동으로 처리해 준다. 개인 개발자의 비즈 앱 전환 신청 시에는 앱 이름과 ID, 소유자 이메일, 본인 인증 완료 여부, 비즈 앱 설정 목적을 명시해야 한다.
비즈 앱으로 전환하지 않아도 이메일을 선택 동의나 이용 중 동의로 설정하면 수집이 가능하지만, 사용자가 동의하지 않을 수 있으므로 서비스 로직에서 이메일이 null인 경우를 반드시 처리해야 한다.
핵심 포인트: Supabase에서 카카오 연동에 필요한 값은 REST API 키(Client ID)와 클라이언트 시크릿(Client Secret) 두 가지뿐이다. 카카오 디벨로퍼스에서 카카오 로그인 ON 전환, 리다이렉트 URI 등록, 동의항목 설정을 완료한 뒤 Supabase 대시보드에서 이 두 값을 입력하면 기본 연동이 끝난다.
3. 토큰 수명 주기와 세션 갱신 전략
Supabase Auth와 카카오 로그인은 각각 독립적인 토큰 체계를 운영한다. 두 체계가 어떻게 다른지 이해해야 세션 만료 타이밍을 정확히 예측할 수 있다.
3.1 카카오 측 토큰 수명
카카오 공식 문서에 따르면, 카카오가 발급하는 토큰의 만료 시간은 개발 환경에 따라 다르다.
| 토큰 종류 | REST API | JavaScript SDK | Android/iOS SDK |
|---|---|---|---|
| 액세스 토큰 | 6시간 | 2시간 | 12시간 |
| 리프레시 토큰 | 2달 (만료 1달 전부터 갱신 가능) | 2달 | 2달 |
| ID 토큰 (OIDC) | 액세스 토큰과 동일 | 액세스 토큰과 동일 | 액세스 토큰과 동일 |
Supabase Auth가 카카오 연동 시 사용하는 방식은 REST API이므로, 카카오 액세스 토큰의 유효 시간은 6시간이다. 그러나 이 토큰은 Supabase 서버 내부에서만 사용되므로, 프론트엔드 세션 수명에 직접적인 영향을 주지 않는다.
3.2 Supabase 측 세션 수명
Supabase Auth는 자체 JWT 기반 세션을 관리한다. 기본 설정에서 Supabase 액세스 토큰(JWT)의 유효 시간은 1시간이고, 리프레시 토큰은 만료 없이 무기한 유효하되 1회만 사용 가능하다. 리프레시 토큰을 한 번 사용하면 새로운 액세스 토큰과 리프레시 토큰 쌍이 발급되고, 기존 리프레시 토큰은 폐기된다.
Supabase 공식 문서에서 권장하는 JWT 만료 시간 관련 기준은 다음과 같다.
| 설정 | 기본값 | 권장 범위 | 비고 |
|---|---|---|---|
| JWT 만료 시간 | 1시간 | 5분~1시간 | 1시간 초과는 보안상 비권장, 2분 미만은 클럭 스큐 문제 발생 가능 |
| 세션 최대 수명(Time-box) | 무제한 | 서비스 정책에 따라 설정 | SOC 2, HIPAA 등 컴플라이언스 요구 시 활성화 |
| 비활동 타임아웃 | 없음 | 서비스 정책에 따라 설정 | 일정 시간 세션 갱신이 없으면 자동 만료 |
| 사용자당 단일 세션 | 비활성 | 필요 시 활성화 | 가장 최근 세션만 유지, 이전 세션 종료 |
Supabase 클라이언트 라이브러리는 만료 전에 선제적으로 세션을 갱신하는 로직을 내장하고 있어, 사용자가 앱을 사용 중인 동안에는 세션이 자동으로 유지된다.
3.3 리프레시 토큰 재사용 감지
Supabase Auth는 리프레시 토큰 재사용 감지(Refresh Token Reuse Detection) 기능을 내장하고 있다. 한 번 사용된 리프레시 토큰이 다시 사용되면 해당 세션 전체를 종료하고 모든 관련 리프레시 토큰을 폐기한다. 이는 리프레시 토큰이 로그나 취약한 서드파티 서버를 통해 유출된 상황에 대비한 보안 장치다.
다만 네트워크 불안정으로 응답을 수신하지 못한 경우를 대비해, 기본 10초의 재사용 허용 구간과 부모 토큰 재사용 예외가 적용된다. 서버사이드 렌더링 환경에서 동일한 리프레시 토큰이 서버와 클라이언트에서 연속으로 사용되는 상황, 또는 네트워크 장애로 응답을 받지 못한 클라이언트가 이전 리프레시 토큰을 재시도하는 상황이 이 예외에 해당한다.
4. PKCE 플로우와 서버사이드 인증
Supabase Auth는 세션 개시에 Implicit 플로우와 PKCE(Proof Key for Code Exchange) 플로우 두 가지를 지원한다. 클라이언트 사이드에서 signInWithOAuth를 호출하면 기본적으로 Implicit 플로우가 사용되지만, Next.js App Router 같은 서버사이드 환경에서는 PKCE 플로우가 필요하다.
4.1 PKCE 플로우의 추가 단계
signInWithOAuth호출 시 options.redirectTo에 서버측 콜백 라우트 URL을 지정한다. 이 URL은 Supabase 대시보드의 Redirect URLs 허용 목록에 등록되어 있어야 한다- 카카오 인증 완료 후 Supabase Auth가 인가 코드를 콜백 라우트로 전달한다
- 콜백 라우트에서
supabase.auth.exchangeCodeForSession(code)를 호출해 인가 코드를 세션으로 교환한다 - 교환이 성공하면 서버에서 쿠키에 세션을 저장하고 사용자를 원래 페이지로 리다이렉트한다
PKCE 플로우에서는 Code Verifier와 Code Challenge를 사용해 인가 코드 탈취 공격을 방지한다. Supabase 공식 문서의 서버사이드 인증 예시에서는 Next.js App Router의 라우트 핸들러(app/auth/callback/route.ts)에서 exchangeCodeForSession을 호출하는 패턴을 보여 준다. 이 콜백 라우트에서는 URL 파라미터에서 code 값을 추출하고, Supabase 서버 클라이언트를 생성해 코드 교환을 수행한 뒤, 에러가 없으면 사용자를 대시보드 등 원하는 경로로 리다이렉트하는 흐름이다.
핵심 포인트: 서버사이드 렌더링 환경(Next.js App Router, SvelteKit, Nuxt 등)에서는 PKCE 플로우를 사용해야 하고, 콜백 라우트에서 exchangeCodeForSession 호출이 반드시 필요하다. 이 단계를 빠뜨리면 세션이 생성되지 않는다.
5. signInWithOAuth와 signInWithIdToken 비교
Supabase의 카카오 공식 문서에는 두 가지 연동 방식이 소개되어 있다. 표준 OAuth 리다이렉트 방식인 signInWithOAuth와 OIDC ID 토큰을 직접 전달하는 signInWithIdToken이다.
5.1 두 방식의 구조적 차이
| 비교 항목 | signInWithOAuth | signInWithIdToken |
|---|---|---|
| 인증 흐름 | 브라우저 리다이렉트 → Supabase 콜백 → 토큰 교환 | 클라이언트가 직접 카카오 토큰 엔드포인트 호출 → ID 토큰 추출 → Supabase에 전달 |
| 카카오 OIDC 필요 여부 | 불필요 | 필수 (OpenID Connect 활성화 + openid 스코프 추가) |
| 토큰 교환 주체 | Supabase Auth 서버 | 개발자가 직접 구현 |
| 브라우저 리다이렉트 | 발생 | 발생하지 않음 |
| 적합한 환경 | 웹 애플리케이션 전반 | 네이티브 모바일 앱, 카카오 SDK를 직접 사용하는 환경 |
| 구현 복잡도 | 낮음 (함수 1줄) | 높음 (토큰 엔드포인트 호출, ID 토큰 파싱 코드 필요) |
signInWithIdToken을 사용하려면 카카오 디벨로퍼스 앱 관리 페이지에서 카카오 로그인 > OpenID Connect 설정을 ON으로 변경해야 한다. 카카오 로그인이 먼저 활성화되어 있어야 OIDC 설정이 가능하며, 비활성화하면 그 시점부터 ID 토큰이 발급되지 않아 signInWithIdToken 기반 로그인이 즉시 중단된다.
signInWithIdToken 방식에서 개발자는 카카오 토큰 엔드포인트(https://kauth.kakao.com/oauth/token)에 POST 요청을 보내 id_token을 추출하고, 이 토큰을 supabase.auth.signInWithIdToken의 token 파라미터로 전달한다. Supabase Auth 서버는 ID 토큰의 서명을 카카오의 공개키로 검증한 뒤 세션을 생성한다.
6. Supabase RLS와 카카오 로그인 사용자 데이터 연계
Supabase의 강점 중 하나는 Row Level Security(RLS)를 통해 데이터베이스 수준에서 사용자별 접근 제어를 구현할 수 있다는 점이다. 카카오 로그인으로 인증된 사용자도 Supabase의 JWT 기반 인증 체계에 통합되므로, 이메일/비밀번호 사용자와 동일한 RLS 정책이 적용된다.
6.1 auth.users 테이블의 카카오 사용자 데이터
카카오 로그인을 통해 가입한 사용자는 auth.users 테이블에 저장된다. 주요 필드의 구성은 다음과 같다.
| 필드 | 내용 |
|---|---|
| id | Supabase에서 생성하는 UUID |
| 카카오 동의항목에서 수집한 이메일 (미수집 시 null) | |
| raw_user_meta_data | 카카오에서 받은 프로필 정보(닉네임, 프로필 이미지 등)를 JSON으로 저장 |
| app_metadata.provider | 'kakao' 문자열 |
| app_metadata.providers | 사용자가 연결한 모든 프로바이더 배열 |
| identities | 카카오 계정과의 연결 정보를 담은 배열. identity_data에 카카오 프로필이 포함됨 |
RLS 정책에서 auth.uid() 함수를 사용하면 현재 인증된 사용자의 UUID를 기준으로 행 접근을 제어할 수 있다. 카카오 로그인 사용자든 이메일 로그인 사용자든 동일한 auth.uid()가 적용되므로, RLS 정책을 로그인 방식별로 나눠서 작성할 필요가 없다.
raw_user_meta_data 내부의 값을 기반으로 RLS 정책을 구성할 수도 있다. 예를 들어 카카오 프로바이더를 통해 가입한 사용자만 특정 테이블에 접근하도록 하고 싶다면, auth.jwt()->'app_metadata'->>'provider' 표현식을 RLS 정책 조건에 활용할 수 있다.
6.2 Identity Linking 동작
Supabase Auth는 동일한 이메일 주소를 가진 계정을 자동으로 연결(Automatic Identity Linking)하는 기능을 기본 제공한다. 예를 들어 사용자가 먼저 이메일/비밀번호로 가입한 뒤 동일한 이메일의 카카오 계정으로 로그인하면, Supabase는 이를 같은 사용자로 인식해 하나의 auth.users 행에 두 개의 identity를 연결한다. 이 동작은 사용자 경험을 크게 향상시키지만, 의도치 않은 계정 병합이 일어날 수 있으므로 서비스 정책에 따라 Manual Linking 모드로 전환하는 것도 고려해야 한다. Manual Linking은 대시보드의 Auth 설정에서 활성화할 수 있으며, 이 경우 개발자가 linkIdentity() 함수를 명시적으로 호출해야만 계정이 연결된다.
7. 주요 인증 서비스의 카카오 로그인 지원 현황
Supabase 외에도 다양한 인증 서비스가 존재한다. 카카오 로그인을 지원하는 방식과 수준이 서비스마다 크게 다르기 때문에, 프로젝트 초기 단계에서 인증 서비스를 선택할 때 카카오 지원 여부를 반드시 확인해야 한다.
7.1 서비스별 카카오 지원 방식 비교
| 인증 서비스 | 카카오 지원 | 연동 방식 | 특징 |
|---|---|---|---|
| Supabase Auth | 공식 프로바이더 | 대시보드에서 Kakao ON 전환 후 REST API 키·시크릿 입력 | OAuth와 OIDC(signInWithIdToken) 두 가지 방식 모두 지원, RLS와 자연스럽게 통합 |
| Clerk | 비공식 (Custom Provider) | SSO connections > Custom provider에서 카카오 OIDC Discovery Endpoint 수동 입력 | 공식 프로바이더 목록에 카카오 미포함. Attribute Mapping 조정 및 프록시 서버 필요 가능 |
| Auth0 | 마켓플레이스 통합 | Auth0 Marketplace에서 Kakao Login 통합 설치 후 연동 | 별도 설치 과정 필요하지만 공식적으로 지원 |
| NextAuth.js (Auth.js) | 공식 프로바이더 | providers 배열에 KakaoProvider 추가 | OIDC 옵션도 지원, 설정이 단순함 |
| Firebase Auth | 비공식 (OIDC 또는 Custom Token) | Cloud Functions로 Custom Token 발급 방식 권장 | 네이티브 카카오 프로바이더 없음 |
| Logto | 공식 커넥터 | 콘솔에서 Kakao 소셜 커넥터 추가 | 전용 카카오 커넥터를 제공하며 설정이 직관적 |
| Better Auth | 공식 프로바이더 | signIn.social 함수로 카카오 호출 | 오픈소스 라이브러리, 카카오 네이티브 지원 |
| Appwrite | 미지원 | 공식 OAuth 프로바이더 목록에 카카오 미포함 | GitHub 이슈로 기능 요청이 등록된 상태이나 일정 미정 |
7.2 Clerk의 Custom OAuth Provider로 카카오 연동 시 고려사항
Clerk는 카카오를 공식 지원하지 않지만, Custom OAuth Provider 기능을 통해 연동할 수 있다. Clerk 대시보드의 SSO connections 페이지에서 Custom provider 탭을 선택하고, Discovery Endpoint에 https://kauth.kakao.com/.well-known/openid-configuration을 입력하면 인증 관련 엔드포인트가 자동으로 채워진다. Client ID에는 카카오 REST API 키, Client Secret에는 클라이언트 시크릿을 입력한다.
그러나 Clerk의 Custom Provider는 Attribute Mapping에서 카카오가 반환하는 비표준 클레임을 수동으로 매핑해야 하고, 경우에 따라 카카오 User Info API 호출에 추가 인증이 필요해 Clerk와 카카오 사이에 프록시 서버를 구현해야 할 수도 있다. Clerk 공식 문서에서는 이런 경우 Cloudflare Workers나 별도 서버로 프록시를 만들어 User info URL로 설정하라고 안내한다.
7.3 Firebase의 카카오 연동 한계
Firebase Authentication에는 Google, Apple, Facebook, GitHub 등 네이티브 프로바이더만 있고 카카오는 없다. Firebase의 OIDC 프로바이더 기능으로 카카오를 설정할 수 있지만, 카카오의 OIDC Discovery Document 구성과 Firebase가 기대하는 표준 형식 사이에 간극이 있어 연동 과정에서 예상치 못한 문제가 발생할 수 있다는 보고가 커뮤니티에서 지속적으로 올라오고 있다. 대안으로 Firebase Cloud Functions에서 카카오 OAuth 인증을 수행한 뒤 admin.auth().createCustomToken()으로 Custom Token을 발급하고, 클라이언트에서 signInWithCustomToken()으로 로그인하는 방식이 있다. 이 방식이 더 안정적이지만 서버사이드 코드를 직접 작성해야 한다.
8. 카카오 동의항목·클라이언트 시크릿·OIDC 등 설정 항목 정리
카카오 디벨로퍼스 앱 관리 페이지에는 카카오 로그인과 관련된 설정 항목이 다수 존재한다. Supabase 연동에 직접 관련되는 항목과 서비스 고도화 시 필요한 항목을 구분해서 정리한다.
8.1 Supabase 연동 필수 설정과 선택 설정
필수 설정 항목:
| 설정 항목 | 위치 | 역할 |
|---|---|---|
| 카카오 로그인 사용 설정 (ON) | 카카오 로그인 > 사용 설정 | OFF 시 KOE004 에러 발생 |
| REST API 키 | 앱 설정 > 앱 > 플랫폼 키 | Supabase Client ID로 사용 |
| 클라이언트 시크릿 | 플랫폼 키 > REST API 키 상세 | Supabase Client Secret으로 사용 |
| 리다이렉트 URI | 플랫폼 키 > REST API 키 상세 | Supabase Callback URL 등록. 불일치 시 KOE006 에러 |
| 동의항목 (profile_nickname, profile_image) | 카카오 로그인 > 동의항목 | 기본 프로필 정보 수집 |
선택 설정 항목:
| 설정 항목 | 위치 | 역할 |
|---|---|---|
| account_email 동의항목 | 카카오 로그인 > 동의항목 | 이메일 수집. 비즈앱 전환 후 필수 동의 설정 가능 |
| OpenID Connect | 카카오 로그인 > OpenID Connect | signInWithIdToken 사용 시 필수. ON 설정 후 openid 스코프 추가 필요 |
| 간편가입 | 카카오 로그인 > 간편가입 | 동의 화면에 서비스 약관을 함께 노출 |
| 로그아웃 리다이렉트 URI | 카카오 로그인 > 고급 | 카카오계정과 함께 로그아웃 기능 사용 시 등록 |
8.2 동의항목 추가 기능 심사
이메일 외에 전화번호, 성별, 생년월일 등 추가 개인정보를 수집하려면 카카오의 추가 기능 심사를 받아야 한다. 심사에서는 신청한 동의항목과 실제 서비스의 회원가입 화면에서 수집하는 항목이 일치하는지, 필수/선택 구분이 명확한지를 확인한다. 회원가입 페이지 URL, 개인정보 처리방침 URL, 수집 항목 증빙 화면 캡처를 제출해야 하며, 서비스 회원가입 화면에서 수집하는 정보와 카카오 동의항목에서 요청하는 정보의 종류 및 필수/선택 조건이 일치해야 심사를 통과할 수 있다.
9. 마무리
위에서 살펴본 Supabase 카카오 로그인 연동의 핵심 내용을 정리하면 다음과 같습니다.
핵심 요약:
- Supabase Auth는 카카오 인가 코드 수신부터 토큰 교환, 사용자 정보 조회, 세션 발급까지를 자동으로 처리하며, 프론트엔드에는 Supabase 자체 JWT만 전달된다
- 카카오 디벨로퍼스에서 REST API 키(Client ID)와 클라이언트 시크릿(Client Secret)을 확보해 Supabase 대시보드에 입력하고, 리다이렉트 URI와 동의항목을 설정하면 기본 연동이 완료된다
- 카카오 REST API 기준 액세스 토큰 유효 시간은 6시간이지만, Supabase 세션의 수명은 별도로 관리되므로 두 체계의 만료 타이밍은 독립적이다
- 서버사이드 렌더링 환경에서는 PKCE 플로우를 사용해야 하고, 콜백 라우트에서 exchangeCodeForSession 호출이 필수다
- signInWithOAuth는 구현이 간단한 표준 방식이고, signInWithIdToken은 네이티브 앱 등 카카오 SDK를 직접 사용하는 환경에 적합하며 OIDC 활성화가 전제 조건이다
- 카카오 로그인 사용자도 auth.uid() 기반 RLS 정책에 동일하게 적용되며, Identity Linking으로 이메일 기반 계정 자동 연결이 가능하다
- Clerk, Firebase, Appwrite는 카카오를 공식 지원하지 않으므로 Custom Provider 또는 Custom Token 등 우회 방식이 필요하고, Supabase, Auth0, NextAuth.js, Logto, Better Auth는 공식 지원한다
인증 서비스를 선택할 때는 카카오 공식 지원 여부 외에도 세션 관리 정책, RLS 연계, OIDC 지원 범위를 함께 비교해서 프로젝트 요구사항에 맞는 서비스를 결정하면 된다.