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 hostato come Firebase, Supabase o Neon, un provider OIDC come Auth0, Okta o Entra ID, o una libreria self-hosted come Better Auth), usa plugin nativi per tutto ciò che apre una pagina di login del provider, verifica i token su un server e salva la sessione risultante in Keychain o Keystore. Biometria e passkey rendono poi il successivo accesso rapido.

Questa guida associa ogni opzione comune al plugin e al flusso Capacitor giusti, con code per le parti che sono le stesse in ogni app: la chiamata di login, la verifica dei token, lo storage della sessione e lo sblocco biometrico. È aggiornata per Capacitor 8 di ottobre 2026. Ogni provider ha la sua guida passo-passo collegata di seguito.

Il flusso di autenticazione in cui finisce ogni app Capacitor

Indipendentemente dal provider scelto, la struttura è la stessa:

1. Identifica l'utente: social sheet nativa, pagina di login del provider nel browser di sistema, prompt passkey o un form che invia email e password.
2. Ottieni una prova: un ID token, un authorization code o un session token dal tuo auth server.
3. Verifica sul server: controlla firma, issuer, audience e scadenza, poi crea o trova l'utente.
4. Emetti una sessione: il tuo token o quelli del provider, con una strategia di refresh.
5. Salvala in modo sicuro sul dispositivo e allegala alle chiamate API.
6. Sblocca rapidamente la prossima volta con le biometriche e gestisci logout e cancellazione account.

I passaggi 1 e 2 variano in base al provider. I passaggi da 3 a 6 sono a tuo carico in ogni opzione, tranne nel caso di BaaS completamente gestito, dove SDK si occupa della maggior parte del lavoro.

Perché le pagine di login WebView si rompono

Un'app Capacitor esegue il tuo code web in un WKWebView (iOS) o in un WebView Android con un'origine locale (capacitor://localhost oppure https://localhost). Caricare la pagina di login di un provider all'interno di quella WebView comporta tre problemi:

• Google restituisce disallowed_useragent e rifiuta di mostrare la pagina.
• L'app non può verificare che la pagina appartenga al provider reale, motivo per cui la RFC 8252 prescrive l'uso del browser di sistema nelle app native.
• Un redirect a pagina intera naviga fuori dalla tua app bundle e perde lo stato.

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

Le tue opzioni a colpo d'occhio

Social sign-in nativo (Apple, Google, Facebook)

Un plugin copre i tre principali provider consumer più un motore 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

Disattiva i provider che non usi in capacitor.config.ts (plugins.SocialLogin.providers) in modo che i loro SDK non vengano compilati nell'app. Questo rimuove anche il permesso per l'ID pubblicitario di Facebook SDK se non usi Facebook.

Ogni provider ha una configurazione nativa: Apple richiede la capability in Xcode e un Services ID per Android, Google richiede le impronte SHA-1 e uno schema URL con client ID invertito. Il Apple e Google le guide coprono ogni passaggio e gli errori più comuni.

SSO Enterprise con OAuth 2.0 e OpenID Connect

Per Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin o il tuo server OIDC, usa il oauth2 provider. Esegue il flusso di autorizzazione code con PKCE in ASWebAuthenticationSession su iOS e in Custom Tabs su Android quando imposti 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 map e sceglierne uno con providerId, il modo in cui le app B2B multi-tenant permettono a ogni cliente di usare 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 i team che migrano da Auth Connect. Guide ai provider: Auth0, Okta, Entra ID. Per i dettagli sul protocollo, vedi 5 passaggi per implementare OAuth2 nelle app Capacitor.

Backend ospitati: Firebase, Supabase e Neon

Se i tuoi dati sono già su Firebase, Supabase o Neon, usa la loro auth per far funzionare security rules e row-level security senza codice extra.

• Supabase: ottieni un ID token con il plugin Social Login e chiama supabase.auth.signInWithIdToken({ provider: 'google', token }). Supabase lo verifica e restituisce una sessione. Setup completo: Supabase con Capacitor Social Login.
• Neon: Neon Auth è Better Auth gestito, che risiede sul tuo branch Neon. @capgo/capacitor-neon autentica gli utenti nativamente con email e password, OTP via email, oppure Google, GitHub e Vercel OAuth nel browser di sistema. Restituisce un JWT per il Neon Data API, so row-level security applies. Full setup: Documentazione plugin Neon.
• Firebase: either use @capgo/capacitor-firebase-authentication, che incapsula gli SDK nativi di Firebase Auth, oppure ottieni un ID token con Social Login e crea una credenziale Firebase da esso nel SDK JS. Consulta la documentazione di Firebase Google login.

Self-hosted: Better Auth

Better Auth è una libreria di autenticazione open-source in TypeScript che memorizza gli utenti nel tuo database. Funziona in Capacitor una volta che ti fidi delle origini dell'app e passi ai bearer token, perché i cookie cross-site sono inaffidabili in WKWebView. Il social login avviene tramite il plugin nativo e il passaggio di un ID token. Procedura passo-passo: Come usare Better Auth nelle app Capacitor.

Passkeys

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

@capgo/capacitor-passkey ti permette di mantenere lo standard WebAuthn code. Configura il relying party in capacitor.config.ts, chiama lo shim una volta all'avvio e navigator.credentials.create() e .get() vengono instradati alle API nativa delle passkey:

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

await CapacitorPasskey.autoShimWebAuthn();

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

Librerie come Better Auth e provider hostizzati come Auth0 e Okta possono fungere da server WebAuthn. Vedi la pagina del plugin passkey.

Email e password con il tuo backend

Non serve alcun plugin, basta fetch. Il lavoro è lato server: hash con Argon2id o bcrypt, rate-limit sui tentativi di login, invio di email di verifica e reset, e supporto per l'eliminazione dell'account. Apri i link di reset e verifica nell'app con Universal Links e App Links, così il link atterra nel punto giusto sul telefono. A meno che tu non abbia una ragione specifica per gestirli tutti, una libreria come Better Auth o un servizio hosted ti offre le stesse funzionalità con meno rischi.

Verifica sempre i token sul server

I controlli client-side possono essere aggirati. Indipendentemente dal 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
}

Gli utenti chiave sul provider sub (più il nome del provider), non sull'email. Collega gli account per email solo quando il provider la marca come verificata (email_verified: true). I token di Limited Login di Meta non includono quel claim.

Memorizza la sessione in modo sicuro

localStorage e Capacitor Preferences sono file in chiaro. Metti i token a lunga scadenza nel Keychain (iOS) o in archiviazione crittografata Keystore (Android). @capgo/capacitor-native-biometric ha un semplice setData, getData e deleteData metodi per farlo:

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 aggiornali con un refresh token o una sessione server. Il nostro guida allo storage sicuro dei token tratta la rotazione e la revoca in modo più approfondito.

Biometria: sbloccare, non identificare

Face ID e impronta digitale dimostrano solo che la persona che tiene il telefono può sbloccarlo. Usali per limitare 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 operativo rilascia il valore solo dopo un controllo biometrico riuscito, quindi la protezione è applicata da Keychain o Keystore, non da JavaScript. Abbinalo alla scadenza delle sessioni lato server e, per le app ad alto rischio, al rilevamento di root e jailbreak. Ulteriori informazioni in Autenticazione biometrica nelle app Capacitor.

Scegliere un metodo

Regole di App Store e Play Store che influenzano il login

• Apple 4.8 Login Services: il login di terze parti come sistema di account principale richiede un'opzione equivalente orientata alla privacy. Sign in with Apple lo soddisfa.
• Apple 5.1.1(v): la creazione dell'account richiede la cancellazione in-app e la revoca dei token di Sign in with Apple. Vedi conformità alla cancellazione dell'account.
• cancellazione account Google Play: le app con account devono offrire la cancellazione in-app e tramite un link web dichiarato in Play Console.
• Accesso per i revisori: fornite ai revisori un account demo funzionante. Se il login è solo SSO, fornite un utente di test del tenant.
• Xcode 26: App Store Connect richiede build create con Xcode 26 e iOS 26 SDK da aprile 2026, quindi aggiorna prima di inviare un rilascio che aggiunge nuove funzionalità di autenticazione.

Rilascia le modifiche auth in sicurezza

I bug di autenticazione bloccano tutti gli utenti, quindi vuoi risolverli in fretta. Le modifiche native (entitlements, URL schemes, intent filters) richiedono una build per lo store. Tutto ciò che è in TypeScript, come la configurazione del provider, gli scopes, la gestione degli errori e la UI, può essere spinto con Live updates di Capgo e rollback se qualcosa si rompe. Build Capgo genera i binari firmati per iOS e Android nel cloud quando hai bisogno di un nuovo rilascio nativo.

Prossimi passi

Scegli il tuo provider e segui la guida corrispondente:

• Accedi con Apple
• Accedi con Google
• Auth0
• Okta
• Microsoft Entra ID
• Better Auth
• Documentazione del plugin Social Login