Autentikasi Bearer API Okta

Autentikasi akses terprogram ke Halo API menggunakan token Bearer OAuth 2.0 yang diterbitkan oleh Okta.

Ikhtisar​

Halo mengekspos REST API melalui layanan API-Access. Semua permintaan API harus menyertakan token Bearer yang valid di header Authorization. Token diperoleh dari Okta menggunakan alur OAuth 2.0 Client Credentials (machine-to-machine).

Panduan ini memandu Anda melalui konfigurasi Okta sebagai Identity Provider untuk layanan Halo API-Access, lalu menguji integrasi dengan autentikasi token Bearer.

Prasyarat​

• Deployment Halo yang sedang berjalan dengan layanan API-Access yang dikonfigurasi
• Organisasi Okta dengan akses admin
• Server otorisasi Okta yang dikonfigurasi untuk Halo (lihat Okta Authorization Server)
• Akses jaringan dari klien API ke Okta dan endpoint API Halo

Penyiapan​

Daftarkan klien API di Okta​

Buat aplikasi machine-to-machine​

1. Masuk ke Okta Admin Console.
2. Buka Applications -> Applications -> Create App Integration -> API Services.

3. Berikan nama integrasi App yang sesuai: misalnya Glasswall Halo API

Nonaktifkan DPoP (proof of possession)​

4. Buka tab General aplikasi -> bagian General Settings -> klik Edit.
5. Di bawah Proof of possession, hapus centang Require Demonstrating Proof of Possession (DPoP) header in token requests.
6. Simpan.

Catatan: Okta mengaktifkan DPoP secara default untuk aplikasi API Services. DPoP mengikat token ke kunci kriptografis klien, sehingga mencegah serangan replay token. Namun, layanan Halo API-Access saat ini belum mendukung validasi token DPoP, jadi fitur ini harus dinonaktifkan agar autentikasi token Bearer berfungsi.

Konfigurasikan kredensial klien​

7. Catat Client ID dan buat Client Secret.

   export CLIENT_ID="<your-client-id>"
   export CLIENT_SECRET="<your-client-secret>"
   

Catatan Keamanan: Simpan rahasia klien dengan aman menggunakan secrets manager (misalnya, Azure KeyVault). Jangan pernah melakukan commit rahasia ke source control.

Konfigurasikan peran (opsional)​

8. Jika klien API Anda memerlukan akses tulis ke endpoint manajemen lisensi, pastikan klaim role dikonfigurasi pada authorization server dengan nilai Admin yang dipetakan ke klien Anda (lihat API Roles).

Catatan: Tanpa klaim role, API secara default menggunakan peran User. Lihat API Roles to Action Mapping untuk detail tentang akses yang dimiliki setiap peran.

Catat issuer URI dan audience​

9. Dari authorization server yang dikonfigurasi pada langkah prasyarat:

   export OKTA_ISSUER_URI="https://<your-okta-domain>/oauth2/<authorization-server-id>"
   export VALID_AUDIENCE="api://halo"
   

Tambahkan access policy untuk klien API​

10. Buka tab Access Policies pada authorization server (Security -> API -> pilih authorization server Anda -> Access Policies).
11. Add a new access policy:
    • Nama: mis. API Client Access
    • Deskripsi: mis. Access policy for Halo API clients
    • Tetapkan ke: klien API Services yang dibuat di atas (cari berdasarkan nama aplikasi glasswall-halo-api dari langkah 2)
12. Add a rule:
    • Nama: mis. Allow API Clients
    • Jenis grant: Client Credentials
    • Biarkan pengaturan lainnya tetap default atau sesuaikan masa berlaku token sesuai kebutuhan.

Catatan: Access policy untuk grant Client Credentials mengontrol klien mana (berdasarkan client_id) yang dapat meminta token. Keanggotaan grup tidak berlaku karena tidak ada konteks pengguna dalam alur ini. Amankan akses ke API dengan membatasi siapa yang memiliki client_id dan client_secret melalui secrets manager Anda.

Konfigurasikan layanan API-Access untuk Okta​

Helm chart cdrplatform-api-access harus dikonfigurasi untuk memvalidasi token Bearer yang diterbitkan oleh authorization server Okta Anda. Chart ini mengekspos pengaturan autentikasi di bawah kunci values configuration.

Deploy konfigurasi​

Catatan: Authority dan ValidIssuer keduanya harus diatur ke URI issuer Okta. Layanan API-Access menggunakan Authority untuk menemukan JWKS (JSON Web Key Set) guna validasi tanda tangan token, dan ValidIssuer untuk memverifikasi klaim iss dalam token.

export HALO_DOMAIN=<your-halo-domain>
helm upgrade --install cdrplatform-api-access cdrplatform-api-access --reuse-values \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__Authority="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="${OKTA_ISSUER_URI:?}" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="${VALID_AUDIENCE:?}" \
  --set strategy.type="Recreate" \
  --set ingress.enabled=true \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain="${HALO_DOMAIN:?}" \
  --atomic

Beberapa audience (opsional)​

Jika beberapa klien API atau aplikasi perlu mengakses Halo API dengan audience yang berbeda, tambahkan entri ValidAudiences tambahan:

  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://halo-api" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__1="<second-client-id>" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__2="<third-client-id>"

Penggunaan Halo API​

Dapatkan bearer token​

Alur Client Credentials (machine-to-machine)​

Gunakan alur ini untuk sistem otomatis, pipeline CI/CD, dan integrasi service-to-service ketika tidak diperlukan interaksi pengguna.

export TOKEN_ENDPOINT="${OKTA_ISSUER_URI}/v1/token"

Minta token:

curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api"

Contoh respons:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "halo.api"
}

Ekstrak token:

export ACCESS_TOKEN=$(curl -s -X POST "${TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=halo.api" | jq -r '.access_token')

Autentikasi permintaan API​

Sertakan token Bearer di header Authorization pada setiap permintaan API:

export HALO_API_URL="https://<your-halo-domain>"

Verifikasi autentikasi​

Uji dengan endpoint yang dilindungi. Permintaan tanpa token harus mengembalikan 401, dan permintaan dengan token yang valid harus mengembalikan 200:

# Without token - expect 401
curl -s -o /dev/null -w "%{http_code}" \
  "${HALO_API_URL}/api/v1/policies"

# With token - expect 200
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "${HALO_API_URL}/api/v1/policies"

Contoh: Kirim file untuk diproses​

curl -s -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "file=@/path/to/document.pdf" \
  "${HALO_API_URL}/api/v1/rebuild/file" \
  --output rebuilt_document.pdf

Pemecahan masalah​