Cara Menambahkan Autentikasi ke Aplikasi Capacitor (2026)

Untuk menambahkan autentikasi ke aplikasi Capacitor, pilih sumber identitas (backend sendiri, layanan terkelola seperti Firebase atau Supabase, penyedia OIDC seperti Auth0, Okta atau Entra ID, atau library self-hosted seperti Better Auth), gunakan plugin native untuk membuka halaman login provider, verifikasi token di server, dan simpan session yang dihasilkan di Keychain atau Keystore. Biometrik dan passkeys akan mempercepat proses sign-in berikutnya.

Panduan ini memetakan setiap opsi umum ke plugin dan alur Capacitor yang tepat, dengan code untuk bagian yang sama di setiap aplikasi: pemanggilan login, verifikasi token, penyimpanan session, dan unlock biometrik. Informasi ini mutakhir untuk Capacitor 8 pada Oktober 2026. Setiap provider memiliki panduan langkah demi langkahnya sendiri yang ditautkan di bawah.

Alur auth yang akhirnya dipakai setiap aplikasi Capacitor

Apa pun provider yang Anda pilih, polanya tetap sama:

1. Identifikasi pengguna: native social sheet, halaman login provider di browser sistem, prompt passkey, atau form yang mengirim email dan password.
2. Dapatkan bukti: ID token, authorization code, atau session token dari auth server Anda.
3. Verifikasi di server: cek signature, issuer, audience, dan expiry, lalu buat atau cari user.
4. Terbitkan session: token Anda sendiri atau token dari provider, lengkap dengan strategi refresh.
5. Simpan dengan aman di perangkat dan lampirkan ke panggilan API.
6. Buka akses dengan cepat lain kali dengan biometrik, serta kelola logout dan penghapusan akun.

Langkah 1 dan 2 berbeda tergantung provider. Langkah 3 sampai 6 adalah tanggung jawab Anda di setiap opsi kecuali BaaS yang fully hosted, di mana SDK menangani sebagian besarnya.

Mengapa halaman login WebView bermasalah

Aplikasi Capacitor menjalankan web code Anda di dalam WKWebView (iOS) atau Android WebView dengan local origin (capacitor://localhost atau https://localhost). Memuat halaman login provider di dalam WebView tersebut menyebabkan tiga masalah:

• Google mengembalikan disallowed_useragent dan menolak untuk menampilkan halaman tersebut.
• Aplikasi tidak dapat membuktikan bahwa halaman tersebut adalah provider asli, itulah sebabnya RFC 8252 menyarankan native app untuk menggunakan system browser.
• Redirect halaman penuh akan mengalihkan pengguna keluar dari bundle app Anda dan menyebabkan kehilangan state.

Jadi, setiap flow di bawah ini menggunakan native SDK (Apple, Google, Facebook) atau sesi system browser (ASWebAuthenticationSession di iOS, Chrome Custom Tabs di Android) yang kembali ke aplikasi melalui custom scheme.

Ringkasan opsi Anda

Login sosial native (Apple, Google, Facebook)

Satu plugin mencakup tiga provider besar plus engine OAuth2 generik:

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

Matikan provider yang tidak digunakan di capacitor.config.ts (plugins.SocialLogin.providers) agar SDK mereka tidak ikut di-compile ke dalam app. Ini juga menghapus izin advertising ID Facebook SDK jika Anda tidak menggunakan Facebook.

Each provider has native setup: Apple needs the capability in Xcode and a Services ID for Android, Google needs SHA-1 fingerprints and a reversed client ID URL scheme. The Apple dan Google panduan ini membahas setiap langkah dan error yang umum terjadi.

Enterprise SSO dengan OAuth 2.0 dan OpenID Connect

Untuk Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin atau server OIDC sendiri, gunakan oauth2 provider plugin ini. Ini menjalankan flow otorisasi code dengan PKCE di ASWebAuthenticationSession pada iOS dan Custom Tabs di Android saat Anda mengatur 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' },
});

Anda bisa mendaftarkan beberapa provider dalam map yang sama dan memilih salah satu dengan providerId, cara aplikasi B2B multi-tenant mengizinkan setiap customer menggunakan IdP mereka sendiri. Plugin ini juga menangani refresh (SocialLogin.refresh), logout dengan id_token_hint, dan wrapper yang kompatibel dengan Ionic Auth Connect (SocialLoginAuthConnect) untuk tim yang bermigrasi dari Auth Connect. Panduan provider: Auth0, Okta, Entra ID. Untuk latar belakang protokolnya, lihat 5 langkah implementasi OAuth2 di aplikasi Capacitor.

Backend terkelola: Firebase dan Supabase

Jika data Anda sudah ada di Firebase atau Supabase, gunakan auth mereka agar security rules dan row-level security berjalan tanpa konfigurasi tambahan.

• Supabase: dapatkan ID token dengan plugin Social Login dan panggil supabase.auth.signInWithIdToken({ provider: 'google', token }). Supabase akan memverifikasinya dan mengembalikan session. Setup lengkap: Supabase dengan Capacitor Social Login.
• Firebase: Anda bisa menggunakan @capgo/capacitor-firebase-authentication, yang membungkus SDK Firebase Auth native, atau dapatkan ID token dengan Social Login lalu buat kredensial Firebase dari token itu di JS SDK. Lihat Dokumentasi login Google Firebase.

Self-hosted: Better Auth

Better Auth adalah library auth TypeScript open-source yang menyimpan user di database Anda sendiri. Ini berfungsi di Capacitor setelah Anda mempercayai origin aplikasi dan beralih ke bearer token, karena cross-site cookies tidak andal di WKWebView. Social login berjalan melalui plugin native dan handoff ID token. Langkah-langkahnya: Cara menggunakan Better Auth di aplikasi Capacitor.

Passkeys

Passkeys menggantikan password dengan pasangan kunci yang disimpan di iCloud Keychain atau Google Password Manager. Passkeys memerlukan aplikasi Anda dikaitkan dengan domain website Anda (apple-app-site-association di iOS, assetlinks.json di Android) dan server WebAuthn.

@capgo/capacitor-passkey memungkinkan Anda tetap memakai WebAuthn code standar. Konfigurasikan relying party di capacitor.config.ts, panggil shim sekali saat startup, dan navigator.credentials.create() dan .get() akan diarahkan ke 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,
});

Library seperti Better Auth, serta provider terkelola seperti Auth0 dan Okta, dapat bertindak sebagai server WebAuthn. Lihat halaman plugin passkey.

Email dan password dengan backend sendiri

Tidak butuh plugin, ini hanya fetch. Pekerjaannya ada di sisi server: hash dengan Argon2id atau bcrypt, rate-limit percobaan login, kirim email verifikasi dan reset, serta dukung penghapusan akun. Buka link reset dan verifikasi di dalam app menggunakan Universal Links dan App Links, agar link mendarat di tempat yang tepat pada ponsel. Kecuali Anda punya alasan untuk mengelola semua itu sendiri, library seperti Better Auth atau layanan terkelola memberikan fitur yang sama dengan risiko lebih rendah.

Selalu verifikasi token di sisi server

Pengecekan di sisi client bisa dilewati. Apa pun providernya, server harus memverifikasi token sebelum membuat session:

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
}

Pengguna utama pada penyedia sub (ditambah nama provider), bukan pada email. Hanya hubungkan akun via email jika provider menandainya sebagai terverifikasi ("email_verified: true"). Token Limited Login milik Meta tidak menyertakan claim tersebut.

Simpan session dengan aman

localStorage dan Capacitor Preferences adalah file biasa. Simpan token berumur panjang di Keychain (iOS) atau penyimpanan terenkripsi Keystore (Android). @capgo/capacitor-native-biometric memiliki setData, getData dan deleteData metode sederhana untuk itu:

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

Jaga agar access token berumur pendek dan perbarui dengan refresh token atau sesi server. Panduan penyimpanan token aman kami membahas rotasi dan pencabutan secara lebih mendalam.

Biometrik: unlock, bukan identitas

Face ID dan sidik jari hanya membuktikan bahwa pemegang ponsel dapat membukanya. Gunakan fitur tersebut untuk membatasi akses ke sesi yang tersimpan:

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

Dengan accessControl set, OS hanya melepaskan nilai setelah pemeriksaan biometrik berhasil, sehingga proteksinya dijalankan oleh Keychain atau Keystore, bukan oleh JavaScript. Padukan dengan kedaluwarsa sesi di sisi server dan, untuk aplikasi berisiko tinggi, deteksi root dan jailbreak. Selengkapnya di Autentikasi biometrik di aplikasi Capacitor.

Memilih metode

Aturan App Store dan Play terkait login

• Layanan Login Apple 4.8: login pihak ketiga sebagai sistem akun utama memerlukan opsi privasi yang setara. Sign in with Apple memenuhi syarat ini.
• Apple 5.1.1(v): pembuatan akun memerlukan penghapusan akun di dalam aplikasi, dan token Sign in with Apple harus dicabut. Lihat kepatuhan penghapusan akun.
• penghapusan akun Google Play: aplikasi dengan akun wajib menyediakan fitur penghapusan di dalam aplikasi dan melalui link web yang terdaftar di Play Console.
• Akses Reviewer: berikan akun demo yang berfungsi kepada reviewer. Jika login hanya menggunakan SSO, sediakan user test tenant.
• Xcode 26: App Store Connect mewajibkan build yang dibuat dengan Xcode 26 dan iOS 26 SDK sejak April 2026, jadi segera update sebelum submit rilis yang menambah fitur auth baru.

Deploy perubahan auth dengan aman

Bug auth berdampak ke semua user, jadi Anda harus memperbaikinya dengan cepat. Perubahan native (entitlements, URL schemes, intent filters) butuh build store. Semua yang berbasis TypeScript, seperti config provider, scope, error handling, dan UI, bisa di-push menggunakan Capgo live updates dan di-rollback jika terjadi error. Capgo Build menghasilkan binary iOS dan Android yang sudah di-sign di cloud saat Anda membutuhkan native release baru.

Next steps

Pilih provider Anda dan ikuti panduan yang sesuai:

• Masuk dengan Apple
• Masuk dengan Google
• Auth0
• Okta
• Microsoft Entra ID
• Better Auth
• Dokumentasi plugin Social Login