如何在Capacitor应用中添加身份验证（2026）

要添加身份验证到Capacitor应用，选择一个身份源（您自己的后端、托管服务如 Firebase 或 Supabase、OIDC 提供者如 Auth0、Okta 或 Entra ID、或自托管库如 Better Auth），使用 native 插件打开提供者登录页面的任何内容、在服务器上验证令牌，并将会话结果存储在 Keychain 或 Keystore 中。生物识别和 passkeys 然后使下一次登录更快。

本指南将每种常见选项映射到正确的Capacitor插件和流程，code用于每个应用中相同的部分：登录调用、令牌验证、会话存储和生物识别解锁。它已更新至Capacitor 8 月份 2026 年。每个提供者都有自己的步骤指南，链接在下面。

Capacitor应用最终的身份验证流程

无论您选择哪个提供商，形状都是相同的：

1. 识别 用户：本地社交表单、系统浏览器中的提供商登录页面、密钥提示或发送电子邮件和密码的表单。
2. 获取凭证: an ID token, an authorization code, or a session token from your auth server.
3. 在服务器端验证: 检查签名、发行者、受众和过期时间，然后创建或找到用户。
4. 颁发会话: 使用自己的令牌或提供商的令牌，带有刷新策略。
5. 安全存储 在设备上并将其附加到API调用。
6. 快速解锁 下一次使用生物识别，处理注销和账户删除。

步骤 1 和 2 根据提供商而变化，步骤 3 到 6 在所有选项中都是您的责任，除了完全托管的 BaaS，SDK 会处理大部分工作。

为什么 WebView 登录页面会出现问题。

一个 Capacitor 应用程序在 WKWebView (iOS) 或 Android WebView 中运行您的 web code，并使用本地源 (capacitor://localhost 或 https://localhost在 WebView 中加载提供商的登录页面会出现三个问题：

• Google 返回 disallowed_useragent 并拒绝显示页面。
• 应用程序无法证明页面是真正的提供商，这就是为什么 RFC 8252 命令本机应用程序使用系统浏览器的原因。
• 全页面重定向会从您的捆绑应用程序中导航并丢失状态。

因此以下所有流程都使用本机 SDK (Apple、Google、Facebook) 或系统浏览器会话 (ASWebAuthenticationSession 在 iOS 上，Chrome 自定义标签页在 Android 上) 以自定义方案返回到应用程序。

您的选项一览

原生社交登录 (Apple、Google、Facebook)

一个插件涵盖了三个大型消费者提供商，包括一个通用 OAuth2 引擎：

bun add @capgo/capacitor-social-login
bunx cap sync

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

await SocialLogin.initialize({
  apple: { clientId: 'com.example.app' },
  google: {
    webClientId: 'WEB_CLIENT_ID.apps.googleusercontent.com',
    iOSClientId: 'IOS_CLIENT_ID.apps.googleusercontent.com',
  },
});

const { result } = await SocialLogin.login({ provider: 'google', options: {} });
// send result.idToken to your server

关闭您不使用的提供商在 capacitor.config.ts (plugins.SocialLogin.providers) 因此，他们的 SDK 不会编译到应用程序中。同样，除非您使用 Facebook，否则也会移除 Facebook SDK 的广告 ID 权限。

每个提供商都有原生设置：Apple 需要在 Xcode 中的能力和 Android 的服务 ID，Google 需要 SHA-1 指纹和反向客户端 ID URL 方案。 Apple 和 Google 指南将逐步介绍每个步骤，并解释常见错误。

企业 SSO 与 OAuth 2.0 和 OpenID Connect

对于 Auth0、Okta、Microsoft Entra ID、Keycloak、Cognito、OneLogin 或您自己的 OIDC 服务器，请使用插件的 oauth2 provider. It runs the authorization code flow with PKCE in ASWebAuthenticationSession 流程，使用 PKCE，在 Android 上的自定义标签中运行。 androidUseCustomTabs: true:

await SocialLogin.initialize({
  oauth2: {
    corp: {
      issuerUrl: 'https://sso.example.com/realms/mobile', // OIDC discovery
      clientId: 'mobile-app',
      redirectUrl: 'com.example.app://oauth/corp',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      androidUseCustomTabs: true,
    },
  },
});

const { result } = await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'corp' },
});

当您设置 providerId时，您可以在 iOS 和 Android 上的自定义标签中运行授权流程，使用 PKCE。SocialLogin.refresh您可以在同一映射中注册多个提供者，并选择一个 id_token_hint，这使得多租户 B2B 应用程序可以让每个客户带来他们自己的 IdP。该插件还处理刷新（SocialLoginAuthConnect）、注销（ Auth0, Okta, 进入 ID. 请参见 5 步实现 OAuth2 在 Capacitor 应用中的步骤.

托管后端： Firebase 和 Supabase

如果您的数据已经存储在 Firebase 或 Supabase 中，请使用它们的身份验证，以便安全规则和行级安全性无需额外的粘合剂即可工作。

• Supabase: 使用社交登录插件获取一个 ID 令牌，然后调用 supabase.auth.signInWithIdToken({ provider: 'google', token })。 Supabase 验证它并返回一个会话。 完整设置： Supabase 与 Capacitor 社交登录.
• Firebase: 或者使用 @capgo/capacitor-firebase-authentication, which wraps the native Firebase Auth SDKs, or get an ID token with Social Login and create a Firebase credential from it in the JS SDK. See the Firebase Google 登录文档.

自托管：更好的认证

更好的认证是一个开源的 TypeScript 认证库，它将用户存储在您的自己的数据库中。它在 Capacitor 中工作，只要您信任应用来源并切换到令牌持有者令牌，因为跨站点 cookie 在 WKWebView 中是不可靠的。社交登录通过 native 插件和 ID 令牌传递。步骤如下: 在 Capacitor 应用中使用更好的认证.

密码钥匙

密码钥匙用一个存储在 iCloud Keychain 或 Google 密码管理器中的密钥对替换密码。它们需要您的应用与您的网站域名 (apple-app-site-association 在 iOS 上， assetlinks.json 在 Android 上)关联，并且需要一个 WebAuthn 服务器。

@capgo/capacitor-passkey 让您保留标准 WebAuthn code。配置依赖方在 capacitor.config.ts，在启动时调用 shim一次， navigator.credentials.create() 并且 .get() 是路由到 native 密码钥匙 API 的：

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

await CapacitorPasskey.autoShimWebAuthn();

// existing WebAuthn code keeps working
const assertion = await navigator.credentials.get({
  publicKey: requestOptionsFromServer,
});

类似Better Auth的库，以及托管提供商如Auth0和Okta，可以作为WebAuthn服务器。请参见 passkey插件页面.

使用电子邮件和密码与您的后端

不需要任何插件，它只是 fetch. 服务器上的工作：使用Argon2id或bcrypt进行散列，限制登录尝试次数，发送验证和重置电子邮件，支持帐户删除。使用Universal Links和App Links在应用程序中打开重置和验证链接，使链接落地在手机的正确位置。除非您有理由拥有所有这些功能，否则类似Better Auth的库或托管服务可以为您提供相同的功能并降低风险。

在服务器上验证令牌，始终

客户端检查可以被绕过。无论提供商如何，服务器必须在创建会话之前验证令牌：

import { createRemoteJWKSet, jwtVerify } from 'jose';

type IssuerConfig = {
  jwks: ReturnType<typeof createRemoteJWKSet>;
  issuer: string | string[];
  audience: string[];
};

const issuers: Record<'google' | 'apple', IssuerConfig> = {
  google: {
    jwks: createRemoteJWKSet(new URL('https://www.googleapis.com/oauth2/v3/certs')),
    issuer: ['https://accounts.google.com', 'accounts.google.com'],
    audience: ['WEB_CLIENT_ID.apps.googleusercontent.com', 'IOS_CLIENT_ID.apps.googleusercontent.com'],
  },
  apple: {
    jwks: createRemoteJWKSet(new URL('https://appleid.apple.com/auth/keys')),
    issuer: 'https://appleid.apple.com',
    audience: ['com.example.app', 'com.example.app.signin'],
  },
};

export async function verifyIdToken(provider: 'google' | 'apple', idToken: string) {
  const cfg = issuers[provider];
  const { payload } = await jwtVerify(idToken, cfg.jwks, {
    issuer: cfg.issuer,
    audience: cfg.audience,
  });
  return payload; // use payload.sub as the stable provider user ID
}

提供商的 sub (加上提供商名称)，而不是电子邮件。只有当提供商标记为已验证时才通过电子邮件关联帐户（email_verified: trueMeta的Limited Login令牌不包含该声明。

安全地存储会话

localStorage 并Capacitor偏好项是平面文件。将长期令牌存储在Keychain（iOS）或Keystore加密存储（Android）中。 @capgo/capacitor-native-biometric 简化 setData, getData 和 deleteData 为此提供

bun add @capgo/capacitor-native-biometric
bunx cap sync

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

export const sessionStore = {
  async save(token: string) {
    await NativeBiometric.setData({ key: 'session.token', value: token });
  },
  async load(): Promise<string | null> {
    try {
      const { value } = await NativeBiometric.getData({ key: 'session.token' });
      return value;
    } catch {
      return null;
    }
  },
  async clear() {
    await NativeBiometric.deleteData({ key: 'session.token' }).catch(() => {});
  },
};

安全令牌存储指南 涵盖了更多内容 生物识别：解锁，而不是身份

面部识别和指纹识别仅证明持有手机的人可以解锁它。使用它们来控制对存储会话的访问：

使用

import { AccessControl, NativeBiometric } from '@capgo/capacitor-native-biometric';

// after a real login, offer biometric unlock
await NativeBiometric.setData({
  key: 'session.refresh',
  value: refreshToken,
  accessControl: AccessControl.BIOMETRY_ANY,
});

// next app start
const { value } = await NativeBiometric.getSecureData({
  key: 'session.refresh',
  reason: 'Unlock your account',
});
// exchange `value` with your server for a fresh access token

With accessControl 生物识别认证在__CAPGO_KEEP_0__应用程序中 生物识别身份验证在Capacitor应用中.

简化方法

影响登录的 App Store 和 Play 规则

• Apple 4.8 登录服务:第三方登录作为主要账户系统需要一个等效的隐私保护选项。使用 Apple 登录可以满足它。
• Apple 5.1.1(v):账户创建需要在应用内删除账户，并且使用 Apple 登录令牌应该被撤销。请参阅 账户删除合规性.
• Google Play 账户删除:拥有账户的应用必须在应用内和通过 Play Console 声明的 Web 链接提供删除功能。
• 审阅者访问: 给审阅者提供一个可用的演示账户。如果登录仅限 SSO，请提供一个测试租户用户。
• Xcode 26: App Store Connect has required builds made with Xcode 26 and the iOS 26 SDK since April 2026, so update before you submit a release that adds new auth capabilities.

安全地发布认证变更

认证错误会阻止所有用户，因此您希望快速修复它们。原生更改（权限、URL 方案、意图过滤器）需要一个商店构建。所有在 TypeScript 中的内容，例如提供商配置、范围、错误处理和 UI，都可以通过 Capgo 实时更新 并在出现问题时回滚。 Capgo 构建 生成云端的签名 iOS 和 Android 二进制文件，当您需要一个新的原生发布时。

下一步

选择您的提供商并遵循匹配的指南：

• 使用 Apple 登录
• 使用 Google 登录
• Auth0
• Okta
• Microsoft Entra ID
• 更好的认证
• 社交登录插件文档