How to Sign In with Okta Using Capacitor

Untuk masuk dengan Okta di sebuah aplikasi Capacitor, buatlah Aplikasi OIDC Native dalam Konsole Admin Okta, daftarkan URI redirect masuk seperti com.example.app://oauth/okta, dan jalankan alur otorisasi code dengan PKCE di browser sistem. Dengan @capgo/capacitor-social-login anda mengonfigurasi Okta sekali dengan issuer dan ID klien, kemudian panggil SocialLogin.login({ provider: 'oauth2', options: { providerId: 'okta' } }).

Guide ini mencakup integrasi aplikasi Okta, kebijakan server otorisasi, plugin code untuk iOS, Android, dan web, pembaruan token, profil pengguna, keluar, dan kesalahan Okta yang paling sering muncul. Ini berfokus pada Capacitor 8 sejak Oktober 2026.

Apa yang Anda butuhkan

• Organisasi Okta (Identitas Kerja atau Identitas Pelanggan) dengan akses admin untuk membuat integrasi aplikasi.
• Aplikasi Capacitor 8.
• Token Capacitor Anda. appId, yang akan Anda gunakan kembali sebagai skema redirect.
• Opsional, backend API yang memvalidasi token akses Okta.

Bagaimana login Okta bekerja di aplikasi Capacitor

Aplikasi Anda tidak menampilkan formulir password. Membuka halaman login Okta di browser aman, Okta mengelola MFA dan kebijakan, kemudian mengarahkan kembali ke aplikasi Anda dengan code. Aplikasi Anda menukar code plus verifikasi PKCE untuk token.

Pilih Custom Tabs di Android. Okta Verify, FastPass, dan passkeys berperilaku lebih baik di browser sistem daripada di WebView yang diintegrasikan, dan cookie SSO dibagikan dengan Chrome.

Langkah 1: Buat Integrasi Aplikasi Okta

1. In konsol Admin Okta, pergi ke Aplikasi > Aplikasi > Buat Integrasi Aplikasi.
2. Pilih OIDC - OpenID Connect dan Aplikasi Asli.
3. Namainya, lalu di bawah Tipe Ijin tetapkan Izin Autentikasi Code dan centang Token Refres Jika pengguna harus tetap masuk.
4. URI Redirect Masuk: com.example.app://oauth/okta. Tambahkan https://app.example.com/auth/callback Jika Anda mengirimkan build web.
5. URI Redirect Keluar: com.example.app://oauth/logout (dan URL web jika diperlukan).
6. Pengaturan: pilih siapa yang dapat menggunakan aplikasi. Pengguna yang tidak diberi akses akan mendapatkan kesalahan saat masuk.
7. Simpan, lalu salin ID Klien. Di bawah Kredensial Klien, autentikasi klien haruslah Tidak Ada dan Tentukan PKCE Memerlukan PKCE

Okta memerlukan URI redirect asli untuk menggunakan skema penggunaan pribadi dalam bentuk domain-reverse. ID paket atau ID aplikasi Anda cocok.

Periksa server otorisasi

Pergi ke Kebijakan Keamanan > API > Server OtentikasiKeamanan > __CAPGO_KEEP_0__ > Server Otorisasi default pengaturan otorisasi khusus, penyedia https://your-org.okta.com/oauth2/default.

Buka server's Pengaturan Kebijakan Akses Aplikasi Anda harus memiliki kebijakan yang diperlukan (atau untuk semua klien) dengan aturan yang memungkinkan akses. Otorisasi Code otorisasi dan Token Refresk Jika Anda menggunakannya. Aturan yang hilang menghasilkan “Policy evaluation failed for this request”.

Asal-Asal Terpercaya untuk web

Jika Anda menjalankan yang sama code di web, tambahkan asal web Anda di bawah Keamanan > API > Asal-Asal Terpercaya dengan CORS dipilih. Tanpa itu, browser menghalangi permintaan token.

Langkah 2: Pasang plugin

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

Jika Okta adalah penyedia tunggal, matikan SDK sosial yang dibundel di capacitor.config.ts:

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

Langkah 3: Tambahkan filter intent Android

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

<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 nilai default Capacitor, sehingga redirect tiba di aktivitas yang 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 yang lebih singkat: atur issuerUrl: OKTA_ISSUER dan jatuhkan URL endpoint. Plugin tersebut memuat /.well-known/openid-configuration dan mengisi mereka. Tim yang bermigrasi dari Ionic Auth Connect dapat menggunakan SocialLoginAuthConnect dengan okta denganissuer, clientId, redirectUrlDapat dilindungi oleh) Petunjuk 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, sehingga Anda mendapatkan profil tanpa permintaan lain. Untuk membaca klaim token ID untuk ditampilkan, gunakan SocialLogin.decodeIdToken({ idToken })Panggilan tersebut tidak memeriksa tanda tangan.

Option login yang perlu Anda ketahui:

• loginHint mengisi username secara otomatis.
• prompt: 'login' memaksa autentikasi ulang bahkan dengan sesi aktif Okta.
• additionalParameters: { idp: '0oa...' } mengarahkan langsung ke penyedia identitas tertentu yang telah dikonfigurasi di Okta.

Pada web dengan flow: 'redirect'panggil SocialLogin.handleRedirectCallback() pada halaman panggilan balik untuk menyelesaikan pertukaran.

Langkah 6: Validasi token Okta di API

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 audiens di server otorisasi Pengaturan tab. Jangan memvalidasi token akses dari server otorisasi organisasi di dalam API. Okta tidak mendukung itu.

Langkah 7: Mengrefresh 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 token refresh telah kedaluwarsa atau dibatalkan, refresh ditolak. Tangkap itu dan kirim pengguna kembali ke signInWithOkta().

Periksa Bagian Token Refresh bagian integrasi aplikasi. Dengan Mengganti token setelah digunakan, setiap refresh mengembalikan token refresh baru dan token lama tidak berfungsi setelah periode waktu singkat. Plugin mengganti salinan yang disimpan secara otomatis. Jika Anda menyimpan token refresh sendiri (misalnya di Keychain melalui @capgo/capacitor-native-biometric setData) SocialLogin.refreshToken({ provider: 'oauth2', providerId: 'okta', refreshToken }) dan simpan nilai yang dikembalikan.

Langkah 8: Keluar

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

Plugin ini menghapus token yang disimpan, kemudian membuka /v1/logout bersama id_token_hint dan post_logout_redirect_uriOkta mengakhiri sesi dan mengarahkan ke URI keluar yang harus terdaftar di integrasi aplikasi. Pada perangkat mobile, halaman keluar membuka di browser sistem.

Revoke token refresh di server dengan menghubungi Okta /v1/revoke endpoint dari backend Anda atau aplikasi sebelum keluar. Lihat di sini Petunjuk Penghapusan Token Troubleshooting

Troubleshooting

Mengaktifkan logsEnabled: true dalam konfigurasi penyedia sambil melakukan debug untuk melihat URL autentikasi dan respons token di log native.

Mengimplementasikan perubahan Okta

Pelanggan perusahaan sering mengubah kebijakan atau klaim setelah peluncuran. Perubahan sisi klien seperti ruang lingkup, penanganan klaim, atau layar kesalahan dapat dikirimkan dengan Capgo pembaruan hidup Alih-alih menulis ulasan toko penuh. Bagian asli (filter tujuan, skema baru) masih memerlukan pembangunan baru.

Petunjuk terkait

• How to sign in with Auth0 using Capacitor
• Cara masuk dengan menggunakan Microsoft Entra ID menggunakan Capacitor
• Bagaimana cara masuk dengan Auth0 menggunakan Capacitor
• Dokumen Integrasi Okta untuk Plugin Login Sosial