Authentifizierung in einer Capacitor-App hinzufügen (2026)

Um Authentifizierung in einer Capacitor-Anwendung hinzuzufügen, wählen Sie eine Identitätsquelle (Ihre eigene Backend, ein gehosteter Dienst wie Firebase oder Supabase, ein OIDC-Anbieter wie Auth0, Okta oder Entra ID oder eine selbst gehostete Bibliothek wie Better Auth), verwenden Sie native Plugins für alles, was eine Anbieter-Login-Seite öffnet, überprüfen Sie Token auf einem Server und speichern Sie das resultierende Sitzung in der Keychain oder Keystore. Biometrie und Passwörter machen das nächste Anmelden dann schnell.

Diese Anleitung stellt alle gängigen Optionen mit dem richtigen Capacitor-Plugin und -Fluss in Beziehung, mit code für die Teile, die in jeder Anwendung gleich sind: der Login-Aufruf, die Token-Überprüfung, die Sitzungs-Speicherung und die Biometrie-Entschlüsselung. Sie ist bis zum Capacitor 8 im Oktober 2026 aktuell. Jeder Anbieter hat seinen eigenen Schritt-für-Schritt-Leitfaden, der unten verlinkt ist.

Der Auth-Fluss, den jede Capacitor-Anwendung erreicht

Unabhängig vom gewählten Anbieter bleibt die Form gleich:

1. Identifiziere den Benutzer: native soziale Blatt, Anbieter-Login-Seite im Systembrowser, Passwortanforderung oder ein Formular, das E-Mail- und Passwort sendet.
2. Get a proof: ein ID-Token, eine Autorisierung code, oder eine Sitzungstoken von Ihrem Auth-Server.
3. Überprüfe auf dem Server: Überprüfe Signatur, Aussteller, Zielgruppe und Ablaufdatum, dann erstelle oder finde den Benutzer.
4. Erstelle eine Sitzung: Ihren eigenen Token oder die Anbieter-Tokens, mit einer Aktualisierungsstrategie.
5. Speichere es sicher auf dem Gerät und füge es zu API-Anfragen hinzu.
6. Erleichtere das schnelle Einloggen Zukünftig mit Biometrie, und Abmeldung und Konto-Löschung verwalten.

Schritte 1 und 2 ändern sich mit dem Anbieter. Schritte 3 bis 6 sind Ihre Verantwortung in jeder Option außer bei vollständig gehosteter BaaS, wo der SDK das meiste macht.

Wieso WebView-Login-Seiten kaputtgehen.

Eine Capacitor-App läuft Ihr Web code in einem WKWebView (iOS) oder Android WebView mit einem lokalen Ursprung (capacitor://localhost oder https://localhost. Laden Sie die Anmeldeseite eines Providers innerhalb des WebViews, um drei Probleme zu verursachen:

• Google gibt zurück disallowed_useragent weigert, die Seite anzuzeigen.
• Die App kann nicht beweisen, dass die Seite der echte Anbieter ist, weshalb RFC 8252 native Apps auffordert, den Systembrowser zu verwenden.
• Eine vollständige Seite-Überleitung leitet Sie von Ihrer gebündelten App weg und verliert den Zustand.

So jede Fluss unten verwendet entweder eine native SDK (Apple, Google, Facebook) oder eine Systembrowser-Sitzung ("ASWebAuthenticationSession Jeder Flow unten verwendet entweder einen nativen __CAPGO_KEEP_0__ (Apple, Google, Facebook) oder einen Systembrowser-Session (

Ihre Optionen im Überblick

Nativeer sozialer Anmeldeprozess (Apple, Google, Facebook)

Eine Plugin-Option deckt die drei großen Verbraucheranbieter und einen generischen OAuth2-Motor ab:

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

Turn off providers you do not use in capacitor.config.ts (plugins.SocialLogin.providers) so dass ihre SDKs nicht in die App kompiliert werden. Das entfernt auch die Facebook SDK-Anzeigen-ID-Berechtigung, wenn Sie Facebook nicht verwenden.

Jeder Anbieter hat eine native Einrichtung: Apple benötigt die Fähigkeit in Xcode und eine Services-ID für Android, Google benötigt SHA-1-Fingerabdrücke und eine umgekehrte Client-ID-URL-Scheme. Der Apple und Google Richtlinien gehen jeden Schritt durch und die häufigsten Fehler.

Unternehmens-SSO mit OAuth 2.0 und OpenID Connect

Für Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin oder Ihren eigenen OIDC-Server verwenden Sie den Plugin-Bibliothek. oauth2 Es führt die Autorisierung code-Fluss mit PKCE in ASWebAuthenticationSession auf iOS und in Custom Tabs auf Android, wenn Sie 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' },
});

Sie können mehrere Anbieter in derselben Map registrieren und einen auswählen mit providerId, wie Multi-Tenant-B2B-Anwendungen es Kunden ermöglichen, ihre eigenen IdPs mitzubringen. Der Plugin verarbeitet auch die Aktualisierung von Access-Tokens ("SocialLogin.refresh), Abmeldung mit id_token_hintund ein kompatibler Wrapper für Ionic Auth Connect ("SocialLoginAuthConnect) für Teams, die von Auth Connect migrieren. Anbieter-Überblicks: Auth0, Okta, Eintritts-ID. Für den Hintergrund des Protokolls siehe 5 Schritte zum Implementieren von OAuth2 in Capacitor-Anwendungen.

Hosted Backends: Firebase und Supabase

Wenn Ihre Daten bereits in Firebase oder Supabase leben, verwenden Sie deren Authentifizierung, damit Sicherheitsregeln und Zeilen-Sicherheitsfunktionen ohne zusätzliche Verbindungen funktionieren.

• Supabase: erhalten Sie eine ID-Token mit dem Social-Login-Plugin und rufen Sie supabase.auth.signInWithIdToken({ provider: 'google', token }). Supabase überprüft es und gibt eine Sitzung zurück. Vollständige Einrichtung: Supabase mit Capacitor Social Login.
• Firebase: entweder verwenden Sie @capgo/capacitor-firebase-authentication, die das native Firebase Auth SDKs umschließt, oder erhalten Sie ein ID-Token mit Social Login und erstellen Sie ein Firebase-Zertifikat aus ihm in der JS SDK. Siehe das Firebase Google login Dokumente.

Selbst gehostet: Bessere Authentifizierung

Bessere Authentifizierung ist eine offene Quellcode-Authentifizierungsbibliothek in TypeScript, die Benutzer in Ihrem eigenen Datenbank enthält. Sie funktioniert in Capacitor sobald Sie die App-Origins vertrauen und auf Bearer-Tokens umschalten, weil sichere Cross-Site-Cookies in WKWebView unzuverlässig sind. Die soziale Anmeldung erfolgt über den nativen Plugin und einen ID-Token-Übertrag. Schritt-für-Schritt: Wie man Better Auth in Capacitor-Apps verwendet.

Passkeys

Passwörter ersetzen Passwörter durch ein Schlüsselpaar, das in iCloud Keychain oder Google Password Manager gespeichert ist. Sie benötigen, dass Ihre App mit Ihrer Website-Domain (apple-app-site-association auf iOS, assetlinks.json auf Android) und einem WebAuthn-Server.

@capgo/capacitor-passkey erlaubt Ihnen, standardmäßige WebAuthn code. Konfigurieren Sie den Relying-Party in capacitor.config.tsrufen Sie die Shim einmal bei der Startzeit auf und navigator.credentials.create() und .get() sind an die native Passkey-APIs geroutet:

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

await CapacitorPasskey.autoShimWebAuthn();

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

Bibliotheken wie Better Auth und gehostete Anbieter wie Auth0 und Okta können als WebAuthn-Server fungieren. Siehe die Seite zum passkey-Plugin .

E-Mail- und Passwort mit Ihrem eigenen Backend

Kein Plugin ist erforderlich, es ist nur fetch . Die Arbeit liegt auf dem Server: Hash mit Argon2id oder bcrypt, Loginversuche rate-limiten, Bestätigungs- und Zurücksetzungs-E-Mails senden und Konten löschen. Öffnen Sie die Zurücksetzungs- und Bestätigungslinks im App mit Universal Links und App Links, so dass der Link an der richtigen Stelle auf einem Telefon landet. Es sei denn, Sie haben einen Grund, um alle das selbst zu besitzen, bietet eine Bibliothek wie Better Auth oder ein gehosteter Dienst Ihnen die gleichen Funktionen mit weniger Risiko.

Verifizieren Sie die Token auf dem Server, immer

Kundenseitige Überprüfungen können umgangen werden. Unabhängig vom Provider muss der Server den Token vor der Erstellung einer Sitzung überprüfen.

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
}

Schlüsselbenutzer auf dem Anbieters sub (plus Anbietername), nicht auf E-Mail. Verbinden Sie Konten nur über E-Mail, wenn der Anbieter es als verifiziert markiert ( email_verified: true Die Limited Login-Tokens von Meta enthalten keinen solchen Anspruch.

Speichern Sie die Sitzung sicher

localStorage und Capacitor Einstellungen sind plain-Dateien. Legen Sie lange lebende Token im Keychain (iOS) oder in Keystore-verschlüsselter Speicherung (Android) ab. @capgo/capacitor-native-biometric hat einfache setData, getData und deleteData Methode für das:

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(() => {});
  },
};

Halten Sie Zugriffstoken kurzlebig und aktualisieren Sie sie mit einem Refresh-Token oder einer Server-Sitzung. Unsere Sichere Token-Speicherung-Anleitung erforscht Rotation und Rückruf in mehr Details.

Biometrie: entsperren, nicht identifizieren

Gesichtserkennung und Fingerabdruck beweisen nur, dass die Person, die das Telefon hält, es entsperren kann. Verwenden Sie sie, um den Zugriff auf eine gespeicherte Sitzung zu sperren:

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

Mit accessControl gesetzt, gibt der Betriebssystem den Wert nur nach einem erfolgreichen biometrischen Check frei, so dass die Sicherheit durch den Keychain oder Keystore und nicht durch JavaScript durchgeführt wird. Paaren Sie es mit der Server-Sitzungsauslaufen und, für Apps mit hohem Risiko, mit der Erkennung von Root- und Jailbreak. Biometrische Authentifizierung in Capacitor-Apps.

Biometrische Authentifizierung in __CAPGO_KEEP_0__-Apps

App Store und Play Regeln, die sich auf das Anmelden auswirken

• Apple 4.8 Login-Dienste: Drittanbieter-Login als Hauptkonto-System erfordert eine äquivalente, auf Privatsphäre ausgerichtete Option. Mit Apple anmelden erfüllt es.
• Apple 5.1.1(v)Kontoerstellung erfordert die Löschung des in-app-Kontos und die Rücknahme von Sign in with Apple-Tokens. Weitere Informationen finden Sie im. Konto-Löschung-Konformität.
• Google Play-Konto-Löschung: Apps mit Konten müssen die Löschung im App und über einen Web-Link, der in der Play Console deklariert ist, anbieten.
• Zugriffsberechtigung für Rezensionen: give reviewers a working demo account. If login is SSO only, provide a test tenant user.
• Xcode 26: App Store Connect hat seit April 2026 Builds mit Xcode 26 und iOS 26 SDK erforderlich, daher aktualisieren Sie sich vor der Einreichung einer Veröffentlichung, die neue Auth-Funktionen enthält.

Auth-Änderungen sicher verschicken

Auth bugs block every user, so you want to fix them fast. Native changes (entitlements, URL schemes, intent filters) need a store build. Everything in TypeScript, like provider config, scopes, error handling and UI, can be pushed with Capgo Live-Updates wird zurückgerollt, wenn etwas kaputt geht. Capgo Build erzeugt die signierten iOS- und Android-Binärdateien im Cloud-Service, wenn Sie eine neue native Version benötigen.

Nächste Schritte

Wählen Sie Ihren Anbieter und folgen Sie der entsprechenden Anleitung.

• Mit Apple anmelden
• Mit Google anmelden
• Auth0
• Okta
• Microsoft Entra ID
• Better Auth
• Dokumentation zum Social Login-Plugin