Penyiapan integrasi Okta - Living Security Platform

Ikhtisar

Okta dapat menyumbangkan data ternormalisasi tentang siklus hidup pengguna, autentikasi, MFA, dan aktivitas administratif. Contoh yang telah ditinjau meliputi:

account.locked — akun terkunci
mfa.factor.activated — mengaktifkan faktor MFA tambahan
auth.login.failed — gagal masuk

Kedua metode koneksi membaca dua aliran yang sama — direktori pengguna (/api/v1/users) dan log sistem (/api/v1/logs). Lihat bagaimana data integrasi menjadi sinyal.

Pilih metode koneksi

	Okta (SSWS)	Okta (OAuth 2.0)
Kredensial	Token API yang Anda buat di Admin Console	ID klien dan JWK privat yang Anda buat dan daftarkan
Penyiapan	Tiga langkah, tanpa perlu membuat materi kunci	Sembilan langkah, termasuk pasangan kunci RSA
Peran administrator yang diperlukan	Administrator hanya-baca, ditetapkan kepada pemilik token	Administrator hanya-baca, ditetapkan kepada aplikasi
Masa berlaku token	Dinonaktifkan setelah 30 hari tanpa penggunaan	Tidak kedaluwarsa; rotasi pasangan kunci menjadi tanggung jawab Anda
Gunakan ketika	Ini adalah jalur yang direkomendasikan bagi sebagian besar organisasi	Kebijakan keamanan Anda melarang token API berumur panjang

Kedua metode memerlukan akses yang sama, sehingga pilihan ini menyangkut penanganan kredensial, bukan apa yang dapat dibaca oleh platform.

Opsi A — Token API (SSWS)

Direkomendasikan.

Yang dibutuhkan Living Security

Kredensial	Deskripsi
Kunci API	Token API Okta. Dialog koneksi memberi label Kunci API pada kolom ini
Subdomain tenant	`<tenant>` dalam `<tenant>.okta.com` — hanya subdomain, bukan URL lengkap

Prasyarat

Anda harus menjadi Super Administrator Okta untuk membuat pengguna akun layanan, menetapkan peran administrator, dan membuat token API.

Buat pengguna sebagai pemilik token

Token API Okta membawa izin dari pengguna yang membuatnya, dan token tersebut berhenti berfungsi jika pengguna itu dinonaktifkan. Buatlah akun layanan khusus dan jangan menggunakan akun admin pribadi, agar koneksi tetap berfungsi ketika terjadi pergantian staf.

Di Admin Console, buka Directory → People.
Klik Add person dan buat pengguna seperti svc-livingsecurity@yourcompany.com.
Aktifkan akun tersebut.

Tetapkan peran administrator hanya-baca

Platform hanya membaca data. Memberikan akses lebih dari akses baca akan memberi token izin yang tidak pernah digunakan.

Buka Keamanan → Administrators.
Klik Add administrator dan pilih pengguna dari langkah sebelumnya.
Tetapkan peran Read-only Administrator.
Simpan.

Tanpa peran administrator, panggilan ke Okta Management API berhasil dengan 200 OK dan mengembalikan daftar kosong. Tidak ada 403 yang memberi tahu Anda bahwa peran tersebut tidak ada — aliran data hanya tetap kosong.

Buat token API

Masuk ke Admin Console sebagai pengguna akun layanan dari langkah 1. Token mewarisi akun mana pun yang membuatnya.
Buka Keamanan → API dan buka tab Tokens.
Klik Create token, beri nama seperti Living Security Platform, lalu klik Create token.
Salin nilai token sekarang — Okta hanya menampilkannya sekali dan tidak akan menampilkannya lagi.

Okta menonaktifkan token API setelah 30 hari tanpa penggunaan. Sinkronisasi dalam integrasi ini berjalan setidaknya sekali sehari, sehingga koneksi yang aktif menjaga tokennya tetap hidup. Koneksi yang dijeda selama sebulan memerlukan token baru.

Daftar alamat di atas hanya relevan jika org Okta Anda membatasi akses API berdasarkan network zone. Sebagian besar org tidak melakukannya.

Temukan subdomain tenant Anda

URL Admin Console Anda terlihat seperti https://acme-admin.okta.com. Subdomain tenant adalah acme — tanpa akhiran -admin, tanpa .okta.com, dan tanpa https://.

Sekarang Anda telah terhubung ke Okta (SSWS).

Pemecahan masalah

401 Unauthorized

Token tidak valid, telah dicabut, atau telah dinonaktifkan setelah 30 hari tidak aktif. Buat token baru sebagai pengguna akun layanan dan masukkan kembali pada koneksi.

Terhubung, tetapi setiap aliran kosong

Pemilik token tidak memiliki peran administrator. Tetapkan Read-only Administrator kepada akun layanan (langkah 2) — API mengembalikan 200 OK dengan daftar kosong, bukan kesalahan, ketika peran tersebut tidak ada.

Sinkronisasi gagal setelah pergantian staf

Token berhenti berfungsi jika pengguna yang membuatnya dinonaktifkan. Inilah sebabnya token sebaiknya dimiliki oleh akun layanan, bukan oleh perorangan.

Opsi B — Aplikasi layanan OAuth 2.0

Gunakan metode ini ketika kebijakan keamanan Anda tidak mengizinkan token API berumur panjang. Metode ini menggantikan token dengan ID klien dan pasangan kunci RSA milik Anda. Di platform, ini adalah tile Okta (OAuth 2.0), di bawah Pengaturan → Integrasi → Katalog. Untuk melakukan autentikasi dengan Okta menggunakan Client Credentials, Anda memerlukan hal berikut:

ID Klien - Pengenal unik untuk aplikasi Okta API Services Anda.
Private Key (JWK) - Kunci privat RSA dalam format JSON Web Key, yang kunci publiknya didaftarkan di aplikasi Okta Anda.
Okta Domain - Hanya subdomain tenant Okta Anda (mis. dev-12345678), bukan nama host lengkap.
Scopes - Daftar scope Okta Management API yang dipisahkan spasi (mis. okta.users.read okta.logs.read).

Panduan ini akan membantu Anda membuat aplikasi API Services di Okta dengan autentikasi private_key_jwt.

Prasyarat:

Anda harus memiliki akun Okta. Daftar untuk akun developer gratis di developer.okta.com.

Langkah 1: Membuat aplikasi Okta API Services Anda

Masuk ke Okta Admin Console Anda.
Di bilah sisi kiri, buka Applications > Applications.
Klik Create App Integration.
Pilih API Services sebagai metode masuk dan klik Selanjutnya.

Beri nama pada aplikasi Anda dan klik Simpan.
Pada tab General aplikasi, temukan ID Klien Anda — Anda akan membutuhkannya pada langkah terakhir.
Atur Client authentication ke Public key / Private key. Scope okta.* hanya didukung dengan metode autentikasi ini.

Nonaktifkan Proof of possession (DPoP) — fitur ini tidak didukung.

Aplikasi harus dibuat sebagai API Services.

Langkah 2: Membuat dan mendaftarkan pasangan kunci RSA Anda

Gunakan generator kunci Okta

Okta dapat membuat pasangan kunci RSA untuk Anda langsung di Admin Console:

Di Admin Console, buka aplikasi API Services Anda.
Buka tab General dan gulir ke bagian PUBLIC KEYS.
Klik Add Key, lalu pilih Generate new key.
Klik Simpan — Okta membuat pasangan kunci dan menampilkan Private Key (JWK) satu kali.
Segera salin dan simpan JSON kunci privat — kunci ini tidak akan ditampilkan lagi.

Kunci publik otomatis didaftarkan ke aplikasi Anda.

Salin JWK privat sebelum menutup dialog. Tempelkan ke kolom Private Key di Living Security Platform pada langkah terakhir.

Buat kunci Anda sendiri

Okta menggunakan private_key_jwt untuk aplikasi API Services. Anda membuat pasangan kunci RSA, mendaftarkan JWK publik ke Okta, dan memberikan JWK privat ke Living Security Platform. Buat JWK privat menggunakan skrip Node.js berikut (memerlukan Node.js 18+):

const { generateKeyPairSync } = require('crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });

const privateJwk = privateKey.export({ format: 'jwk' });
const publicJwk  = publicKey.export({ format: 'jwk' });

// Assign a kid — must match between private and public JWK
const kid = require('crypto').randomUUID();
privateJwk.kid = kid;
publicJwk.kid  = kid;

console.log('=== PUBLIC JWK (upload to Okta) ===');
console.log(JSON.stringify(publicJwk, null, 2));
console.log('\n=== PRIVATE JWK (paste into the Living Security Platform) ===');
console.log(JSON.stringify(privateJwk));

Daftarkan JWK publik di Okta:

Di Admin Console, buka aplikasi API Services Anda.
Buka tab General dan gulir ke bagian PUBLIC KEYS.
Klik Add Key, tempelkan JSON JWK publik hasil keluaran skrip di atas, lalu klik Simpan.

JWK privat adalah yang Anda tempelkan ke Living Security Platform. JWK ini mencakup seluruh materi kunci (d, p, q, dp, dq, qi) dan kid. Jaga kerahasiaannya.

Langkah 3: Menemukan Okta Domain Anda

Masukkan hanya subdomain tenant Okta Anda — bagian sebelum .okta.com.

Di Admin Console, bilah alamat browser Anda akan menampilkan URL seperti https://dev-12345678-admin.okta.com.
Okta Domain Anda hanyalah subdomain (mis., dev-12345678), bukan dev-12345678.okta.com.
Sebagai alternatif, buka Pengaturan > Account di Admin Console untuk menemukan domain Okta Anda, lalu gunakan bagian subdomainnya.

Langkah 4: Berikan scope API kepada aplikasi Anda

Okta mensyaratkan setidaknya satu scope dalam setiap permintaan token. Sebelum aplikasi Anda dapat meminta scope tertentu, scope tersebut harus diberikan:

Di Admin Console, buka Applications > Applications dan buka aplikasi Anda.
Klik tab Okta API Scopes.
Berikan scope yang dibutuhkan integrasi Anda: okta.users.read dan okta.logs.read.

Daftar lengkap scope yang tersedia ada di referensi Okta Management API.

Langkah 5: Tetapkan peran admin kepada aplikasi Anda

Memberikan scope saja tidak cukup — endpoint Okta Management API (mis. /api/v1/users) secara diam-diam mengembalikan respons 200 [] kosong jika aplikasi Anda tidak memiliki peran admin. Anda harus menetapkan setidaknya Read-Only Administrator:

Di Admin Console, buka Keamanan > Administrators (atau buka Applications > Applications > aplikasi Anda > Admin roles).
Klik Add administrator assignment dan pilih aplikasi API Services Anda.

Tetapkan peran Read-Only Administrator (atau yang lebih tinggi, tergantung pada scope yang Anda butuhkan).
Klik Simpan.

Tanpa peran admin, panggilan API berhasil dengan 200 OK tetapi mengembalikan hasil kosong, dan tidak ada kesalahan 403 yang menunjukkan masalahnya.

Langkah 6: Masukkan kredensial di Living Security Platform

Setelah Anda memiliki ID Klien, Private Key (JWK), Okta Domain, dan Scopes:

Buka formulir tempat Anda perlu melakukan autentikasi dengan Okta (Client Credentials).
Masukkan ID Klien Anda.
Tempelkan Private Key (JWK) Anda — objek JSON lengkap dari skrip di atas (satu baris atau terformat).
Masukkan Okta Domain Anda hanya sebagai subdomain tenant (mis., dev-12345678).
Masukkan Scopes sebagai daftar yang dipisahkan spasi (mis., okta.users.read okta.logs.read).
Kirim formulir, dan Anda akan berhasil terautentikasi.

Sekarang Anda telah terhubung ke Okta (Client Credentials).

Sebagian dokumentasi ini diadaptasi dari Nango, digunakan berdasarkan Elastic License 2.0.

Integrasi