Bagaimana Menambahkan Autentikasi ke Aplikasi Capacitor (2026)

Untuk menambahkan autentikasi ke sebuah aplikasi Capacitor, pilih sumber identitas (backend sendiri, layanan yang dihosting seperti Firebase atau Supabase, penyedia OIDC seperti Auth0, Okta atau Entra ID, atau library yang dihost sendiri seperti Better Auth), gunakan plugin native untuk apa pun yang membuka halaman login penyedia, verifikasi token di server, dan simpan hasilnya di Keychain atau Keystore. Biometrik dan passkeys kemudian membuat sign-in berikutnya cepat.

Panduan ini memetakan semua pilihan umum ke plugin Capacitor yang tepat dan alur, dengan code untuk bagian yang sama dalam setiap aplikasi: panggilan login, verifikasi token, penyimpanan sesi dan unggul biometrik. Hal ini sudah diperbarui untuk Capacitor 8 pada Oktober 2026. Setiap penyedia memiliki panduan langkah demi langkah yang terkait di bawah.

Alur autentikasi yang diakhiri oleh setiap aplikasi Capacitor

Tidak peduli penyedia apa yang Anda pilih, bentuknya sama:

1. Identifikasi pengguna: lembaran sosial asli, halaman login penyedia di browser sistem, prompt passkey, atau formulir yang mengirimkan email dan kata sandi.
2. Peroleh bukti:suatu token ID, suatu otorisasi code, atau token sesi dari server autentikasi Anda.
3. Verifikasi di server:periksa tanda tangan, pengirim, audiens, dan kadaluarsa, lalu buat atau temukan pengguna.
4. Issue sesi:token Anda sendiri atau token penyedia, dengan strategi refresh.
5. Simpan dengan aman di perangkat dan pasangkannya ke API panggilan.
6. Terbuka dengan cepat Selanjutnya dengan biometrik, dan mengelola keluar dan penghapusan akun.

Langkah 1 dan 2 berubah dengan penyedia. Langkah 3 hingga 6 adalah tanggung jawab Anda dalam setiap opsi except BaaS yang sepenuhnya dihosting, di mana SDK melakukan sebagian besar hal.

Mengapa halaman login WebView rusak.

Aplikasi Capacitor menjalankan web code Anda di dalam WKWebView (iOS) atau Android WebView dengan asal lokal ("capacitor://localhost atau https://localhostBeberapa masalah muncul ketika memuat halaman login provider di dalam WebView tersebut.

• Google returns disallowed_useragent tidak menampilkan halaman.
• Aplikasi tidak dapat membuktikan bahwa halaman ini adalah penyedia asli, sehingga RFC 8252 menginstruksikan aplikasi native untuk menggunakan browser sistem.
• Pindah halaman penuh mengarahkan pengguna keluar dari aplikasi bundel Anda dan kehilangan status.

Jadi setiap aliran di bawah ini menggunakan baik SDK native (Apple, Google, Facebook) atau sebuah sesi browser sistem (ASWebAuthenticationSession Jadi setiap aliran di bawah ini menggunakan baik native __CAPGO_KEEP_0__ (Apple, Google, Facebook) atau sesi browser sistem (

Pilihan Anda secara singkat

Pengenalan sosial asli (Apple, Google, Facebook)

Satu plugin mencakup tiga penyedia konsumen besar plus mesin OAuth2 umum:

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 penyedia yang tidak Anda gunakan di capacitor.config.ts (plugins.SocialLogin.providers) sehingga SDK-nya tidak dikompilasi ke dalam aplikasi. Hal itu juga menghapus izin ID iklan Facebook SDK jika Anda tidak menggunakan Facebook.

Pengaturan asli setiap penyedia: Apple memerlukan kemampuan di Xcode dan ID Layanan untuk Android, Google memerlukan fingerprint SHA-1 dan skema URL klien yang dibalik. Apple dan Google Petunjuk ini menjelaskan setiap langkah dan kesalahan umum.

Enterprise SSO dengan OAuth 2.0 dan OpenID Connect

Untuk Auth0, Okta, Microsoft Entra ID, Keycloak, Cognito, OneLogin atau server OIDC milik Anda sendiri, gunakan plugin’s oauth2 provider. Ini menjalankan alur otorisasi code dengan PKCE di ASWebAuthenticationSession on iOS dan di Custom Tabs pada Android ketika 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 dalam map yang sama dan memilih salah satu dengan providerId, yang merupakan cara aplikasi B2B multi-tenant memungkinkan setiap pelanggan membawa IdP mereka sendiri. Plugin ini juga menghandle refresh (SocialLogin.refresh), logout dengan id_token_hint, dan wrapper kompatibel Ionic Auth Connect (SocialLoginAuthConnect) untuk tim yang beralih dari Auth Connect. Petunjuk provider: Auth0, Okta, Masuk ID. Untuk latar belakang protokol, lihat 5 langkah untuk menerapkan OAuth2 di aplikasi Capacitor.

Backend yang dihosting: Firebase dan Supabase

Jika data Anda sudah berada di Firebase atau Supabase, gunakan autentikasi mereka agar aturan keamanan dan keamanan tingkat baris bekerja tanpa perlu perangkat lunak tambahan.

• Supabase: dapatkan token ID dengan plugin Login Sosial dan panggil supabase.auth.signInWithIdToken({ provider: 'google', token }). Supabase memverifikasi dan mengembalikan sebuah sesi. Konfigurasi lengkap: Supabase dengan Capacitor Login Sosial.
• Firebase: baik menggunakan @capgo/capacitor-firebase-authentication, yang menyelubungi SDK autentikasi native Firebase, atau dapatkan token ID dengan Login Sosial dan buat kredensial Firebase dari itu di JS SDK. Lihat Firebase Google login docs.

Self-hosted: Otoritas Lebih Baik

Otoritas Lebih Baik adalah sebuah library autentikasi TypeScript terbuka yang menyimpan pengguna di database milik Anda sendiri. Ini berfungsi di Capacitor setelah Anda mempercayai asal aplikasi dan beralih ke token bearer, karena cookie lintas-situs tidak dapat diandalkan di WKWebView. Login sosial melalui plugin native dan tukar token ID. Langkah demi langkah: How to use Better Auth in Capacitor apps.

Passkeys

Passkeys menggantikan kata sandi dengan pasangan kunci yang disimpan di iCloud Keychain atau Google Password Manager. Mereka membutuhkan aplikasi Anda untuk terkait dengan domain website Anda (apple-app-site-association di iOS, assetlinks.json di Android) dan sebuah server WebAuthn.

@capgo/capacitor-passkey memungkinkan Anda untuk menjaga WebAuthn standar code. Konfigurasi pihak yang dipercaya di capacitor.config.tsmemanggil shim sekali di awal, dan navigator.credentials.create() dan .get() Ditangani 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,
});

Perpustakaan seperti Better Auth, dan penyedia yang dihosting seperti Auth0 dan Okta, dapat berfungsi sebagai server WebAuthn. Lihat halaman plugin passkey halaman plugin passkey.

Tidak perlu plugin, itu hanya

Tidak perlu plugin, hanya 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.

Verifikasi token di server, selalu

Pemeriksaan di sisi klien dapat dilompati. Apapun penyedia, server harus memverifikasi token sebelum membuat sesi:

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 Tautan akun hanya dapat dibuat melalui email ketika penyedia menandai email tersebut sebagai terverifikasi ("verified")email_verified: trueToken Meta Limited Login tidak termasuk klaim tersebut.

Simpan Sesi dengan Aman

localStorage dan Capacitor Preferensi adalah file teks biasa. Simpan token yang berumur lama di Keychain (iOS) atau penyimpanan yang dienkripsi Keystore (Android). @capgo/capacitor-native-biometric memiliki sederhana setData, getData dan deleteData metode 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(() => {});
  },
};

Tetapkan token akses singkat dan segarkan mereka dengan token segar atau sesi server. Kami meliputi rotasi dan revokasi dalam lebih mendalam. Biometrik: buka, bukan identitas

Biometrik: buka, bukan identitas

Menggunakan Face ID dan sidik jari hanya membuktikan bahwa orang yang memegang ponsel dapat membukanya. Gunakan fitur ini untuk mengatur akses ke sesi yang disimpan:

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

With accessControl set, the OS releases the value only after a successful biometric check, so the protection is enforced by the Keychain or Keystore, not by JavaScript. Pair it with server-side session expiry and, for high-risk apps, root and jailbreak detection. More in Autentikasi biometrik di aplikasi Capacitor.

metode untuk itu:

Aturan App Store dan Play yang mempengaruhi login

• Apple 4.8 Layanan Login: login pihak ketiga sebagai sistem akun utama memerlukan pilihan privasi-fokus yang setara. Masuk dengan Apple memenuhinya.
• Apple 5.1.1(v): pembuatan akun memerlukan penghapusan akun di dalam aplikasi, dan token Sign in dengan Apple harus di-revoke. Lihat kompilasi penghapusan akun.
• penghapusan akun Google Play: aplikasi dengan akun harus menawarkan penghapusan di dalam aplikasi dan melalui tautan web yang diumumkan di Console Play.
• Akses reviewer: berikan reviewer akun demo yang berfungsi. Jika login hanya SSO, berikan pengguna tenant test.
• Xcode 26: App Store Connect telah memerlukan build yang dibuat dengan Xcode 26 dan iOS 26 SDK sejak April 2026, jadi update sebelum Anda mengirimkan rilis yang menambahkan kemampuan autentikasi baru.

Kirim perubahan autentikasi dengan aman

Bug autentikasi menghalangi setiap pengguna, jadi Anda ingin memperbaikinya dengan cepat. Perubahan asli (hak istimewa, skema URL, filter tujuan) memerlukan build toko. Semua di TypeScript, seperti konfigurasi penyedia, ruang lingkup, penanganan kesalahan, dan UI, dapat diteruskan dengan Capgo pembaruan hidup dan dapat dibalik jika ada yang rusak. Capgo Bangun Menghasilkan file biner iOS dan Android yang ditandatangani di cloud ketika Anda memerlukan rilis native baru.

Langkah berikutnya

Pilih penyedia Anda dan ikuti panduan yang sesuai.

• Masuk dengan Apple
• Masuk dengan Google
• Auth0
• Okta
• Azure Active Directory
• Better Auth
• Dokumentasi plugin Login Sosial