K-Auth Flutter #

한국 앱을 위한 소셜 로그인 SDK. 카카오, 네이버, 구글, 애플을 하나의 API로 구현하세요.

Next.js 버전: k-auth/next

왜 K-Auth인가요? #

설치 #

dependencies:
  k_auth: ^0.2.0

flutter pub add k_auth

빠른 시작 #

1. 초기화 #

import 'package:k_auth/k_auth.dart';

void main() {
  final kAuth = KAuth(
    config: KAuthConfig(
      kakao: KakaoConfig(appKey: 'YOUR_KAKAO_APP_KEY'),
      naver: NaverConfig(
        clientId: 'YOUR_CLIENT_ID',
        clientSecret: 'YOUR_CLIENT_SECRET',
        appName: 'Your App',
      ),
      google: GoogleConfig(),
      apple: AppleConfig(),
    ),
  );

  kAuth.initialize();
  runApp(MyApp());
}

2. 로그인 (함수형 스타일 권장) #

final result = await kAuth.signIn(AuthProvider.kakao);

// ✅ fold: 성공/실패 분기
result.fold(
  onSuccess: (user) => print('환영합니다, ${user.displayName}!'),
  onFailure: (error) => print('로그인 실패: $error'),
);

// ✅ when: 성공/취소/실패 세분화
result.when(
  success: (user) => navigateToHome(user),
  cancelled: () => showToast('로그인을 취소했습니다'),
  failure: (code, msg) => showError(msg),
);

// ✅ 체이닝
result
  .onSuccess((user) => saveUser(user))
  .onFailure((code, msg) => logError(msg));

// ✅ 값 추출
final name = result.mapUserOr((u) => u.displayName, 'Guest');

3. 인증 상태 감지 #

// Firebase Auth 스타일의 Stream
kAuth.authStateChanges.listen((user) {
  if (user != null) {
    print('로그인됨: ${user.displayName}');
  } else {
    print('로그아웃됨');
  }
});

4. 로그아웃 #

// 현재 로그인된 Provider로 자동 로그아웃
await kAuth.signOut();

// 또는 특정 Provider 지정
await kAuth.signOut(AuthProvider.kakao);

5. UI 버튼 #

// 개별 버튼
KakaoLoginButton(
  onPressed: () => kAuth.signInWithKakao(),
)

// 버튼 그룹
LoginButtonGroup(
  providers: kAuth.configuredProviders,
  onPressed: (provider) => kAuth.signIn(provider),
)

6. 자동 로그인 (세션 복원) #

// 1. SessionStorage 구현 (SecureStorage 권장)
class SecureSessionStorage implements KAuthSessionStorage {
  final _storage = FlutterSecureStorage();

  @override
  Future<void> save(String key, String value) =>
    _storage.write(key: key, value: value);

  @override
  Future<String?> read(String key) =>
    _storage.read(key: key);

  @override
  Future<void> delete(String key) =>
    _storage.delete(key: key);

  @override
  Future<void> clear() =>
    _storage.deleteAll();
}

// 2. KAuth에 storage 설정
final kAuth = KAuth(
  config: config,
  storage: SecureSessionStorage(),
);

// 3. 초기화 시 자동 복원
await kAuth.initialize(autoRestore: true);

if (kAuth.isSignedIn) {
  print('자동 로그인 성공: ${kAuth.currentUser?.displayName}');
}

7. 백엔드 연동 #

final kAuth = KAuth(
  config: config,
  // 소셜 로그인 성공 후 자동 호출
  onSignIn: (provider, tokens, user) async {
    // 백엔드 서버에 토큰 전송
    final response = await myApi.socialLogin(
      provider: provider.name,
      accessToken: tokens.accessToken,
      idToken: tokens.idToken,  // Google/Apple OIDC
    );

    // 반환값은 serverToken에 저장됨
    return response.jwt;
  },
  // 로그아웃 시 호출
  onSignOut: (provider) async {
    await myApi.logout();
  },
);

// 로그인 후 serverToken 사용
final result = await kAuth.signIn(AuthProvider.kakao);
if (result.success) {
  print('서버 토큰: ${kAuth.serverToken}');
}

8. 토큰 갱신 #

// 현재 로그인된 Provider로 토큰 갱신
final result = await kAuth.refreshToken();

result.fold(
  onSuccess: (user) => print('토큰 갱신 성공'),
  onFailure: (error) => print('갱신 실패, 재로그인 필요'),
);

// 토큰 만료 임박 확인
if (kAuth.lastResult?.isExpiringSoon() ?? false) {
  await kAuth.refreshToken();
}

⚠️ Apple은 토큰 갱신을 지원하지 않습니다. 재로그인이 필요합니다.

디버그 로깅 #

개발 중 디버깅을 위해 로그를 활성화할 수 있습니다:

// 개발 환경에서 로그 활성화
KAuthLogger.level = KAuthLogLevel.debug;

// 프로덕션에서는 비활성화 (기본값)
KAuthLogger.level = KAuthLogLevel.none;

// 커스텀 로거 (Firebase Crashlytics 등)
KAuthLogger.onLog = (event) {
  if (event.level == KAuthLogLevel.error) {
    FirebaseCrashlytics.instance.recordError(
      event.error,
      event.stackTrace,
      reason: event.message,
    );
  }
};

Provider 설정 #

카카오 #

KakaoConfig(
  appKey: 'YOUR_KAKAO_NATIVE_APP_KEY',  // Native App Key (REST API Key 아님!)
  collect: KakaoCollectOptions(
    email: true,      // 이메일
    profile: true,    // 닉네임, 프로필 이미지
    phone: false,     // 전화번호 (개발자센터 활성화 필요)
    birthday: false,  // 생일
    gender: false,    // 성별
  ),
)

📖 카카오 공식 문서

네이버 #

NaverConfig(
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  appName: 'Your App Name',
)

⚠️ 네이버는 scope 파라미터를 지원하지 않습니다. 수집 항목은 네이버 개발자센터에서 직접 설정하세요.

구글 #

GoogleConfig(
  iosClientId: 'YOUR_IOS_CLIENT_ID',      // iOS 필수
  serverClientId: 'YOUR_SERVER_CLIENT_ID', // 백엔드 연동 시
  forceConsent: true,                      // refresh token 획득
)

📖 Google Cloud Console

애플 #

AppleConfig(
  collect: AppleCollectOptions(
    email: true,
    fullName: true,  // 첫 로그인 시에만 제공
  ),
)

⚠️ iOS 13+, macOS에서만 지원됩니다.

API 레퍼런스 #

KAuthUser (표준화된 사용자 정보) #

AuthResult #

KAuth #

Provider별 지원 기능 #

에러 처리 #

모든 에러는 한글 메시지와 해결 힌트를 포함합니다:

result.when(
  success: (user) => ...,
  cancelled: () => showToast('로그인을 취소했습니다'),
  failure: (code, message) {
    switch (code) {
      case ErrorCodes.networkError:
        showRetryDialog();
        break;
      case ErrorCodes.kakaoPhoneNotEnabled:
        // 힌트: 카카오 개발자센터에서 전화번호 수집을 활성화하세요
        showSettingsGuide();
        break;
      default:
        showError(message);
    }
  },
);

주요 에러 코드 #

설정 진단 #

네이티브 설정이 잘 되어있는지 확인할 수 있습니다:

// 진단 실행
final result = await KAuthDiagnostic.run(kAuth.config);

// 결과 확인
if (result.hasErrors) {
  print(result.prettyPrint());
  // ═══════════════════════════════════════
  //   K-Auth 진단 결과
  // ═══════════════════════════════════════
  // 플랫폼: ios
  //
  // 발견된 문제: 2개
  //   - 에러: 1개
  //   - 경고: 1개
  //
  // ❌ [카카오] URL Scheme이 Info.plist에 등록되지 않았습니다
  //    💡 해결: Info.plist에 kakao{APP_KEY} URL Scheme 추가
  //    📖 문서: https://developers.kakao.com/docs/...
}

// 개별 이슈 처리
for (final issue in result.errors) {
  print('${issue.provider}: ${issue.message}');
  if (issue.solution != null) {
    print('해결: ${issue.solution}');
  }
}

앱 개발 중 설정 문제로 로그인이 안 될 때 유용합니다!

플랫폼 설정 #

💡 설정이 잘 되었는지 확인하려면 KAuthDiagnostic.run()을 사용하세요!

iOS (ios/Runner/Info.plist) #

<!-- 카카오 -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>kakao{YOUR_NATIVE_APP_KEY}</string>
    </array>
  </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>kakaokompassauth</string>
  <string>kakaolink</string>
  <string>kakaoplus</string>
  <string>kakaotalk</string>
</array>

<!-- 구글 -->
<key>GIDClientID</key>
<string>{YOUR_IOS_CLIENT_ID}.apps.googleusercontent.com</string>
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.googleusercontent.apps.{YOUR_CLIENT_ID}</string>
    </array>
  </dict>
</array>

<!-- 네이버 -->
<key>NidClientID</key>
<string>{YOUR_CLIENT_ID}</string>
<key>NidClientSecret</key>
<string>{YOUR_CLIENT_SECRET}</string>
<key>NidAppName</key>
<string>{YOUR_APP_NAME}</string>
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>naversearchapp</string>
  <string>naversearchthirdlogin</string>
</array>

<!-- 애플: Xcode > Signing & Capabilities > + > "Sign in with Apple" 추가 -->

Android #

카카오 (android/app/src/main/AndroidManifest.xml)

<activity
    android:name="com.kakao.sdk.flutter.AuthCodeCustomTabsActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:host="oauth"
              android:scheme="kakao{YOUR_NATIVE_APP_KEY}" />
    </intent-filter>
</activity>

네이버 - MainActivity가 FlutterFragmentActivity를 상속해야 합니다:

// MainActivity.kt
import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity()

<!-- AndroidManifest.xml -->
<application>
  <meta-data android:name="com.naver.sdk.clientId" android:value="@string/client_id" />
  <meta-data android:name="com.naver.sdk.clientSecret" android:value="@string/client_secret" />
  <meta-data android:name="com.naver.sdk.clientName" android:value="@string/client_name" />
</application>

구글 - android/app/google-services.json 파일 추가

마이그레이션 #

0.1.x → 0.2.0 #

// Before
if (result.success) {
  print(result.user!.name);
} else {
  print(result.errorMessage);
}

// After (권장)
result.fold(
  onSuccess: (user) => print(user.name),
  onFailure: (error) => print(error),
);

// Before
await kAuth.signOut(AuthProvider.kakao);

// After (현재 Provider로 자동)
await kAuth.signOut();

라이선스 #

MIT License

관련 링크 #

• GitHub
• pub.dev
• 이슈 등록
• Contributing