跳转到正文

Supabase Google Login - 通用设置

GitHub

本指南将带你使用 Capacitor Social Login 插件,把 Google 登录集成到 Supabase 认证中。这样你就能在移动端使用原生 Google 登录,同时用 Supabase Auth 处理后端认证。

开始之前,请确保您已具备以下条件:

  1. 已创建 Supabase 项目

  2. 阅读 Google Login 常规设置 Google OAuth 凭据设置指南

  3. 已按照各平台对应的指南,为您的目标平台配置好 Google OAuth 凭据:

  1. 前往你的 Supabase 控制台

  2. 点击你的项目

    Supabase 项目选择器
  3. 前往 Authentication 菜单

    Supabase 身份验证菜单
  4. 点击 Providers 选项卡

    Supabase 提供商标签页
  5. 找到 Google 提供方

    Supabase Google 提供商
  6. 启用该提供商

    启用 Supabase Google Provider
  7. 添加你计划使用的各平台 Client ID

    为 Supabase Google Provider 添加 Client ID
  8. 点击 Save 按钮

    Supabase Google Provider 保存

搞定,你现在已经通过 Supabase Authentication 启用了 Google 登录 🎉

Supabase 身份验证助手中的 Google 登录工作原理

章节标题:“Supabase 身份验证助手中的 Google 登录工作原理”

本节介绍 Google 登录与 Supabase 集成的底层工作原理。了解此流程有助于你实现和排查身份验证过程中的问题。

该实现遵循 Supabase nonce 要求:

// Generate URL-safe random nonce
function 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-256
async 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 pair
async 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 比对

该函数初始化插件并使用 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
},
});

在把 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,有几个重要作用:

  1. 避免无效请求:如果 token 的 audience 不正确或 nonce 不匹配,Supabase 反正也会拒绝该 token。提前校验可以避免不必要的 API 调用,并给出更清晰的错误信息。

  2. Token 缓存问题:在某些平台(尤其是 iOS)上,Google Sign-In SDK 为了性能会缓存 token。返回缓存 token 时,该 token 可能是用不同的 nonce(或根本没有 nonce)生成的,导致 Supabase 以“nonce mismatch”错误拒绝该 token。在发送给 Supabase 之前先校验,我们就能尽早发现这个问题,并自动用新的 token 重试。

  3. 安全 (iOS):在 iOS 上,校验可确保 token 是为你的特定 Google Client ID 签发的,避免因使用原本面向其他应用的 token 而带来潜在安全问题。

  4. 更好的错误处理:在 Supabase 之前检测问题可实现自动重试逻辑,这对于透明处理 iOS 缓存问题至关重要。

如果验证失败,函数会自动:

  1. 从 Google 登出(清除缓存的 token - 在 iOS 上至关重要)
  2. 重试一次身份验证(强制使用正确的 nonce 生成新 token)
  3. 如果重试也失败,则返回错误

最后,将经过验证的 token 发送到 Supabase:

const { data, error } = await supabase.auth.signInWithIdToken({
provider: 'google',
token: googleResponse.idToken,
nonce: rawNonce, // Pass the raw (unhashed) nonce
});

完整实现位于 示例应用的 supabaseAuthUtils.ts 文件,其中包含:

  • getUrlSafeNonce() - 生成 URL 安全的随机 nonce
  • sha256Hash() - 使用 SHA-256 对字符串进行哈希
  • getNonce() - 生成 nonce 对
  • decodeJWT() - 解码 JWT token
  • validateJWTToken() - 验证 JWT 受众和 nonce
  • authenticateWithGoogleSupabase() - 带有自动重试的主认证函数

请前往目标平台的平台专属设置指南:

从 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 中的实现细节, 双因素认证 有关双重身份验证的实现细节。