Pelayan Kebenaran Okta

Sediakan pelayan kebenaran Okta tersuai dengan claims, roles dan policy akses yang diperlukan oleh Halo. Ini ialah prasyarat untuk kedua-dua Halo Portal SSO dan Halo API Bearer Authentication.

Prasyarat​

• Organisasi Okta dengan akses pentadbir
• Akses rangkaian daripada deployment Halo anda ke Okta

Cipta pelayan kebenaran​

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

   • Berikan nama yang sesuai. contohnya Glasswall Halo

   • Masukkan nilai audience umum yang akan dikongsi merentas semua klien Halo (Portal dan API). contohnya api://halo

   • Berikan penerangan yang sesuai. contohnya Glasswall Halo Authorization server

   • Setelah disimpan, catat Issuer Metadata URI. Buang /.well-known/oauth-authorization-server daripada hujung URI. contohnya.

     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"
     

Nota: Audience api://halo dikongsi merentas semua klien Halo. Kedua-dua pengesahan Portal SSO dan API Bearer mengesahkan token terhadap audience ini. Ini membolehkan satu authorization server digunakan untuk kedua-dua kes penggunaan.

Tambah custom scope untuk akses Halo API​

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

Nota: Scope OIDC (contohnya openid, profile, email) adalah untuk konteks pengguna sahaja dan tidak boleh digunakan dengan aliran Client Credentials. Custom scope diperlukan untuk akses API machine-to-machine.

Sediakan claims​

3. Konfigurasikan claims yang diperlukan oleh perkhidmatan Halo. Navigasi ke 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

Takrifkan peranan​

Nota: Halo menggunakan dua tuntutan peranan yang berasingan:

• roles: digunakan oleh Portal (melalui Portal-Access) untuk mengawal akses UI
• role: digunakan oleh perkhidmatan API-Access untuk kebenaran endpoint

Jika tuntutan peranan tidak dikonfigurasikan, Portal akan lalai kepada peranan baca sahaja dan API akan lalai kepada peranan User. Lihat Pemetaan Peranan Portal kepada Tindakan dan Pemetaan Peranan API kepada Tindakan untuk butiran tentang perkara yang boleh diakses oleh setiap peranan.

4. Halo mengenali dua nilai peranan: User dan Admin (tidak peka huruf besar/kecil). Okta tidak mempunyai cara asli untuk mentakrifkan peranan dalam Authorization servers. Tuntutan peranan perlu ditambah untuk menghantar peranan pengguna/klien dalam access token.

Peranan SSO Portal (roles claim)​

Tuntutan ini digunakan oleh Portal untuk menentukan halaman dan ciri yang tersedia kepada pengguna. Kami mengesyorkan penggunaan nama kumpulan khusus Halo berbanding kumpulan generik User atau Admin, yang mungkin bercanggah dengan aplikasi lain dalam organisasi Okta anda.

1. Cipta kumpulan dalam Okta. Navigasi ke Directory -> Groups dan cipta:

   • Halo_User
   • Halo_Admin

2. Tetapkan pengguna kepada kumpulan yang sesuai.

3. Pergi ke tab Claims pelayan kebenaran dan cipta tuntutan roles yang menterjemahkan nama kumpulan kepada nilai peranan 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

   

Nota: Fungsi isMemberOfGroupName() hanya berfungsi dalam aliran konteks pengguna (contohnya, Authorization Code). Ia tidak terpakai kepada aliran Client Credentials (machine-to-machine).

Peranan API (role claim)​

Tuntutan ini digunakan oleh perkhidmatan API-Access untuk membenarkan operasi. Memandangkan klien API menggunakan aliran Client Credentials (tiada konteks pengguna), ungkapan keahlian kumpulan tidak terpakai. Sebaliknya, petakan client_id kepada nilai peranan.

4. Pergi ke tab Claims pelayan kebenaran dan cipta tuntutan 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

   

Nota: Gantikan <your-api-client-id> dengan client_id aplikasi API Services anda. Tambahkan syarat tambahan untuk berbilang klien API, contohnya:

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

Langkah seterusnya​

Dengan pelayan kebenaran telah dikonfigurasikan, teruskan untuk menyediakan satu atau kedua-dua yang berikut:

• Halo Portal SSO - konfigurasikan Okta sebagai penyedia identiti untuk Halo Portal
• Halo API Bearer Authentication - konfigurasikan pengesahan token Bearer untuk Halo API

Setiap panduan merangkumi konfigurasi policy akses pada authorization server ini untuk klien masing-masing.