Android 端 Supabase Apple Login

前提条件

本指南将帮助你在 Android 端将 Apple Sign-In 与 Supabase Authentication 进行集成。前提是你已经完成了以下步骤：

• 这个 Supabase Apple Login - 常规设置.

重要提示

由于 Apple 不提供 Android 原生支持，在 Android 上实现 Apple Sign-In 需要后端服务器。我们将使用 Supabase Edge Function 作为后端。

第 1 步：部署后端 Edge Function

首先，我们需要部署用于处理 Apple OAuth 回调的 Supabase Edge Function。

1. 进入你的 Supabase 项目目录

   cd your-project/supabase

2. 创建 edge function （如果尚未创建）

   supabase functions new apple-signin-callback

3. 复制 edge function code

   完整的 edge function 实现可在以下位置找到： 示例应用.

   将以下文件复制到你的项目中：

   • supabase/functions/apple-signin-callback/index.ts - 主 edge function code
   • supabase/functions/apple-signin-callback/deno.json - 依赖项的 import map（包含 jose 用于 JWT 签名的库）

4. 配置 JWT 验证

   Apple OAuth 回调端点必须公开（无需身份验证），因为 Apple 会重定向到该地址。请更新你的 supabase/config.toml 文件：

   [functions.apple-signin-callback]
   enabled = true
   verify_jwt = false  # Important: Set to false for public OAuth callback
   import_map = "./functions/apple-signin-callback/deno.json"
   entrypoint = "./functions/apple-signin-callback/index.ts"

   重要提示

   设置 verify_jwt = false 这会使该端点公开。必须这样做，因为 Apple 的 OAuth 重定向不包含 Supabase 认证请求头。该端点会自行校验 OAuth 流程。

5. 部署函数

   supabase functions deploy apple-signin-callback

6. 获取函数 URL

   部署后，你会获得类似这样的 URL：

   https://your-project-ref.supabase.co/functions/v1/apple-signin-callback

   如果找不到，可以按以下步骤操作：

   1. 打开 https://supabase.com/dashboard/project/YOUR_PROJECT_REF/functions
   2. 点击 apple-signin-callback 点击函数 URL 进行复制。

   保存此 URL

   在下一步配置 Apple Developer Portal 时，您需要用到此 URL。

第 2 步：配置 Apple Developer Portal

现在我们需要在 Apple Developer Portal 中配置后端 URL，并获取所有必需的值。

函数 URL

继续操作前，请确保已获取第 1 步中的 Supabase Edge Function URL。配置 Apple Developer Portal 中的 Return URL 时需要用到它。

1. 按照 Apple Login Android 设置指南操作

   完成 Apple Login Android 设置指南 以进行以下操作：

   • 创建 Service ID
   • 生成私钥（.p8 文件）
   • 获取 Team ID 和 Key ID
   • 配置 Return URL

2. 在 Apple Developer Portal 中设置 Return URL

   在 Apple Developer Portal 中配置 Return URL 时（Apple 指南第 6.9 步），请使用 Supabase Edge Function URL：

   https://your-project-ref.supabase.co/functions/v1/apple-signin-callback

   重要提示：请使用 Supabase Edge Function URL

   切勿 使用来自 Apple Login Android 设置指南的重定向 URL。该指南使用的是自定义后端服务器 URL。对于 Supabase 集成，你应该 必须 改用你的 Supabase Edge Function URL。

   必须完全匹配

   Return URL 必须与 此处配置的内容 完全一致。Apple 对重定向 URI 的匹配要求非常严格。

3. 收集所有必需的值

   完成 Apple 设置指南后，你应该已具备：

   • APPLE_TEAM_ID: 你的 Apple Developer Team ID
   • APPLE_KEY_ID: Apple Developer Portal 中的 Key ID
   • APPLE_PRIVATE_KEY: 你的 .p8 私钥文件（需要进行 base64 编码）
   • ANDROID_SERVICE_ID: 你的 Apple Service ID（例如， com.example.app.service)
   • BASE_REDIRECT_URL: 你的 deep link URL（例如， capgo-demo-app://path)

   Deep Link URL

   本指南中介绍的 BASE_REDIRECT_URL 是在你的 AndroidManifest.xml中配置的 deep link scheme。身份验证后，后端将重定向至此。

   你的 deep link 的值取决于 android:scheme="capgo-demo-app" code。如果你已在 android:scheme="capgo-demo-app" 中设置了 AndroidManifest.xml，那么你的 deep link 将会是 capgo-demo-app://path.

步骤 3：设置 Supabase Secrets

现在我们需要为 Supabase Edge Function 配置环境变量 (secrets)。

1. 对私钥进行编码

   首先，将您的 Apple 私钥 (.p8 文件) 编码为 base64 格式：

   base64 -i AuthKey_XXXXX.p8

   复制全部输出内容（这是一行长字符串）。

2. 使用 Supabase CLI 设置 Secrets

   supabase secrets set APPLE_TEAM_ID=your_team_id
   supabase secrets set APPLE_KEY_ID=your_key_id
   supabase secrets set APPLE_PRIVATE_KEY=your_base64_encoded_key
   supabase secrets set ANDROID_SERVICE_ID=your.service.id
   supabase secrets set BASE_REDIRECT_URL=your-app://path
   supabase secrets set APPLE_REDIRECT_URI=https://your-project-ref.supabase.co/functions/v1/apple-signin-callback

   替换占位符

   将所有占位符替换为第 2 步中获取的实际值。

3. 备选方案：在 Supabase Dashboard 中设置 Secrets

   如果你更倾向于使用 dashboard：

   1. 前往你的 Supabase 项目 dashboard
   2. 前往 Edge Functions → 设置 → Secrets
   3. 添加每个 secret 变量及其对应的值

Android App 配置

本指南中介绍的 Apple Login Android 设置指南 已涵盖 Android app 的配置：

• 将 deep link intent filter 添加到 AndroidManifest.xml
• 将 onNewIntent handler 添加到 MainActivity.java

继续之前，请确保已完成这些步骤。你在此配置的 deep link scheme 将是你的 BASE_REDIRECT_URL 在第 3 步中。

第 4 步：使用 Authentication Helper

现在你可以在应用 code 中使用 authentication helper 了。

实现

完整实现位于 示例应用的 supabaseAuthUtils.ts 文件。

使用 Authentication Helper

import { authenticateWithAppleSupabase } from './supabaseAuthUtils';

const result = await authenticateWithAppleSupabase();
if (result.success) {
  console.log('Signed in:', result.user);
  // Navigate to your authenticated area
} else {
  console.error('Error:', result.error);
}

更新 Helper Function

当使用 authenticateWithAppleSupabase helper function，你 必须 请更新以下值以匹配您的配置：

1. 更新 redirectUrl - 将此项设置为您的 Supabase Edge Function URL：

   const redirectUrl = platform === 'android'
     ? 'https://your-project-ref.supabase.co/functions/v1/apple-signin-callback'
     : undefined;

2. 更新 clientId - 将此项设置为您的 Apple Service ID：

   await SocialLogin.initialize({
     apple: {
       clientId: isIOS
         ? undefined // iOS uses bundle ID automatically
         : 'your.service.id.here', // Your Apple Service ID for Android
       redirectUrl: redirectUrl,
     },
   });

   重要提示

   替换 'your.service.id.here' 使用您真实的 Apple Service ID（即您在 ANDROID_SERVICE_ID 步骤 3 中使用的值）。

请参阅 完整的实现代码 供您参考。

第 5 步：测试集成

1. 构建并运行你的 Android 应用

   npx cap sync android
   npx cap run android

2. 测试身份验证流程

   • 点击“Sign in with Apple”按钮
   • 你应该会在浏览器中看到 Apple OAuth 页面
   • 身份验证完成后，你应该会被重定向回应用
   • 检查控制台 logs 是否有错误

3. 验证流程

   完整的流程应该是：

   1. 用户点击“通过 Apple 登录”
   2. App 打开 Apple OAuth 浏览器
   3. 用户通过 Apple 进行身份验证
   4. Apple 重定向至： https://your-project-ref.supabase.co/functions/v1/apple-signin-callback
   5. Edge function 使用 code 换取 token
   6. Edge function 重定向至： your-app://path?id_token=...&access_token=...
   7. Android App 接收 deep link 并处理 identity token
   8. App 使用 identity token 登录 Supabase

故障排除

如果身份验证失败：

• Redirect URI 不匹配: 请确保 Apple Developer Portal 中的 Return URL 与以下内容完全一致： APPLE_REDIRECT_URI secret
• Deep link 不生效: 请检查 AndroidManifest.xml intent filter 是否与您的 BASE_REDIRECT_URL
• 缺少 secrets: 请使用以下方式验证所有 secrets 是否配置正确： supabase secrets list
• Token 交换失败: 请在 Supabase Dashboard 中查看 edge function logs 以获取详细错误信息
• App 未收到 callback: 请确保 onNewIntent 在 MainActivity 中正确实现
• 请查阅 code 示例应用 供参考

工作原理

在 Android 上，Apple Sign-In 使用 OAuth 重定向流程：

1. 初始化：使用您的 Service ID 和后端重定向 URL 初始化插件
2. OAuth 流程：打开包含 Apple OAuth 页面的浏览器/Chrome Custom Tab
3. 后端回调：Apple 会携带授权 code 重定向至您的 Supabase Edge Function
4. Token 兑换Edge Function 使用 Apple 的 token 端点，将 code 兑换为 token
5. Deep Link 重定向Edge Function 携带 identity token 重定向回你的 App
6. Supabase 身份验证App 收到 token 后登录 Supabase

此流程之所以必要，是因为 Apple 没有为 Android 提供 Sign in with Apple 的原生支持。

继续：Android 端 Supabase Apple Login

如果你正在使用 Android 端 Supabase Apple 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 中的实现细节， 双因素认证 有关双重身份验证的实现细节。