Cara Menambahkan Autentikasi ke Aplikasi Capacitor (2026)

Untuk menambahkan autentikasi ke aplikasi Capacitor, pilih sumber identitas (backend Anda sendiri, layanan hosted seperti Firebase, Supabase, atau Neon, provider OIDC seperti Auth0, Okta, atau Entra ID, atau library self-hosted seperti Better Auth), gunakan plugin native untuk apa pun yang membuka halaman login provider, verifikasi token di server, dan simpan sesi yang dihasilkan di Keychain atau Keystore. Biometrik dan passkey kemudian membuat login berikutnya cepat.

Panduan ini memetakan setiap opsi umum ke plugin dan alur Capacitor yang tepat, dengan code untuk bagian yang sama di setiap aplikasi: panggilan login, verifikasi token, penyimpanan sesi, dan unlock biometrik. Panduan ini sudah diperbarui untuk Capacitor 8 pada Oktober 2026. Setiap provider memiliki panduan langkah demi langkah 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, code otorisasi, 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 cepat lain kali dengan biometrik, serta tangani logout dan penghapusan akun.

Langkah 1 dan 2 berubah tergantung provider. Langkah 3 hingga 6 adalah tanggung jawab Anda di semua opsi, kecuali BaaS yang sepenuhnya di-host, di mana SDK menangani sebagian besar.

Mengapa halaman login WebView rusak

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

• Google mengembalikan disallowed_useragent dan menolak menampilkan halaman.
• Aplikasi tidak dapat membuktikan bahwa halaman tersebut adalah penyedia asli, itulah mengapa RFC 8252 menyarankan aplikasi native untuk menggunakan browser sistem.
• Redirect halaman penuh akan menavigasi keluar dari aplikasi ter-bundle Anda dan kehilangan state.

Jadi setiap alur di bawah menggunakan SDK native (Apple, Google, Facebook) atau sesi browser sistem (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 konsumen 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.providerssehingga SDK mereka tidak di-compile ke dalam aplikasi. Ini juga menghapus izin advertising ID Facebook SDK jika Anda tidak memakai Facebook.

Setiap provider punya setup native: Apple butuh capability di Xcode dan Services ID; untuk Android, Google butuh fingerprint SHA-1 dan URL scheme client ID terbalik. Apple dan Google Panduan membahas setiap langkah dan error umum.

Enterprise SSO dengan OAuth 2.0 dan OpenID Connect

Untuk Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin, atau server OIDC Anda sendiri, gunakan plugin's oauth2 provider. Ini menjalankan alur otorisasi code dengan PKCE di ASWebAuthenticationSession di iOS dan di 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 dapat mendaftarkan beberapa provider di map yang sama dan memilih salah satunya dengan providerId, yang merupakan cara aplikasi B2B multi-tenant memungkinkan setiap pelanggan membawa IdP mereka sendiri. Plugin ini juga menangani refresh (SocialLogin.refresh), logout dengan id_token_hint, dan wrapper kompatibel Ionic Auth Connect (SocialLoginAuthConnect) untuk tim yang bermigrasi dari Auth Connect. Panduan provider: Auth0, Okta, Entra ID. Untuk latar belakang protokol, lihat 5 langkah implementasi OAuth2 di aplikasi Capacitor.

Backend hosted: Firebase, Supabase, dan Neon

Jika data Anda sudah ada di Firebase, Supabase, atau Neon, gunakan auth mereka agar security rules dan row-level security berfungsi tanpa perlu glue tambahan.

• Supabase: dapatkan ID token dengan plugin Social Login dan panggil supabase.auth.signInWithIdToken({ provider: 'google', token }). Supabase memverifikasinya dan mengembalikan session. Setup lengkap: Supabase dengan Capacitor Social Login.
• Neon: Neon Auth adalah Better Auth terkelola yang berjalan di branch Neon Anda. @capgo/capacitor-neon memproses sign-in pengguna secara native dengan email dan password, email OTP, atau Google, GitHub dan Vercel OAuth di browser sistem. Ini mengembalikan JWT untuk Data Neon API, sehingga row-level security tetap berlaku. Setup lengkap: dokumentasi plugin Neon.
• Firebase: Anda bisa menggunakan @capgo/capacitor-firebase-authentication, yang membungkus native Firebase Auth SDK, atau ambil ID token dengan Social Login dan buat kredensial Firebase darinya di JS SDK. Lihat Dokumentasi Firebase Google login.

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 mem-trust origin aplikasi dan beralih ke bearer token, karena cross-site cookie tidak bisa diandalkan di WKWebView. Social login berjalan lewat native plugin dan handoff ID token. Langkah-langkahnya: Cara menggunakan Better Auth di aplikasi Capacitor.

Passkeys

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

@capgo/capacitor-passkey memungkinkan Anda tetap memakai code WebAuthn standar. Konfigurasi relying party di capacitor.config.ts, panggil shim sekali saat startup, dan navigator.credentials.create() dan .get() 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 hosted seperti Auth0 dan Okta, bisa berperan sebagai server WebAuthn. Lihat halaman plugin passkey.

Email dan password dengan backend sendiri

Tidak perlu plugin, ini hanya fetch. Pekerjaannya ada di sisi server: hash dengan Argon2id atau bcrypt, batasi rate percobaan login, kirim email verifikasi dan reset, serta dukung penghapusan akun. Buka link reset dan verifikasi di dalam app lewat Universal Links dan App Links, supaya link-nya mendarat di tempat yang tepat di ponsel. Kecuali Anda punya alasan untuk mengurus semua itu sendiri, library seperti Better Auth atau layanan hosted memberi fitur yang sama dengan risiko lebih kecil.

Selalu verifikasi token di server

Pengecekan di sisi client bisa dilewati. Apa pun providernya, server wajib 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
}

Kunci user berdasarkan sub (ditambah nama provider), bukan berdasarkan email. Hubungkan akun lewat email hanya jika provider menandainya terverifikasi (email_verified: true). Token Limited Login dari 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 punya 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 access token tetap berumur pendek dan perbarui lewat refresh token atau sesi server. Panduan penyimpanan token aman kami membahas rotasi dan pencabutan 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 merilis nilai tersebut setelah pemeriksaan biometrik berhasil, jadi proteksinya ditegakkan oleh Keychain atau Keystore, bukan JavaScript. Padukan dengan masa berlaku 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 Store terkait login

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

Rilis 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 Live updates Capgo dan di-rollback jika ada masalah. Build Capgo menghasilkan binary iOS dan Android yang sudah ditandatangani di cloud saat Anda memang perlu rilis native baru.

Langkah berikutnya

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