Pengesahan Bearer API Okta

Sahkan akses berprogram ke Halo API menggunakan token OAuth 2.0 Bearer yang dikeluarkan oleh Okta.

Gambaran keseluruhan​

Halo mendedahkan REST API melalui perkhidmatan API-Access. Semua permintaan API mesti menyertakan token Bearer yang sah dalam pengepala Authorization. Token diperoleh daripada Okta menggunakan aliran OAuth 2.0 Client Credentials (machine-to-machine).

Panduan ini menerangkan langkah demi langkah untuk mengkonfigurasi Okta sebagai Identity Provider bagi perkhidmatan Halo API-Access, kemudian menguji integrasi dengan pengesahan token Bearer.

Prasyarat​

• Deployment Halo yang sedang berjalan dengan perkhidmatan API-Access dikonfigurasi
• Organisasi Okta dengan akses pentadbir
• Pelayan kebenaran Okta dikonfigurasi untuk Halo (lihat Okta Authorization Server)
• Akses rangkaian daripada klien API ke kedua-dua Okta dan endpoint API Halo

Persediaan​

Daftarkan klien API dalam Okta​

Cipta aplikasi machine-to-machine​

1. Log masuk ke Okta Admin Console.
2. Navigasi ke Applications -> Applications -> Create App Integration -> API Services.

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

Nyahdayakan DPoP (bukti pemilikan)​

4. Navigasi ke tab General aplikasi -> bahagian General Settings -> klik Edit.
5. Di bawah Proof of possession, nyahtanda Require Demonstrating Proof of Possession (DPoP) header in token requests.
6. Simpan.

Nota: Okta mendayakan DPoP secara lalai untuk aplikasi API Services. DPoP mengikat token kepada kunci kriptografi klien, sekali gus menghalang serangan ulangan token. Walau bagaimanapun, perkhidmatan Halo API-Access pada masa ini tidak menyokong pengesahan token DPoP, jadi ini mesti dinyahdayakan agar pengesahan token Bearer berfungsi.

Konfigurasikan kelayakan klien​

7. Catat Client ID dan jana Client Secret.

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

Nota Keselamatan: Simpan rahsia klien dengan selamat menggunakan pengurus rahsia (contohnya, Azure KeyVault). Jangan sekali-kali commit rahsia ke kawalan sumber.

Konfigurasikan peranan (pilihan)​

8. Jika klien API anda memerlukan akses tulis ke endpoint pengurusan lesen, pastikan tuntutan role dikonfigurasikan pada pelayan kebenaran dengan nilai Admin dipetakan kepada klien anda (lihat API Roles).

Nota: Tanpa tuntutan role, API akan menggunakan peranan User secara lalai. Lihat API Roles to Action Mapping untuk butiran tentang perkara yang boleh diakses oleh setiap peranan.

Catat issuer URI dan audience​

9. Daripada pelayan kebenaran yang dikonfigurasikan dalam langkah prasyarat:

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

Tambah policy akses untuk klien API​

10. Navigasi ke tab Access Policies pelayan kebenaran (Security -> API -> pilih pelayan kebenaran anda -> Access Policies).
11. Add a new access policy:
    • Nama: contohnya API Client Access
    • Penerangan: contohnya Access policy for Halo API clients
    • Tetapkan kepada: klien API Services yang dibuat di atas (cari mengikut nama aplikasi glasswall-halo-api daripada langkah 2)
12. Add a rule:
    • Nama: contohnya Allow API Clients
    • Jenis grant: Client Credentials
    • Biarkan tetapan lain pada nilai lalai atau laraskan jangka hayat token mengikut keperluan.

Nota: policy akses untuk grant Client Credentials mengawal klien (melalui client_id) yang boleh meminta token. Keahlian kumpulan tidak terpakai kerana tiada konteks pengguna dalam aliran ini. Lindungi akses kepada API dengan mengehadkan siapa yang mempunyai client_id dan client_secret melalui pengurus rahsia anda.

Konfigurasikan perkhidmatan API-Access untuk Okta​

Carta Helm cdrplatform-api-access mesti dikonfigurasikan untuk mengesahkan token Bearer yang dikeluarkan oleh pelayan kebenaran Okta anda. Carta ini mendedahkan tetapan pengesahan di bawah kunci nilai configuration.

Gunakan konfigurasi​

Nota: Authority dan ValidIssuer mesti kedua-duanya ditetapkan kepada URI pengeluar Okta. Perkhidmatan API-Access menggunakan Authority untuk menemui JWKS (JSON Web Key Set) bagi pengesahan tandatangan token, dan ValidIssuer untuk mengesahkan tuntutan 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

Berbilang audience (pilihan)​

Jika berbilang klien API atau aplikasi perlu mengakses Halo API dengan audience yang berbeza, 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 token bearer​

Aliran Client Credentials (machine-to-machine)​

Gunakan aliran ini untuk sistem automatik, pipeline CI/CD dan integrasi service-to-service yang tidak memerlukan 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')

Sahkan permintaan API​

Sertakan token Bearer dalam pengepala Authorization bagi setiap permintaan API:

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

Sahkan pengesahan​

Uji dengan endpoint yang dilindungi. Permintaan tanpa token sepatutnya mengembalikan 401, dan permintaan dengan token yang sah sepatutnya 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: Hantar fail 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

Penyelesaian masalah​