이런 경험 있으시죠?

// 카카오 로그인 버튼... 공식 가이드 색상이 뭐였지?
<button style={{ backgroundColor: '#FEE500' }}>  // 이게 맞나...?
  카카오 로그인
</button>

// 아이콘은 또 어디서 다운받지?
// 버튼 모서리 radius는 몇이더라?
// 네이버는 또 다른 가이드네...

// next-auth 설정... 카카오 provider가 없네?
// 직접 만들어야 하나?
// authorization URL이 뭐였지?
// scope는 뭘 넣어야 하지?
// profile 응답 형식은...?

// 에러 발생!
OAuthCallbackError: invalid_request
// 뭐가 문제인지 모르겠다...
// 영어로 된 에러... 구글링 시작...

우리 모두 겪어봤습니다.

그래서 K-Auth를 만들었습니다

우리의 철학

"한국 개발자가 한국 서비스를 만들 때, 로그인에서 시간을 낭비하면 안 된다."

카카오, 네이버 로그인은 한국 서비스의 필수입니다. 하지만 next-auth에는 공식 한국 provider가 없고, 매번 커스텀으로 만들어야 합니다. 버튼 디자인도 각 회사의 가이드라인을 찾아 직접 구현해야 합니다.

K-Auth는 이 반복되는 작업을 없앱니다.

뭐가 좋아지나요?

| 기존 방식 | K-Auth | |-----------|--------| | OAuth 설정에 30분-1시간 | 10초만에 설정 완료 | | 버튼 CSS 직접 작성, 가이드라인 검색 | 공식 디자인 버튼 제공 | | 영어 에러 메시지, 원인 파악 어려움 | 친절한 한국어 에러 + 해결 힌트 | | 카카오/네이버 문서 왔다갔다 | 통합된 하나의 API | | scope 설정 복잡 | collectPhone: true 한 줄 | | provider 직접 구현 | 검증된 provider 제공 |

설치

npm install @relkimm/k-auth

next-auth가 자동으로 함께 설치됩니다.

빠른 시작

Step 1. 인증 설정

auth.ts 파일을 생성하세요:

import { KAuth } from '@relkimm/k-auth';

export const { handlers, auth, signIn, signOut } = KAuth({
  kakao: {
    clientId: process.env.KAKAO_CLIENT_ID!,
    clientSecret: process.env.KAKAO_CLIENT_SECRET!,
  },
  naver: {
    clientId: process.env.NAVER_CLIENT_ID!,
    clientSecret: process.env.NAVER_CLIENT_SECRET!,
  },
});

Step 2. API 라우트

app/api/auth/[...nextauth]/route.ts:

import { handlers } from '@/auth';

export const { GET, POST } = handlers;

Step 3. 로그인 버튼

import { Button } from '@relkimm/k-auth/ui';
import { signIn } from '@/auth';

export default function LoginPage() {
  return (
    <Button.Group>
      <Button.Kakao onClick={() => signIn('kakao')} />
      <Button.Naver onClick={() => signIn('naver')} />
    </Button.Group>
  );
}

3단계면 끝! CSS 작성 없이, 공식 가이드라인을 준수한 버튼이 바로 나타납니다.

전화번호가 필요하세요?

기존 방식:

// scope에 뭘 넣어야 하지...?
// account_email,phone_number,birthday...?
// 카카오 문서 다시 확인...

K-Auth:

KAuth({
  kakao: {
    clientId: '...',
    clientSecret: '...',
    collectPhone: true,    // 전화번호
    collectBirth: true,    // 생년월일
    collectGender: true,   // 성별
  },
});

옵션 하나로 끝. scope는 자동으로 설정됩니다.

버튼 컴포넌트

K-Auth는 각 서비스의 공식 디자인 가이드를 준수한 버튼을 제공합니다.

• 카카오: 카카오 로그인 디자인 가이드
• 네이버: 네이버 로그인 디자인 가이드

더 이상 가이드라인 문서를 뒤지며 색상 코드를 찾을 필요가 없습니다.

지원 버튼

import { Button } from '@relkimm/k-auth/ui';

<Button.Kakao />   // 카카오 (노란색)
<Button.Naver />   // 네이버 (초록색)
<Button.Google />  // 구글 (흰색)
<Button.Apple />   // 애플 (검은색)

크기 옵션

<Button.Kakao size="sm" />      // 작게
<Button.Kakao size="default" /> // 기본
<Button.Kakao size="lg" />      // 크게
<Button.Kakao size="icon" />    // 아이콘만

버튼 그룹

// 세로 배치 (기본)
<Button.Group>
  <Button.Kakao />
  <Button.Naver />
</Button.Group>

// 가로 배치
<Button.Group direction="row">
  <Button.Kakao size="icon" />
  <Button.Naver size="icon" />
</Button.Group>

// 간격 조절
<Button.Group gap="sm">  // sm | md | lg
  ...
</Button.Group>

스타일 커스텀

Tailwind CSS 클래스로 자유롭게 커스텀할 수 있습니다:

<Button.Kakao className="w-full shadow-lg rounded-xl" />

구글 / 애플 추가하기

K-Auth는 next-auth와 100% 호환됩니다. 구글, 애플 같은 글로벌 로그인은 next-auth의 공식 provider를 그대로 사용하세요:

import { KAuth } from '@relkimm/k-auth';
import Google from 'next-auth/providers/google';
import Apple from 'next-auth/providers/apple';

export const { handlers, auth, signIn, signOut } = KAuth({
  kakao: {
    clientId: process.env.KAKAO_CLIENT_ID!,
    clientSecret: process.env.KAKAO_CLIENT_SECRET!,
  },
  naver: {
    clientId: process.env.NAVER_CLIENT_ID!,
    clientSecret: process.env.NAVER_CLIENT_SECRET!,
  },
  // 구글/애플 추가
  nextAuthConfig: {
    providers: [
      Google({
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      }),
      Apple({
        clientId: process.env.APPLE_CLIENT_ID!,
        clientSecret: process.env.APPLE_CLIENT_SECRET!,
      }),
    ],
  },
});

<Button.Group>
  <Button.Kakao onClick={() => signIn('kakao')} />
  <Button.Naver onClick={() => signIn('naver')} />
  <Button.Google onClick={() => signIn('google')} />
  <Button.Apple onClick={() => signIn('apple')} />
</Button.Group>

한국어 에러 메시지

기존 에러:

OAuthCallbackError: invalid_request

"뭐가 문제지...?" 구글링 시작...

K-Auth 에러:

==================================================
[K-Auth 오류] KAKAO_PHONE_NOT_ENABLED
==================================================

메시지: 전화번호 동의 항목이 비활성화되어 있습니다.
힌트: 카카오 개발자센터 > 동의항목 > 전화번호를 활성화해주세요.
문서: https://developers.kakao.com/console

==================================================

뭐가 문제인지, 어떻게 해결하는지 바로 알 수 있습니다.

API

KAuth 옵션

KAuth({
  kakao?: KakaoOptions,
  naver?: NaverOptions,
  nextAuthConfig?: NextAuthConfig,  // 고급 설정
})

카카오 옵션

| 옵션 | 타입 | 필수 | 설명 | |------|------|:----:|------| | clientId | string | ✅ | 카카오 REST API 키 | | clientSecret | string | ✅ | 카카오 Client Secret | | collectPhone | boolean | | 전화번호 수집 | | collectBirth | boolean | | 생년월일 수집 | | collectGender | boolean | | 성별 수집 | | collectAgeRange | boolean | | 연령대 수집 |

네이버 옵션

| 옵션 | 타입 | 필수 | 설명 | |------|------|:----:|------| | clientId | string | ✅ | 네이버 Client ID | | clientSecret | string | ✅ | 네이버 Client Secret | | collectPhone | boolean | | 전화번호 수집 | | collectBirth | boolean | | 생년월일 수집 | | collectGender | boolean | | 성별 수집 | | collectName | boolean | | 실명 수집 |

환경 변수 설정

.env.local 파일:

# 카카오
KAKAO_CLIENT_ID=your_kakao_rest_api_key
KAKAO_CLIENT_SECRET=your_kakao_client_secret

# 네이버
NAVER_CLIENT_ID=your_naver_client_id
NAVER_CLIENT_SECRET=your_naver_client_secret

# (선택) 구글
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# (선택) 애플
APPLE_CLIENT_ID=your_apple_client_id
APPLE_CLIENT_SECRET=your_apple_client_secret

# NextAuth 필수
AUTH_SECRET=your_random_secret_key  # openssl rand -base64 32

개발자 콘솔 설정

1. Kakao Developers 접속
2. 애플리케이션 추가
3. 앱 키 > REST API 키 복사 → KAKAO_CLIENT_ID
4. 보안 > Client Secret 생성 → KAKAO_CLIENT_SECRET
5. 카카오 로그인 > 활성화
6. Redirect URI 등록:
   • 개발: http://localhost:3000/api/auth/callback/kakao
   • 배포: https://yourdomain.com/api/auth/callback/kakao

1. NAVER Developers 접속
2. 애플리케이션 등록
3. Client ID 복사 → NAVER_CLIENT_ID
4. Client Secret 복사 → NAVER_CLIENT_SECRET
5. 서비스 URL: http://localhost:3000
6. Callback URL: http://localhost:3000/api/auth/callback/naver

1. Google Cloud Console 접속
2. 프로젝트 생성
3. OAuth 동의 화면 설정
4. 사용자 인증 정보 > OAuth 2.0 클라이언트 ID 생성
5. Redirect URI: http://localhost:3000/api/auth/callback/google

1. Apple Developer 접속
2. Certificates, Identifiers & Profiles
3. Identifiers > App ID 생성 (Sign in with Apple 활성화)
4. Keys > Sign in with Apple 키 생성
5. Redirect URI: https://yourdomain.com/api/auth/callback/apple

애플 로그인은 HTTPS가 필수입니다.

요구사항

• Next.js 14+
• React 18+

라이센스

MIT