Supabase Google Login - 通用设置
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
本指南将带你使用 Capacitor Social Login 插件,把 Google 登录集成到 Supabase 认证中。这样你就能在移动端使用原生 Google 登录,同时用 Supabase Auth 处理后端认证。
前提条件
“前提条件”章节开始之前,请确保您已具备以下条件:
-
阅读 Google Login 常规设置 Google OAuth 凭据设置指南
-
已按照各平台对应的指南,为您的目标平台配置好 Google OAuth 凭据:
在 Supabase 中启用 Google OAuth 提供商
标题为“在 Supabase 中启用 Google OAuth 提供商”的章节-
前往你的 Supabase 控制台
-
点击你的项目
-
前往
Authentication菜单
-
点击
Providers选项卡
-
找到
Google提供方
-
启用该提供商
-
添加你计划使用的各平台 Client ID
-
点击
Save按钮
搞定,你现在已经通过 Supabase Authentication 启用了 Google 登录 🎉
Supabase 身份验证助手中的 Google 登录工作原理
章节标题:“Supabase 身份验证助手中的 Google 登录工作原理”本节介绍 Google 登录与 Supabase 集成的底层工作原理。了解此流程有助于你实现和排查身份验证过程中的问题。
1. Nonce 生成
章节标题:“1. 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 安全的随机字符串(64 个十六进制字符)nonceDigest:SHA-256 哈希值,对象为rawNonce(十六进制编码)nonceDigest传递给 Google Sign-In → Google 会将 nonce 摘要包含在 ID token 中rawNonce传递给 Supabase → Supabase 会对原始 nonce 做哈希,并与 token 中的 nonce 比对
2. Google 登录
标题为 “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 Validation” 的章节在把 token 发送给 Supabase 之前,实现会先校验 JWT token:
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 之前校验?
在把 token 发送给 Supabase 之前先校验 JWT token,有几个重要作用:
-
避免无效请求:如果 token 的 audience 不正确或 nonce 不匹配,Supabase 反正也会拒绝该 token。提前校验可以避免不必要的 API 调用,并给出更清晰的错误信息。
-
Token 缓存问题:在某些平台(尤其是 iOS)上,Google Sign-In SDK 为了性能会缓存 token。返回缓存 token 时,该 token 可能是用不同的 nonce(或根本没有 nonce)生成的,导致 Supabase 以“nonce mismatch”错误拒绝该 token。在发送给 Supabase 之前先校验,我们就能尽早发现这个问题,并自动用新的 token 重试。
-
安全 (iOS):在 iOS 上,校验可确保 token 是为你的特定 Google Client ID 签发的,避免因使用原本面向其他应用的 token 而带来潜在安全问题。
-
更好的错误处理:在 Supabase 之前检测问题可实现自动重试逻辑,这对于透明处理 iOS 缓存问题至关重要。
如果验证失败,函数会自动:
- 从 Google 登出(清除缓存的 token - 在 iOS 上至关重要)
- 重试一次身份验证(强制使用正确的 nonce 生成新 token)
- 如果重试也失败,则返回错误
4. Supabase 登录
标题为“4. Supabase 登录”的章节最后,将经过验证的 token 发送到 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 安全的随机 noncesha256Hash()- 使用 SHA-256 对字符串进行哈希getNonce()- 生成 nonce 对decodeJWT()- 解码 JWT tokenvalidateJWTToken()- 验证 JWT 受众和 nonceauthenticateWithGoogleSupabase()- 带有自动重试的主认证函数
附加示例文件
标题为“附加示例文件”的章节- SupabasePage.tsx - 带有重定向处理的示例组件(Web)
- SupabaseCreateAccountPage.tsx - 创建账号页示例
下一步
“后续步骤”章节请前往目标平台的平台专属设置指南:
从 Supabase Google Login - General Setup 继续
标题为“从 Supabase Google Login - General Setup 继续”的章节如果你正在使用 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 中的实现细节, 双因素认证 有关双重身份验证的实现细节。