Come aggiungere l'autenticazione a un'app Capacitor (2026)

Per aggiungere l'autenticazione a un'app Capacitor, scegli una fonte di identità (il tuo backend, un servizio ospitato come Firebase o Supabase, un provider OIDC come Auth0, Okta o Entra ID, o una libreria self-hosted come Better Auth), utilizza plugin nativi per qualsiasi cosa apra una pagina di login del provider, verifica i token sul server e memorizza la sessione risultante nel Keychain o Keystore. Le biometrie e i passkeys rendono il prossimo accesso veloce.

Questa guida mappa ogni opzione comune al plugin e al flusso Capacitor giusto, con code per le parti che sono le stesse in ogni app: la chiamata di login, la verifica dei token, la memorizzazione della sessione e l'accesso con biometria. È aggiornata per Capacitor 8 in ottobre 2026. Ogni provider ha la sua guida passo dopo passo collegata di seguito.

Il flusso di autenticazione che ogni app Capacitor finisce con

Indipendentemente dal provider che scegli, la forma è la stessa:

1. Identifica l'utente: schermo sociale nativo, pagina di accesso del provider nel browser del sistema, richiesta di passkey, o un modulo che invia email e password.
2. Otteni una prova: un token di identità, un'autorizzazione code o un token di sessione dal tuo server di autenticazione.
3. Verifica sul server: controlla firma, emittente, destinatario e scadenza, quindi crea o trova l'utente.
4. Emiti una sessione: il tuo token o i token del provider, con una strategia di aggiornamento.
5. Memorizzalo in modo sicuro sul dispositivo e attaccalo alle chiamate di API.
6. Sblocca velocemente la prossima volta con biometria, e gestisci il logout e la cancellazione dell'account.

I passaggi 1 e 2 cambiano con il provider. I passaggi 3 a 6 sono la tua responsabilità in ogni opzione, except per il BaaS completamente ospitato, dove il SDK si occupa di tutto.

Perché le pagine di accesso di WebView si rompono

Un'app Capacitor esegue il tuo web code in un WKWebView (iOS) o in un Android WebView con un origin locale (capacitor://localhost o https://localhostCaricamento della pagina di accesso del provider all'interno di quel WebView causa tre problemi.

• Google restituisce disallowed_useragent e rifiuta di mostrare la pagina.
• L'app non può provare che la pagina sia il provider reale, il che è il motivo per cui RFC 8252 consiglia agli app nativi di utilizzare il browser del sistema.
• Un redirect a pagina intera naviga via dalla tua app bundle e perde lo stato.

Quindi ogni flusso sotto utilizza o un SDK nativo (Apple, Google, Facebook) o una sessione del browser del sistema (ASWebAuthenticationSession su iOS, Chrome Custom Tabs su Android) che torna all'app tramite un custom scheme.

Le vostre opzioni in un colpo d'occhio

Accesso nativo con social (Apple, Google, Facebook)

Un plugin copre i tre grandi provider di consumo più un motore di autenticazione OAuth2 generico:

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

Disabilitare i provider che non si utilizzano in capacitor.config.ts (plugins.SocialLogin.providers) quindi i loro SDK non vengono compilati nell'app. Ciò elimina anche la richiesta di autorizzazione all'ID pubblicitario di Facebook di Facebook SDK se non si utilizza Facebook.

Ogni provider ha una configurazione nativa: Apple richiede la capacità in Xcode e un ID Servizi per Android, Google richiede impronte SHA-1 e un URL di ID client inverso. Apple e Google I guide passano attraverso ogni passo e gli errori comuni.

SSO aziendale con OAuth 2.0 e OpenID Connect

Per Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin o il proprio server OIDC, utilizzare il plugin's oauth2 provider. Esegue il flusso di autorizzazione code con PKCE in ASWebAuthenticationSession su iOS e in Custom Tabs su Android quando si impostano 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' },
});

Puoi registrare più provider nella stessa mappa e scegliere uno con providerId, che è come gli app B2B multi-tenant consentono a ogni cliente di portare il proprio IdP. Il plugin gestisce anche il refresh (SocialLogin.refresh), logout con id_token_hint, e un wrapper compatibile con Ionic Auth Connect (SocialLoginAuthConnect) per team che migrano da Auth Connect. Guida al provider: Auth0, Okta, Accedi con ID. Per la background del protocollo, vedi 5 passaggi per implementare OAuth2 nei Capacitor app.

Servizi backend ospitati: Firebase e Supabase

Se i tuoi dati già vivono in Firebase o Supabase, utilizza le loro autenticazioni per che le regole di sicurezza e la sicurezza a livello di riga funzionino senza ulteriore collegamento.

• Supabase: ottieni un token ID con il plugin di accesso sociale e chiama supabase.auth.signInWithIdToken({ provider: 'google', token }). Supabase verifica e restituisce una sessione. Configurazione completa: Supabase con Capacitor Social Login.
• Firebase: o utilizza @capgo/capacitor-firebase-authentication, che avvolge gli SDK di autenticazione nativi di Firebase, o ottieni un token ID con Social Login e crea un credenziale Firebase da esso nel JS SDK. Vedi il Fattori Google login docs.

Autenticazione self-hosted: Migliore Autenticazione

Migliore Autenticazione è una libreria di autenticazione open-source TypeScript che memorizza gli utenti nel proprio database. Funziona in Capacitor una volta che si fidano delle origini dell'app e si passa ai token di accesso, perché i cookie di sito cross-site sono poco affidabili in WKWebView. L'accesso sociale passa attraverso il plugin nativo e un'invio di token ID. Passaggi per seguire: Come utilizzare Migliore Autenticazione in Capacitor app.

Passkey

I passkey sostituiscono le password con una coppia di chiavi memorizzata in iCloud Keychain o Google Password Manager. Hanno bisogno che la tua app sia associata al tuo dominio del sito web (apple-app-site-association su iOS, assetlinks.json su Android) e un server WebAuthn.

@capgo/capacitor-passkey ti consente di mantenere lo standard WebAuthn code. Configura il partner di fiducia in capacitor.config.tschiamare la shim una volta all'avvio navigator.credentials.create() e .get() sono indirizzati alle API passkey native:

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

await CapacitorPasskey.autoShimWebAuthn();

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

Le librerie come Better Auth, e i provider ospitati come Auth0 e Okta, possono agire come server WebAuthn. Vedi la pagina del plugin passkey.

Email e password con il tuo backend

Nessun plugin è necessario, è solo fetch. Il lavoro si svolge sul server: hash con Argon2id o bcrypt, limitazione del numero di tentativi di accesso, invio di email di verifica e di reset, e supporto alla cancellazione dell'account. Apri i collegamenti di reset e di verifica nell'applicazione con Universal Links e App Links, in modo che il collegamento si apra nel posto giusto su un telefono. A meno che tu non abbia una ragione per gestire tutto da solo, una libreria come Better Auth o un servizio ospitato ti offre le stesse funzionalità con meno rischi.

Verifica i token sul server, sempre

I controlli client-side possono essere bypassati. Qualunque sia il provider, il server deve verificare il token prima di creare una sessione:

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
}

Utenti chiave del fornitore sub Non collegare gli account tramite email se non il provider lo segnala come verificato ("email_verified: true. I token di accesso limitati di Meta non includono tale claim.

Memorizza la sessione in modo sicuro

localStorage e Capacitor Preferenze sono file di testo. Inserisci token a lunga durata nella Keychain (iOS) o nel storage crittografato Keystore (Android). @capgo/capacitor-native-biometric ha semplice setData, getData e deleteData metodi per questo:

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

Mantieni i token di accesso a breve durata e rinnaziali con un token di rinnovo o una sessione server. guida di archiviazione sicura dei token copre la rotazione e la revoca in modo più dettagliato.

Biometria: sblocca, non identità

La faccia ID e il dito unico dimostrano solo che la persona che tiene il telefono può sbloccarlo. Utilizzarli per bloccare l'accesso a una sessione memorizzata:

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

Con accessControl impostato, il sistema rilascia il valore solo dopo un controllo biometrico riuscito, quindi la protezione è garantita dal Keychain o Keystore, non dal JavaScript. Associarlo con la scadenza della sessione server e, per le app ad alto rischio, la detezione di root e jailbreak. Di più in l'autenticazione biometrica nei Capacitor app.

Scegliere un metodo

Regole di App Store e Play che influenzano l'accesso

• Servizi di accesso Apple 4.8: l'accesso con terze parti come sistema di conto principale richiede un'opzione equivalente focalizzata sulla privacy. L'accesso con Apple lo soddisfa.
• Apple 5.1.1(v)La creazione dell'account richiede la cancellazione dell'account all'interno dell'app e i token Sign in with Apple dovrebbero essere revocati. Vedi compliance della cancellazione del conto.
• cancellazione del conto di Google Play: le app con conti devono offrire la cancellazione all'interno dell'app e tramite un link web dichiarato nel Console di Play.
• Accesso del revisore: fornire ai revisori un account di demo funzionante. Se l'accesso è solo SSO, fornire un utente di testante.
• Xcode 26: App Store Connect richiede costruzioni fatte con Xcode 26 e l'iOS 26 SDK dal mese di aprile 2026, quindi aggiorna prima di inviare una versione che aggiunge nuove capacità di autenticazione.

Scegliere l'aggiornamento delle autenticazioni con sicurezza

: i bug delle autenticazioni bloccano ogni utente, quindi desideri risolverli velocemente. Le modifiche native (diritti, schemi URL, filtri di intento) richiedono una costruzione di store. Tutto in TypeScript, come la configurazione del provider, gli ambiti, l'elaborazione degli errori e l'interfaccia utente, può essere spedito con aggiornamenti live Capgo e viene annullato se qualcosa non funziona. Costrui Capgo genera i binari iOS e Android firmati in cloud quando hai bisogno di una nuova versione nativa.

Next steps

Scegli il tuo provider e segui la guida corrispondente.

• Accedi con Apple
• Accedi con Google
• Auth0
• Okta
• Azure Active Directory
• Better Auth
• Dal documento plugin di accesso sociale