Wie man Authentifizierung in einer Capacitor-App hinzufügt (2026)

Um Authentifizierung in einer Capacitor-App hinzuzufügen, wählen Sie eine Identitätsquelle (eigenes Backend, gehosteter Dienst wie Firebase oder Supabase, 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 Anbieteranmeldeseite öffnet, überprüfen Sie Token auf einem Server und speichern Sie das resultierende Sitzung in der Keychain oder Keystore. Biometrische Daten und Passwörter machen das nächste Anmelden schnell.

Dieses Leitfaden zeigt alle gängigen Optionen auf die richtige Capacitor-Erweiterung und -Fluss, mit code für die Teile, die in jedem App gleich sind: der Anmeldeaufruf, die Tokenüberprüfung, die Sitzungsablage und die biometrische Freischaltung. Es ist bis Capacitor 8 im Oktober 2026 aktuell. Jeder Anbieter hat seinen eigenen Schritt-für-Schritt-Leitfaden, der unten verlinkt ist.

Die Authentifizierungsablauf, den jede Capacitor-App erreicht

Unabhängig vom gewählten Anbieter ist die Form immer gleich:

1. Identifizieren Der Benutzer: native soziale Blatt, Anbieter-Login-Seite im Systembrowser, Passwort-Eingabeaufforderung oder ein Formular, das E-Mail-Adresse und Passwort sendet.
2. Ein Beweis: ein ID-Token, eine Autorisierung code oder ein Sitzungs-Token von Ihrem Auth-Server.
3. Verifizieren auf dem ServerÜberprüfe die Signatur, den Aussteller, das Ziel und die Gültigkeit, dann erstelle oder finde den Benutzer.
4. Ausstellen einer Sitzung: Ihr eigenes Token oder die Tokens des Providers, mit einer Refresh-Strategie.
5. Sicheren Speicherplatz : auf dem Gerät und anhängen Sie es an API-Anrufe.
6. Rasch freischalten : nächstes Mal mit Biometrien und Logout und Account-Löschung verwalten.

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

Warum 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://localhostBei der Aufladung der Anmeldeseite eines Providers innerhalb des WebViews entstehen drei Probleme:

• Google gibt zurück disallowed_useragent und zeigt die Seite nicht an.
• Die App kann nicht beweisen, dass die Seite der echte Provider ist, weshalb RFC 8252 native Apps dazu auffordert, den Systembrowser zu verwenden.
• Ein vollständiger Seitenwechsel navigiert vom gebündelten App aus und verliert den Zustand.

Jeder der folgenden Flüsse verwendet daher entweder einen nativen SDK (Apple, Google, Facebook) oder einen Systembrowser-Sitzung (ASWebAuthenticationSession auf iOS, Chrome Custom Tabs auf Android), der durch einen benutzerdefinierten Schematismus zurückkehrt.

Optionen im Überblick

Nativeer sozialer Anmeldeprozess (Apple, Google, Facebook)

Ein Plugin 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 werden ihre SDKs nicht in die App kompiliert. 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. Die Apple und Google Anleitungen gehen durch jeden Schritt 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 das Plugin’s oauth2 Anbieter. Es führt den Autorisierungscode-Fluss mit PKCE durch. ASWebAuthenticationSession On iOS und in Custom Tabs auf Android, wenn Sie dies setzen 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 providerId, wie Multi-Tenant-B2B-Anwendungen es Kunden ermöglichen, ihre eigenen IdPs mitzubringen. Der Plugin verarbeitet auch die Aktualisierung ("SocialLogin.refresh), Abmeldung mit id_token_hintund eine kompatible Wrapper für Ionic Auth Connect.SocialLoginAuthConnect) für Teams, die von Auth Connect migrieren. Anbieter-Überblick: Auth0, Okta, Eintritts-ID. Für den Hintergrund des Protokolls siehe 5 Schritte, um OAuth2 in Capacitor-Apps zu implementieren.

Hosten von Backends: Firebase und Supabase

If Ihre Daten bereits in Firebase oder Supabase leben, verwenden Sie deren Auth, damit Sicherheitsregeln und row-level-Sicherheit ohne zusätzliche Verbindung funktionieren.

• Supabase: erhalten Sie einen 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: verwenden Sie entweder @capgo/capacitor-firebase-authentication, das die native Firebase Auth SDKs einhüllt, oder erhalten Sie einen ID-Token mit Social Login und erstellen Sie ein Firebase-Zertifikat aus ihm in der JS SDK. Siehe die Firebase Google login Dokumentation.

Selbst gehostet: Bessere Auth

Bessere Auth ist eine Open-Source-TypeScript-Auth-Bibliothek, die Benutzer in Ihrem eigenen Datenbank speichert. Sie funktioniert in Capacitor einmal Sie die App-Origins vertrauen und auf Bearer-Tokens umschalten, weil cross-site-Cookies in WKWebView unzuverlässig sind. Social-Login geht über den native Plugin und einen ID-Token-Handover. Schritt-für-Schritt: Wie Sie Bessere Auth in Capacitor Apps verwenden.

Passkeys

Passkeys ersetzen Passwörter durch eine 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 Lassen Sie Ihnen die Standard-WebAuthn code. Konfigurieren Sie die anvertrauende Partei in capacitor.config.tsKonfigurieren Sie den Relying-Party in navigator.credentials.create() and .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 Passkey-Plugin-Seite.

E-Mail und Passwort mit Ihrem eigenen Backend

E-Mail und Passwort mit Ihrem eigenen Backend fetch. The work is on the server: hash with Argon2id or bcrypt, rate-limit login attempts, send verification and reset emails, and support account deletion. Open reset and verification links in the app with Universal Links and App Links, so the link lands in the right place on a phone. Unless you have a reason to own all of that, a library like Better Auth or a hosted service gives you the same features with less risk.

Überprüfe 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
}

Jeder Benutzer auf dem Anbieter’s sub (plus Anbietername), nicht auf E-Mail. Verbinde Konten nur über E-Mail, wenn der Anbieter es als verifiziert markiert (email_verified: trueMeta’s Limited Login-Tokens enthalten keinen solchen Anspruch.

Speichern Sie die Sitzung sicher

localStorage und Capacitor Einstellungen sind einfache Dateien. Legen Sie lange lebende Token im Keychain (iOS) oder in einer Keystore-verschlüsselten Speicherung (Android) ab. @capgo/capacitor-native-biometric und setData, getData and deleteData Möglichkeiten dafür:

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 erneuern Sie sie mit einem Refresh-Token oder einer Server-Sitzung. Unsere Leitfaden für sichere Token-Speicherung beschreibt die Rotation und die Rückrufung im Detail.

Biometrie: einlösen, nicht Identität

Fingerabdruck und Face ID beweisen nur, dass die Person, die das Telefon hält, es entsperren kann. Verwenden Sie sie, um 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 durchgesetzt wird. Paaren Sie es mit der serverseitigen Sitzungsauslaufen und, für Apps mit hohem Risiko, mit der Erkennung von Wurzeln und Jailbreaks. Mehr in Biometrische Authentifizierung in Capacitor-Apps.

Die Wahl der Methode

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

• Apple 4.8 Login DiensteEin dritter Anbieter-Login als Hauptkonto-System erfordert eine gleichwertige, auf Privatsphäre ausgerichtete Option. Mit Apple anmelden erfüllt diese Anforderung.
• Apple 5.1.1(v)Kontoerstellung erfordert die Löschung des in-app-Kontos und die Rücknahme von Sign in with Apple-Tokens. Siehe Konto-Löschungskonformität.
• Google Play-Konto-Löschung: Apps mit Konten müssen die Löschung im App und über einen Web-Link, der in Play Console deklariert ist, anbieten.
• Zugriffsrechte des Rezensenten: Geben Sie Rezensenten einen funktionierenden Demo-Konto. Wenn das Login nur SSO ist, stellen Sie einen Test-Tenant-Benutzer bereit.
• Xcode 26: App Store Connect hat seit April 2026 Builds, die mit Xcode 26 und iOS 26 SDK erstellt wurden, vorgeschrieben, also aktualisieren Sie, bevor Sie eine Veröffentlichung einreichen, die neue Auth-Fähigkeiten hinzufügt.

Schiffe auth Änderungen sicher

Auth Fehler blockieren jeden Benutzer, also möchten Sie sie schnell beheben. Native Änderungen (Zugriffsrechte, URL Schemes, Intent Filter) benötigen eine App-Store-Build. Alles in TypeScript, wie Provider-Konfiguration, Scope, Fehlerbehandlung und UI, kann mit Capgo Live-Updates und zurückgerollt werden, wenn etwas kaputt geht. Capgo Build erzeugt die signierten iOS- und Android-Binärdateien im Cloud, wenn Sie eine neue native Release 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
• Bessere Auth
• Dokumentation zum Social Login-Plugin