Cara Login dengan Okta Menggunakan Capacitor

Untuk sign in dengan Okta di aplikasi Capacitor, buat sebuah Aplikasi Native OIDC di Okta Admin Console, daftarkan sign-in redirect URI seperti com.example.app://oauth/okta, dan jalankan alur otorisasi code dengan PKCE di browser sistem. Dengan @capgo/capacitor-social-login Anda cukup mengonfigurasi Okta sekali dengan issuer dan client ID Anda, lalu panggil SocialLogin.login({ provider: 'oauth2', options: { providerId: 'okta' } }).

Panduan ini mencakup integrasi aplikasi Okta, kebijakan server otorisasi, plugin code untuk iOS, Android, dan web, pembaruan token, profil pengguna, logout, serta error Okta yang paling sering muncul. Panduan ini menargetkan Capacitor 8 per Oktober 2026.

Yang Anda butuhkan

• Organisasi Okta (Workforce Identity atau Customer Identity) dengan akses admin untuk membuat integrasi aplikasi.
• Aplikasi Capacitor 8.
• Capacitor Anda appId, yang akan Anda gunakan kembali sebagai skema redirect.
• Secara opsional, backend API yang memvalidasi access token Okta.

Cara kerja login Okta di aplikasi Capacitor

Aplikasi Anda tidak pernah menampilkan formulir kata sandi. Aplikasi membuka halaman sign-in Okta di browser yang aman, Okta menangani MFA dan kebijakan, lalu mengalihkan kembali ke aplikasi Anda dengan code. Aplikasi menukar code plus verifier PKCE untuk token.

Utamakan Custom Tabs di Android. Okta Verify, FastPass, dan passkey bekerja lebih baik di browser sistem daripada di WebView tertanam, dan cookie SSO dibagikan dengan Chrome.

Langkah 1: Buat integrasi aplikasi Okta

1. Di Okta Admin Console, buka Applications > Applications > Create App Integration.
2. Pilih OIDC - OpenID Connect dan Aplikasi Native.
3. Beri nama, lalu di bagian Tipe grant biarkan Otorisasi Code dan centang Refresh Token jika pengguna harus tetap masuk.
4. URI redirect sign-in: com.example.app://oauth/okta. Tambahkan https://app.example.com/auth/callback jika Anda merilis web build.
5. URI redirect sign-out: com.example.app://oauth/logout (dan URL web jika diperlukan).
6. Assignments: pilih siapa yang bisa menggunakan aplikasi. Pengguna yang tidak ditugaskan akan menerima error saat sign-in.
7. Simpan, lalu salin Client ID. Di bawah Kredensial Klien, autentikasi klien harus Tidak ada dan Wajibkan PKCE harus diaktifkan.

Okta memerlukan URI redirect native yang menggunakan skema private-use dalam format reverse-domain. Bundle ID atau application ID Anda cocok untuk ini.

Periksa authorization server

Buka Keamanan > API > Server Otorisasi. Sebagian besar setup menggunakan default authorization server kustom, issuer https://your-org.okta.com/oauth2/default.

Open the server’s Kebijakan Akses tab. Harus ada policy yang ditugaskan ke aplikasi Anda (atau All clients) dengan aturan yang mengizinkan Otorisasi Code grant, dan Refresh Token jika Anda menggunakannya. Jika aturan tidak ada, akan muncul “Policy evaluation failed for this request”.

Trusted Origins untuk web

Jika Anda menjalankan code yang sama di web, tambahkan origin web Anda di bawah Keamanan > API > Trusted Origins dengan CORS dicentang. Tanpa ini, browser akan memblokir permintaan token.

Langkah 2: Instal plugin

bun add @capgo/capacitor-social-login
bunx cap sync

Jika Okta adalah satu-satunya provider, matikan bundled social SDK di dalam capacitor.config.ts:

plugins: {
  SocialLogin: {
    providers: { google: false, facebook: false, apple: false, twitter: false },
  },
},

Langkah 3: Tambahkan intent filter redirect Android

Di android/app/src/main/AndroidManifest.xml, di dalam MainActivity activity:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="com.example.app" android:host="oauth" />
</intent-filter>

MainActivity harus tetap android:launchMode="singleTask", yang merupakan default Capacitor, sehingga redirect tiba di activity yang sedang berjalan.

Langkah 4: Inisialisasi Okta

import { Capacitor } from '@capacitor/core';
import { SocialLogin } from '@capgo/capacitor-social-login';

const OKTA_ISSUER = 'https://your-org.okta.com/oauth2/default';
const isWeb = Capacitor.getPlatform() === 'web';

export async function initAuth() {
  await SocialLogin.initialize({
    oauth2: {
      okta: {
        appId: 'YOUR_OKTA_CLIENT_ID',
        authorizationBaseUrl: `${OKTA_ISSUER}/v1/authorize`,
        accessTokenEndpoint: `${OKTA_ISSUER}/v1/token`,
        resourceUrl: `${OKTA_ISSUER}/v1/userinfo`,
        redirectUrl: isWeb
          ? 'https://app.example.com/auth/callback'
          : 'com.example.app://oauth/okta',
        scope: 'openid profile email offline_access',
        pkceEnabled: true,
        logoutUrl: `${OKTA_ISSUER}/v1/logout`,
        postLogoutRedirectUrl: isWeb
          ? 'https://app.example.com/'
          : 'com.example.app://oauth/logout',
        androidUseCustomTabs: true,
      },
    },
  });
}

Alternatif lebih singkat: set issuerUrl: OKTA_ISSUER dan hapus URL endpoint. Plugin memuat /.well-known/openid-configuration dan mengisinya. Tim yang bermigrasi dari Ionic Auth Connect dapat menggunakan SocialLoginAuthConnect dengan okta preset (issuer, clientId, redirectUrl), dibahas di panduan migrasi.

Langkah 5: Masuk dan baca profil

import { SocialLogin } from '@capgo/capacitor-social-login';

export async function signInWithOkta() {
  try {
    const { result } = await SocialLogin.login({
      provider: 'oauth2',
      options: { providerId: 'okta' },
    });

    const profile = result.resourceData as {
      sub: string;
      email?: string;
      name?: string;
      preferred_username?: string;
    } | null;

    return {
      accessToken: result.accessToken?.token,
      idToken: result.idToken,
      refreshToken: result.refreshToken,
      scopes: result.scope,
      profile,
    };
  } catch (error: any) {
    if (error?.code === 'USER_CANCELLED') return null;
    throw error;
  }
}

resourceData menyimpan JSON yang dikembalikan oleh /userinfo endpoint, jadi Anda mendapatkan profil tanpa request tambahan. Untuk membaca claims ID token untuk ditampilkan, gunakan SocialLogin.decodeIdToken({ idToken }). Pemanggilan tersebut tidak memverifikasi signature.

Opsi login yang perlu diketahui:

• loginHint mengisi otomatis username.
• prompt: 'login' memaksa autentikasi ulang meskipun sesi Okta aktif.
• additionalParameters: { idp: '0oa...' } mengarahkan langsung ke identity provider tertentu yang dikonfigurasi di Okta.

Di web dengan flow: 'redirect', panggil SocialLogin.handleRedirectCallback() di halaman callback untuk menyelesaikan exchange.

Langkah 6: Validasi token Okta di API Anda

import { createRemoteJWKSet, jwtVerify } from 'jose';

const ISSUER = 'https://your-org.okta.com/oauth2/default';
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/v1/keys`));

export async function verifyOktaAccessToken(token: string) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
    audience: 'api://default', // the Audience value of your authorization server
  });
  return payload; // payload.uid is the Okta user ID, payload.sub the login
}

Temukan audience pada authorization server Pengaturan authorization server. Jangan validasi access token dari org authorization server di API Anda. Okta tidak mendukungnya.

Langkah 7: Refresh token

import { SocialLogin } from '@capgo/capacitor-social-login';

export async function ensureFreshOktaToken() {
  const { isLoggedIn } = await SocialLogin.isLoggedIn({ provider: 'oauth2', providerId: 'okta' });
  if (!isLoggedIn) {
    await SocialLogin.refresh({ provider: 'oauth2', options: { providerId: 'okta' } });
  }
  const { accessToken } = await SocialLogin.getAuthorizationCode({ provider: 'oauth2', providerId: 'okta' });
  return accessToken;
}

Jika refresh token kedaluwarsa atau dicabut, refresh ditolak. Tangkap error tersebut dan arahkan user kembali ke signInWithOkta().

Cek Refresh Token bagian integrasi aplikasi. Dengan Rotasi token setiap kali digunakan, setiap refresh mengembalikan refresh token baru dan token lama berhenti berfungsi setelah masa grace period singkat. Plugin mengganti salinan yang tersimpan secara otomatis. Jika Anda menyimpan refresh token sendiri (misalnya di Keychain melalui @capgo/capacitor-native-biometric setData), gunakan SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'okta', refreshToken }) dan simpan nilai yang dikembalikan.

Langkah 8: Keluar

await SocialLogin.logout({ provider: 'oauth2', providerId: 'okta' });

Plugin menghapus token yang tersimpan, lalu membuka /v1/logout dengan id_token_hint dan post_logout_redirect_uri. Okta mengakhiri sesi dan mengalihkan ke URI sign-out Anda, yang harus terdaftar di integrasi aplikasi. Di mobile, halaman logout terbuka di browser sistem.

Untuk juga mencabut refresh token di sisi server, panggil /v1/revoke endpoint Okta dari backend atau aplikasi sebelum logout. Lihat panduan pencabutan token kami untuk polanya.

Pemecahan Masalah

Aktifkan logsEnabled: true di config provider saat debugging untuk melihat URL otorisasi dan respons token di log native.

Merilis perubahan Okta

Pelanggan Enterprise sering mengubah kebijakan atau claim setelah peluncuran. Perubahan sisi client seperti scope, penanganan claim, atau layar error bisa dirilis dengan Live updates Capgo alih-alih melalui peninjauan toko aplikasi secara penuh. Bagian native (intent filter, scheme baru) tetap memerlukan build baru.

Panduan terkait

• Cara login dengan Auth0 menggunakan Capacitor
• Cara login dengan Microsoft Entra ID menggunakan Capacitor
• Cara menambah autentikasi ke aplikasi Capacitor
• Dokumentasi integrasi Okta untuk plugin Social Login