Server Otorisasi Okta

Siapkan server otorisasi Okta kustom dengan claim, role, dan policy akses yang diperlukan oleh Halo. Ini adalah prasyarat untuk Halo Portal SSO dan Halo API Bearer Authentication.

Prasyarat​

• Organisasi Okta dengan akses admin
• Akses jaringan dari deployment Halo Anda ke Okta

Buat server otorisasi​

1. Navigate to Security -> API and create a new Authorization server.

   • Berikan nama yang sesuai. mis. Glasswall Halo

   • Masukkan nilai audience umum yang akan dibagikan di semua klien Halo (Portal dan API). mis. api://halo

   • Berikan deskripsi yang sesuai. mis. Glasswall Halo Authorization server

   • Setelah disimpan, catat Issuer Metadata URI. Hapus /.well-known/oauth-authorization-server dari akhir URI. mis.

     export ORIGINAL_ISSUER_URI=https://your-org.okta.com/oauth2/aus1234567890abcdef/.well-known/oauth-authorization-server
     export OKTA_ISSUER_URI=https://your-org.okta.com/oauth2/aus1234567890abcdef
     export VALID_AUDIENCE="api://halo"
     

Catatan: Audience api://halo digunakan bersama di semua klien Halo. Baik autentikasi Portal SSO maupun API Bearer memvalidasi token terhadap audience ini. Ini memungkinkan satu authorization server melayani kedua kasus penggunaan.

Tambahkan scope kustom untuk akses Halo API​

2. Navigate to the Scopes tab on the authorization server and add a new scope:
   • Nama: halo.api
   • Frasa Tampilan: Halo API
   • Deskripsi: Access to Halo API
   • Centang Set as a default scope

Catatan: Scope OIDC (mis. openid, profile, email) hanya untuk konteks pengguna dan tidak dapat digunakan dengan flow Client Credentials. Scope kustom diperlukan untuk akses API machine-to-machine.

Siapkan claims​

3. Konfigurasikan claims yang diperlukan oleh layanan Halo. Buka tab Claims pada authorization server.

   • Full name:
     • Nama: name
     • Sertakan dalam jenis token: Access Token
     • Jenis nilai: Expression
     • Nilai: user.firstName + " " + user.lastName
     • Sertakan dalam: Any scope
   • Family name:
     • Nama: family_name
     • Sertakan dalam jenis token: Access Token
     • Jenis nilai: Expression
     • Nilai: user.lastName
     • Sertakan dalam: Any scope
   • Given name:
     • Nama: given_name
     • Sertakan dalam jenis token: Access Token
     • Jenis nilai: Expression
     • Nilai: user.firstName
     • Sertakan dalam: Any scope
   • Email ID:
     • Nama: unique_name
     • Sertakan dalam jenis token: Access Token
     • Jenis nilai: Expression
     • Nilai: user.email
     • Sertakan dalam: Any scope

Tentukan peran​

Catatan: Halo menggunakan dua klaim peran yang terpisah:

• roles: digunakan oleh Portal (melalui Portal-Access) untuk mengontrol akses UI
• role: digunakan oleh layanan API-Access untuk otorisasi endpoint

Jika klaim peran tidak dikonfigurasi, Portal secara default menggunakan peran hanya-baca dan API secara default menggunakan peran User. Lihat Pemetaan Peran Portal ke Tindakan dan Pemetaan Peran API ke Tindakan untuk detail tentang apa yang dapat diakses oleh setiap peran.

4. Halo mengenali dua nilai peran: User dan Admin (tidak peka huruf besar/kecil). Okta tidak memiliki cara bawaan untuk mendefinisikan peran di Authorization servers. Klaim peran perlu ditambahkan untuk meneruskan peran pengguna/klien dalam access token.

Peran SSO Portal (roles claim)​

Klaim ini digunakan oleh Portal untuk menentukan halaman dan fitur mana yang tersedia bagi pengguna. Kami merekomendasikan penggunaan nama grup khusus Halo daripada grup generik User atau Admin, yang mungkin bertentangan dengan aplikasi lain di organisasi Okta Anda.

1. Buat grup di Okta. Buka Directory -> Groups lalu buat:

   • Halo_User
   • Halo_Admin

2. Tetapkan pengguna ke grup yang sesuai.

3. Buka tab Claims pada authorization server dan buat claim roles yang menerjemahkan nama grup menjadi nilai peran Halo:

   • Nama: roles
   • Sertakan dalam jenis token: Access Token
   • Jenis nilai: Expression
   • Value:

     isMemberOfGroupName("Halo_Admin") ? "Admin" : isMemberOfGroupName("Halo_User") ? "User" : ""
     

   • Sertakan dalam: Any scope

   

Catatan: Fungsi isMemberOfGroupName() hanya berfungsi dalam flow konteks pengguna (misalnya, Authorization Code). Fungsi ini tidak berlaku untuk flow Client Credentials (machine-to-machine).

Peran API (role claim)​

Claim ini digunakan oleh layanan API-Access untuk mengotorisasi operasi. Karena klien API menggunakan alur Client Credentials (tanpa konteks pengguna), ekspresi keanggotaan grup tidak berlaku. Sebagai gantinya, petakan client_id ke nilai peran.

4. Buka tab Claims pada authorization server dan buat claim role:

   • Nama: role
   • Sertakan dalam jenis token: Access Token
   • Jenis nilai: Expression
   • Value:

     (app.clientId == "<your-api-client-id>") ? "Admin" : "User"
     

   • Sertakan dalam: Any scope

   

Catatan: Ganti <your-api-client-id> dengan client_id dari aplikasi API Services Anda. Tambahkan kondisi tambahan untuk beberapa klien API, misalnya:

(app.clientId == "<client-1>") ? "Admin" : (app.clientId == "<client-2>") ? "Admin" : "User"

Langkah berikutnya​

Setelah authorization server dikonfigurasi, lanjutkan untuk menyiapkan salah satu atau keduanya dari:

• Halo Portal SSO - konfigurasikan Okta sebagai penyedia identitas untuk Halo Portal
• Halo API Bearer Authentication - konfigurasikan autentikasi token Bearer untuk Halo API

Setiap panduan mencakup konfigurasi access policy pada authorization server ini untuk klien terkait masing-masing.