Supabase Google Login - 일반 설정
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
소개
“소개” 섹션Capacitor Social Login 플러그인을 사용해 Supabase Authentication에 Google Sign-In을 통합하는 방법을 안내합니다. 이 설정을 사용하면 모바일 플랫폼에서 네이티브 Google Sign-In을 사용하고, 백엔드 인증은 Supabase Auth로 처리할 수 있습니다.
사전 요구사항
“사전 준비 사항” 섹션시작하기 전에 다음 사항을 확인하세요:
-
앱 스위처 동작에 대한 Google Login 기본 설정 Google OAuth 자격 증명 설정 가이드
-
대상 플랫폼에 맞는 각 플랫폼별 가이드를 따라 Google OAuth 자격 증명 설정 완료:
Supabase에서 Google OAuth 프로바이더 활성화하기
“Supabase에서 Google OAuth 프로바이더 활성화하기” 섹션-
다음으로 이동하세요: Supabase 대시보드
-
프로젝트 클릭
-
다음으로 이동하세요:
Authentication메뉴
-
다음을 클릭하세요:
Providers탭
-
다음
Google프로바이더
-
Provider 활성화
-
사용할 플랫폼의 Client ID 추가
-
다음을 클릭하세요:
Save버튼을 클릭하세요
자, 이제 Supabase Authentication으로 Google Sign-In을 활성화했습니다 🎉
Supabase Authentication Helper를 이용한 Google Sign-In 동작 방식
“Supabase Authentication Helper를 사용한 Google Sign-In 작동 방식” 섹션이 섹션은 Supabase와 Google Sign-In 통합이 내부적으로 어떻게 작동하는지 설명합니다. 이 플로우를 이해하면 인증 프로세스를 구현하고 문제를 해결하는 데 도움이 됩니다.
1. Nonce 생성
“1. Nonce 생성” 섹션구현에서는 안전한 nonce 쌍을 생성하며, 다음을 따릅니다: Supabase nonce 요구 사항:
// Generate URL-safe random noncefunction getUrlSafeNonce(): string { const array = new Uint8Array(32); crypto.getRandomValues(array); return Array.from(array, (byte) => byte.toString(16).padStart(2, '0')).join('');}
// Hash the nonce with SHA-256async function sha256Hash(message: string): Promise<string> { const encoder = new TextEncoder(); const data = encoder.encode(message); const hashBuffer = await crypto.subtle.digest('SHA-256', data); const hashArray = Array.from(new Uint8Array(hashBuffer)); return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');}
// Generate nonce pairasync function getNonce(): Promise<{ rawNonce: string; nonceDigest: string }> { const rawNonce = getUrlSafeNonce(); const nonceDigest = await sha256Hash(rawNonce); return { rawNonce, nonceDigest };}플로우:
rawNonce: URL-safe 랜덤 문자열 (64자리 16진수)nonceDigest: SHA-256 해시rawNonce(16진수 인코딩)nonceDigest을 Google Sign-In에 전달 → Google이 nonce digest를 ID 토큰에 포함rawNonce을 Supabase에 전달 → Supabase가 raw nonce를 해시한 뒤 토큰의 nonce와 비교
2. Google Sign-In
“2. Google Sign-In” 섹션이 함수는 플러그인을 초기화하고 Google로 로그인합니다:
await SocialLogin.initialize({ google: { webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com', // iOS only: iOSClientId: 'YOUR_IOS_CLIENT_ID.apps.googleusercontent.com', mode: 'online', // Required to get idToken },});
const response = await SocialLogin.login({ provider: 'google', options: { scopes: ['email', 'profile'], nonce: nonceDigest, // Pass the SHA-256 hashed nonce },});3. JWT 검증
“3. JWT 검증” 섹션토큰을 Supabase로 보내기 전에, 구현부에서 JWT 토큰을 검증합니다:
function validateJWTToken(idToken: string, expectedNonceDigest: string): { valid: boolean; error?: string } { const decodedToken = decodeJWT(idToken);
// Check audience matches your Google Client IDs const audience = decodedToken.aud; if (!VALID_GOOGLE_CLIENT_IDS.includes(audience)) { return { valid: false, error: 'Invalid audience' }; }
// Check nonce matches const tokenNonce = decodedToken.nonce; if (tokenNonce && tokenNonce !== expectedNonceDigest) { return { valid: false, error: 'Nonce mismatch' }; }
return { valid: true };}왜 Supabase로 보내기 전에 검증해야 하나요?
Supabase로 토큰을 보내기 전 JWT 토큰을 검증하면 다음과 같은 중요한 이점이 있습니다:
-
잘못된 요청 방지: audience가 잘못되었거나 nonce가 일치하지 않으면 어차피 Supabase에서 토큰을 거절합니다. 미리 검증하면 불필요한 API 호출을 막고 더 명확한 에러 메시지를 제공할 수 있습니다.
-
토큰 캐싱 문제: 일부 플랫폼(특히 iOS)에서는 성능을 위해 Google Sign-In SDK이 토큰을 캐싱할 수 있습니다. 캐싱된 토큰이 반환될 때 해당 토큰이 다른 nonce로 생성되었거나 nonce가 아예 없을 수 있어, Supabase에서 “nonce mismatch” 에러와 함께 거절될 수 있습니다. Supabase로 보내기 전에 검증하면 이 문제를 조기에 감지하고 새로운 토큰으로 자동 재시도할 수 있습니다.
-
보안 (iOS): iOS에서는 검증을 통해 토큰이 지정한 Google Client ID용으로 발급되었는지 확인하므로, 다른 앱용 토큰을 사용해 발생할 수 있는 보안 문제를 방지합니다.
-
더 나은 에러 핸들링: Supabase 이전에 문제를 감지하면 자동 재시도 로직을 구현할 수 있으며, 이는 iOS 캐싱 문제를 투명하게 처리하는 데 필수적입니다.
검증이 실패하면 함수가 자동으로 수행하는 작업:
- Google에서 로그아웃 (캐시된 토큰 삭제 - iOS에서 중요)
- 인증 재시도 1회 (올바른 nonce로 새 토큰 생성 강제)
- 재시도도 실패하면 오류 반환
4. Supabase 로그인
“4. Supabase Sign-In” 섹션마지막으로, 검증된 토큰을 Supabase로 전송합니다:
const { data, error } = await supabase.auth.signInWithIdToken({ provider: 'google', token: googleResponse.idToken, nonce: rawNonce, // Pass the raw (unhashed) nonce});Code 전체 레퍼런스
“Code 전체 참고” 섹션전체 구현 코드는 예제 앱의 supabaseAuthUtils.ts 파일이며, 다음을 포함합니다:
getUrlSafeNonce()- URL-safe 랜덤 nonce 생성sha256Hash()- SHA-256으로 문자열 해시getNonce()- nonce 쌍 생성decodeJWT()- JWT 토큰 디코딩validateJWTToken()- JWT audience 및 nonce 검증authenticateWithGoogleSupabase()- 자동 재시도 기능이 포함된 메인 인증 함수
추가 예제 파일
“추가 예제 파일” 섹션- SupabasePage.tsx - 리다이렉트 처리가 포함된 예제 컴포넌트 (Web)
- SupabaseCreateAccountPage.tsx - 예제 계정 생성 페이지
다음 단계
“다음 단계” 섹션대상 플랫폼별 설정 가이드를 참고하세요:
Supabase Google Login - 일반 설정에서 계속하기
“Supabase Google Login - 일반 설정”에서 계속하기 섹션사용 중이라면 Supabase Google Login - 일반 설정 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-social-login 사용하기 @capgo/capacitor-social-login 사용 시 네이티브 기능을 위해, @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은, 2단계 인증 2단계 인증의 구현 세부 사항에 대해서는