设置 Supabase 认证与 Capacitor 社会登录插件

在移动应用中设置认证可能会很复杂，但结合使用 Supabase 和 __CAPGO_KEEP_0__ 社交登录插件可以 Supabase 与 Capgo 社交登录插件 让它变得简单。这一教程将指导您在Capacitor应用中集成社交身份验证（Google、Apple、Facebook）和 Supabase。

Supabase 提供了一个强大的后端即服务（BaaS）以及内置的身份验证，而插件 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login 提供了原生社交身份验证，支持 iOS、Android 和 web 平台。为了实现更紧密的 Supabase 集成，@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-supabase 添加了原生身份验证助手和 JWT 访问权限。他们一起提供： @capgo/capacitor-social-login 安全令牌管理 @capgo/capacitor-supabase 实时数据库集成

Why Use Supabase with Social Login?
Supabase
provides a robust backend-as-a-service with built-in authentication, while the
@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login
Built-in user management

前置条件

开始之前，请确保您有：

一个 Capacitor 项目设置
一个 Supabase 账户和项目
您选择的社交提供商的开发者帐户（Google、Apple、Facebook）

首先，安装 Capgo 社交登录插件：

npm install @capgo/capacitor-social-login
npx cap sync

查看社交登录和 Supabase 为平台特定设置的插件页面。

步骤 2：设置 Supabase 项目

创建和配置您的 Supabase 项目

创建 Supabase 项目:
- 前往 supabase.com 并注册/登录
- 点击 “新项目”
- 选择您的组织
- 输入一个 项目名称 (例如，"MyApp Auth")
- 设置一个 数据库密码 (安全保存)
- 选择你的区域 (选择离用户最近的)
- 点击 "创建新项目"
获取你的项目凭证:
- 创建后，前往 设置 > API
- 复制你的 项目URL (例如 https://your-project-ref.supabase.co)
- 复制你的 匿名公共 API密钥
- 将这些用于后续在应用中

配置身份验证设置

设置通用身份验证设置:
- 前往 身份验证>设置
- 在 全局设置:
  - 设置 站点URL 到您的应用程序URL（例如， https://yourdomain.com 或 http://localhost:3000 用于开发
  - 添加额外 重定向URL 如果需要：
```
http://localhost:3000
https://yourdomain.com
capacitor://localhost (for mobile apps)
```
配置电子邮件设置 （可选但推荐：
- 在 SMTP 设置配置您的电子邮件提供商
- 此功能启用电子邮件确认和密码重置
- 对于开发，您可以使用内置的电子邮件服务

访问提供商部分:
- 前往 身份验证 > 提供商 在您的 Supabase 控制台中
- 您将看到可用的社交提供商列表
- 每个提供商都有一个启用开关和配置选项

现在让我们详细配置每个社交提供商：

在 Supabase 中设置 Google 认证

首先，获取您的 Google OAuth 凭证：

遵循我们的全面 Google 设置指南： Google 认证设置

本指南涵盖：

创建 Google 云项目
为 Web、iOS 和 Android 配置 OAuth 2.0 凭证
配置-consent 屏幕
获取所需的 Client ID 和密钥

完成Google设置后，配置它在Supabase中：

在Supabase中启用Google提供者:
- 在您的Supabase控制台中，前往 身份验证 > 提供者
- 找到 Google 并将其切换到 ON
- 填写配置：
  - 客户端ID:您的Google OAuth Web Client ID (from the Google Cloud Console)
  - Client Secret: 您的 Google OAuth Web Client Secret
  - Redirect URL: https://your-project-ref.supabase.co/auth/v1/callback (auto-filled)
- 点击 “Save”

重要: 使用的 Web Client ID 和 Web 客户端密钥 即使您正在构建移动应用程序，在 Supabase 中也可以使用这些密钥。移动客户端 ID 在插件配置中单独使用。

在 Supabase 中设置 Apple 认证

获取 Apple 凭证：

遵循我们的详细 Apple 配置指南： Apple 认证设置

本指南涵盖：

设置 Apple 开发者帐户
创建 App ID 和 Service ID
配置 Sign in with Apple 功能
生成所需的私钥
iOS、Android和Web平台的特定设置

完成Apple设置后，在Supabase中配置：

在Supabase中启用Apple提供者：:
- 前往 身份验证>提供者 并切换 Apple 开启
- 填写配置：
  - Client ID: 你的Service ID标识符（例如 com.yourapp.signin)
  - Client Secret: 使用您的 Apple 私钥生成此 JWT（参见 Supabase Apple 文档为 JWT 格式
  - 重定向 URL: https://your-project-ref.supabase.co/auth/v1/callback (自动填充)
- 点击 “保存”

注意: Apple 认证设置是最复杂的，因为 Apple 对 Service IDs、私钥和 JWT 生成有特定的要求。请仔细阅读每个平台的文档。

在 Supabase 中设置 Facebook 认证

获取 Facebook 凭证：

请参阅我们的完整 Facebook 设置指南： Facebook 登录设置

本指南涵盖：

创建 Facebook 开发者帐户和应用
添加 Facebook 登录产品
配置 OAuth 重定向 URI
获取您的 App ID、App Secret 和 Client Token
iOS 和 Android 平台的特定配置

完成 Facebook 设置后，在 Supabase 中配置：

在 Supabase 中启用 Facebook 提供者:
- 前往 身份验证 > 提供者 并切换开关 Facebook ON
- 填写配置：
  - 客户端 ID：您的 Facebook App ID
  - 客户端密钥：您的 Facebook App Secret
  - 重定向 URL: https://your-project-ref.supabase.co/auth/v1/callback (自动填充)
- 点击 “保存”

重要: 确保将 Supabase 回调 URL (https://your-project-ref.supabase.co/auth/v1/callback) 添加到您的 Facebook 应用程序的 Facebook 登录设置中的有效 OAuth 重定向 URI Facebook 登录设置中的有效 OAuth 重定向 URI

重要的 Supabase 配置说明

行级安全性 (RLS):

在设置身份验证后，启用表格的 RLS
前往 数据库 > 表格 并切换 启用 RLS 为每个表格
根据已验证用户创建数据访问策略

用户管理：

查看已验证用户在 身份验证 > 用户
在 身份验证 > 日志
在 身份验证 > 邮件模板

测试配置：

使用 Supabase 内置身份验证测试工具
前往 身份验证 > 用户 点击并 “Invite user” 测试电子邮件流程
检查日志查看任何身份验证错误

现在，Supabase 已配置好，您需要使用相应凭证设置社交登录插件。 重要提示：插件需要从 原始提供商处获取 OAuth 凭证（而不是从 Supabase），而 Supabase 负责服务器端身份验证。 __CAPGO_KEEP_0__

How the Authentication Flow Works

在了解配置之前，了解流程：

插件验证 与社交提供者 (Google/Apple/Facebook) 本地验证
插件接收令牌 (访问令牌，ID令牌) 从提供者
您的应用程序将这些令牌 发送到 Supabase 使用 signInWithIdToken()
Supabase 验证 令牌与提供者并创建用户会话
Supabase 返回 其自己的 JWT 令牌用于您的应用程序的已验证请求

Google 插件配置

该插件需要您的 Web 客户端 ID 所有平台和可选的 iOS 客户端 ID iOS 特定功能：

import { SocialLogin } from '@capgo/capacitor-social-login';

await SocialLogin.initialize({
  google: {
    // Use the same Web Client ID you configured in Supabase
    webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
    
    // Optional: iOS Client ID for iOS-specific features
    iOSClientId: 'YOUR_IOS_CLIENT_ID.apps.googleusercontent.com',
    
    // Optional: Request offline access for refresh tokens
    mode: 'offline'
  }
});

Google 的关键点：

使用 Web 客户端 ID （而不是 Android/iOS 客户端 ID）填写 webClientId 字段
该插件将在所有平台上正常工作，只需使用 Web 客户端 ID
The iOSClientId 是可选的，仅用于 iOS 特有的 Google 功能

Apple 插件配置

Apple 配置在 iOS 和 Android 之间有所不同：

对于 iOS (本机 Apple 登录):

await SocialLogin.initialize({
  apple: {
    // No additional configuration needed for iOS
    // The plugin uses the native Apple Sign-In capability
  }
});

对于 Android/Web (需要 Service ID):

await SocialLogin.initialize({
  apple: {
    clientId: 'YOUR_SERVICE_ID', // The Service ID from Apple Developer Portal
    redirectUrl: 'https://your-project-ref.supabase.co/auth/v1/callback'
  }
});

Apple 的关键点：

iOS 使用本机 Sign in with Apple (无需额外配置)
Android/Web 需要您在 Apple Developer Portal 中创建的 Service ID
The redirectUrl 应与您在 Apple Developer Portal 和 Supabase 中配置的内容相匹配

Facebook 插件配置

Facebook 需要您的 App ID 和 Client Token:

await SocialLogin.initialize({
  facebook: {
    appId: 'YOUR_FACEBOOK_APP_ID',        // From Facebook Developer Dashboard
    clientToken: 'YOUR_FACEBOOK_CLIENT_TOKEN', // From Facebook Developer Dashboard
    
    // Optional: Use Facebook Limited Login (for enhanced privacy)
    limitedLogin: false // See our Facebook setup guide for important Limited Login details
  }
});

Facebook 的关键点:

使用您在 Supabase 中配置的相同 App ID
Client Token 可在您的 Facebook App 的基本设置中找到
limitedLogin: true 启用 Facebook 的 iOS-only privacy-focused Limited Login 功能
重要: 查看我们的 Facebook 设置指南以获取有关 Limited Login 的详细信息，包括 ATT 考虑因素

完成插件初始化

初始化所有提供者：

import { SocialLogin } from '@capgo/capacitor-social-login';

export async function initializeSocialLogin() {
  await SocialLogin.initialize({
    google: {
      webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
      mode: 'offline'
    },
    facebook: {
      appId: 'YOUR_FACEBOOK_APP_ID',
      clientToken: 'YOUR_FACEBOOK_CLIENT_TOKEN',
    },
    apple: {
      // iOS: no config needed
      // Android/Web: uncomment the lines below
      // clientId: 'YOUR_SERVICE_ID',
      // redirectUrl: 'https://your-project-ref.supabase.co/auth/v1/callback'
    }
  });
}

重要说明：

在应用启动时调用一次，不要在每次登录前调用 initialize() 只需配置您打算使用的提供者 以下凭据来自
原提供者
确保提供者凭据与您在 Supabase 中配置的凭据匹配 步骤 5：设置 Supabase 客户端安装 Supabase 客户端：
__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

npm install @supabase/supabase-js

创建一个 Supabase 服务：

// services/supabase.ts
import { createClient } from '@supabase/supabase-js';

const supabaseUrl = 'https://your-project-ref.supabase.co';
const supabaseKey = 'your-anon-public-key';

export const supabase = createClient(supabaseUrl, supabaseKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
  },
});

步骤 6：实现身份验证流程

创建一个身份验证服务，结合两者：

// services/auth.ts
import { SocialLogin } from '@capgo/capacitor-social-login';
import { supabase } from './supabase';

export class AuthService {
  
  async initializeSocialLogin() {
    await SocialLogin.initialize({
      google: {
        webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
      },
      facebook: {
        appId: 'YOUR_FACEBOOK_APP_ID',
        clientToken: 'YOUR_FACEBOOK_CLIENT_TOKEN',
      },
      apple: {} // iOS configuration
    });
  }

  async signInWithGoogle() {
    try {
      const result = await SocialLogin.login({
        provider: 'google',
        options: {
          scopes: ['email', 'profile']
        }
      });

      const googleResult = result.result;
      if (!googleResult) {
        throw new Error('Google login failed');
      }

      // GoogleLoginResponse is a union type - check responseType to determine flow
      if (googleResult.responseType === 'online') {
        // Online mode: use idToken directly with Supabase
        const { data, error } = await supabase.auth.signInWithIdToken({
          provider: 'google',
          token: googleResult.idToken!,
        });
        if (error) throw error;
        return data;
      } else {
        // Offline mode: exchange serverAuthCode on your backend
        // Your backend should exchange the code for tokens and create a Supabase session
        const response = await fetch('/api/auth/google', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ serverAuthCode: googleResult.serverAuthCode })
        });
        return response.json();
      }
    } catch (error) {
      console.error('Google sign-in error:', error);
      throw error;
    }
  }

  async signInWithApple() {
    try {
      const result = await SocialLogin.login({
        provider: 'apple',
        options: {
          scopes: ['email', 'name']
        }
      });

      const { data, error } = await supabase.auth.signInWithIdToken({
        provider: 'apple',
        token: result.result?.identityToken!,
      });

      if (error) throw error;
      return data;
    } catch (error) {
      console.error('Apple sign-in error:', error);
      throw error;
    }
  }

  async signInWithFacebook() {
    try {
      const result = await SocialLogin.login({
        provider: 'facebook',
        options: {
          permissions: ['email', 'public_profile']
        }
      });

      const fbResult = result.result;
      if (!fbResult?.accessToken?.token) {
        throw new Error('Facebook login failed - no access token received');
      }

      // Facebook uses accessToken for Supabase authentication
      const { data, error } = await supabase.auth.signInWithIdToken({
        provider: 'facebook',
        token: fbResult.accessToken.token,
      });

      if (error) throw error;
      return data;
    } catch (error) {
      console.error('Facebook sign-in error:', error);
      throw error;
    }
  }

  async signOut() {
    // Sign out from Supabase
    await supabase.auth.signOut();
    
    // Optionally sign out from social providers
    await SocialLogin.logout({
      provider: 'google' // or 'apple', 'facebook'
    });
  }

  getCurrentUser() {
    return supabase.auth.getUser();
  }

  onAuthStateChange(callback: (event: string, session: any) => void) {
    return supabase.auth.onAuthStateChange(callback);
  }
}

export const authService = new AuthService();

步骤 7：在您的应用中实现

初始化服务并处理身份验证：

// main.ts or app component
import { authService } from './services/auth';

async function initializeApp() {
  await authService.initializeSocialLogin();
  
  // Listen to auth state changes
  authService.onAuthStateChange((event, session) => {
    if (event === 'SIGNED_IN') {
      console.log('User signed in:', session.user);
      // Redirect to authenticated area
    } else if (event === 'SIGNED_OUT') {
      console.log('User signed out');
      // Redirect to login
    }
  });
}

initializeApp();

在您的 UI 中创建登录按钮：

// Login component
async function handleGoogleLogin() {
  try {
    const user = await authService.signInWithGoogle();
    console.log('Signed in with Google:', user);
  } catch (error) {
    console.error('Login failed:', error);
  }
}

async function handleAppleLogin() {
  try {
    const user = await authService.signInWithApple();
    console.log('Signed in with Apple:', user);
  } catch (error) {
    console.error('Login failed:', error);
  }
}

async function handleFacebookLogin() {
  try {
    const user = await authService.signInWithFacebook();
    console.log('Signed in with Facebook:', user);
  } catch (error) {
    console.error('Login failed:', error);
  }
}

async function handleLogout() {
  try {
    await authService.signOut();
    console.log('Signed out successfully');
  } catch (error) {
    console.error('Logout failed:', error);
  }
}

步骤 8：平台特定配置

iOS 配置

有关详细的 iOS 配置说明，请参见我们的平台特定指南：

Google iOS 配置 - URL 方案，Info.plist 配置
Apple iOS 配置 - 使用 Apple 能力登录设置
Facebook iOS 设置 (一般的 Facebook 指南) - Facebook SDK 配置

快速概要 - 添加到 ios/App/App/Info.plist:

<!-- Google Sign-In URL scheme -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_REVERSED_CLIENT_ID</string>
    </array>
  </dict>
</array>

<!-- Apple Sign-In capability -->
<key>com.apple.developer.applesignin</key>
<array>
  <string>Default</string>
</array>

请参阅我们的平台特定指南，了解详细的 iOS 设置指南，包括 Xcode 项目配置。

Android 配置

有关详细的 Android 设置指南，请参阅我们的平台特定指南：

Google Android 设置 - SHA-1 指纹，Google Play 服务配置
Apple Android 设置 - Android 服务 ID 配置
Facebook Android 配置 (一般的 Facebook 指南) - Facebook SDK 集成

Android 必备配置:

1. 获取 SHA-1 指纹 (用于 Google):

# For debug builds (development)
cd android
./gradlew signingReport

# Look for the SHA1 fingerprint under "Variant: debug"
# Add this SHA1 to your Google Cloud Console Android OAuth client

2. 配置 AndroidManifest.xml - 添加到 android/app/src/main/AndroidManifest.xml:

<!-- Internet permission -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Facebook configuration -->
<meta-data 
  android:name="com.facebook.sdk.ApplicationId" 
  android:value="@string/facebook_app_id"/>
<meta-data 
  android:name="com.facebook.sdk.ClientToken" 
  android:value="@string/facebook_client_token"/>

3. 添加 Facebook 资源 到 android/app/src/main/res/values/strings.xml:

<string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
<string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>

按照链接的平台指南完成 Android 配置，包括 Google Play Services 配置和包名配置。

步骤 9: 使用 Supabase 数据库与已验证用户

一旦用户验证成功，您就可以使用 Supabase 的数据库，带有行级安全性 (RLS):

// Example: Fetch user profile
async function getUserProfile() {
  const { data: user } = await supabase.auth.getUser();
  
  if (user) {
    const { data, error } = await supabase
      .from('profiles')
      .select('*')
      .eq('id', user.user.id)
      .single();
    
    return data;
  }
}

// Example: Update user profile
async function updateUserProfile(updates: any) {
  const { data: user } = await supabase.auth.getUser();
  
  if (user) {
    const { data, error } = await supabase
      .from('profiles')
      .update(updates)
      .eq('id', user.user.id);
    
    return data;
  }
}

重要的安全注意事项

绝不暴露敏感密钥 在您的客户端 code
使用环境变量 进行配置
在 Supabase 中启用行级安全性 在您的后端验证令牌
如果需要 处理令牌刷新
targetLanguage 与 Supabase 自动同步

常见问题排查

令牌不匹配错误

确保社交登录插件和 Supabase 的 OAuth 提供商配置一致
检查重定向 URL 是否正确配置

平台特定问题

iOS：验证您的 bundle ID 与 Apple Developer 配置一致
Android：确保 SHA1 指纹正确添加到 Google Console

身份验证流程中断

实现网络问题的适当错误处理
在身份验证期间添加加载状态

结论

You now have a complete authentication system combining Supabase’s robust backend with native social login capabilities. This setup provides:

安全的原生社交验证
无缝令牌管理
实时数据库集成
跨平台兼容性

Supabase 和 Capgo 社交登录插件的结合提供了一个强大的、可扩展的验证解决方案，适用于您的 Capacitor 应用。

如需更高级的功能，如 多因素验证 或 自定义声明, 请参阅 Supabase 文档 and the Social Login plugin 文档.

如果您正在使用 Setup Supabase Authentication with Capacitor Social Login Plugin 来规划身份验证和帐户流程，连接它与 @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中了解实现细节 @capgo/capacitor-passkey 在 @capgo/capacitor-passkey 中了解实现细节 @capgo/capacitor-native-biometric 在 @capgo/capacitor-native-biometric 中了解实现细节 Two-factor authentication 为 Two-factor authentication 的实现细节, 和 SSO (Enterprise) 为 SSO (Enterprise) 的实现细节。

设置 Supabase 认证与 Capacitor 社交登录插件

为什么要使用 Supabase 与社交登录?

前置条件

步骤 1：安装和配置社交登录插件

步骤 2：设置 Supabase 项目

创建和配置您的 Supabase 项目

配置身份验证设置

启用社交身份验证提供商

步骤 3：在 Supabase 中配置社交提供商

在 Supabase 中设置 Google 认证

在 Supabase 中设置 Apple 认证

在 Supabase 中设置 Facebook 认证

重要的 Supabase 配置说明

步骤 4：配置社交登录插件

How the Authentication Flow Works

Google 插件配置

Apple 插件配置

Facebook 插件配置

完成插件初始化

__CAPGO_KEEP_0__

步骤 6：实现身份验证流程

步骤 7：在您的应用中实现

步骤 8：平台特定配置

iOS 配置

Android 配置

步骤 9: 使用 Supabase 数据库与已验证用户

重要的安全注意事项

常见问题排查

令牌不匹配错误

平台特定问题

身份验证流程中断

结论

继续 Setup Supabase Authentication with Capacitor Social Login Plugin