เซิร์ฟเวอร์การให้สิทธิ์ Okta

ตั้งค่าเซิร์ฟเวอร์การให้สิทธิ์ Okta แบบกำหนดเองพร้อม claims, roles และ access policies ที่ Halo ต้องใช้ นี่เป็นข้อกำหนดเบื้องต้นสำหรับทั้ง Halo Portal SSO และ Halo API Bearer Authentication.

ข้อกำหนดเบื้องต้น​

• องค์กร Okta ที่มีสิทธิ์เข้าถึงระดับผู้ดูแลระบบ
• การเข้าถึงเครือข่ายจากการปรับใช้ Halo ของคุณไปยัง Okta

สร้าง authorization server​

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

   • ตั้งชื่อให้เหมาะสม เช่น Glasswall Halo

   • ป้อนค่า audience กลางที่จะใช้ร่วมกันในทุกไคลเอนต์ Halo (Portal และ API) เช่น api://halo

   • ระบุคำอธิบายที่เหมาะสม เช่น Glasswall Halo Authorization server

   • เมื่อบันทึกแล้ว ให้จด Issuer Metadata URI ไว้ ลบ /.well-known/oauth-authorization-server ออกจากท้าย URI เช่น

     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"
     

หมายเหตุ: audience api://halo ใช้ร่วมกันในทุก Halo client ทั้งการยืนยันตัวตนแบบ Portal SSO และ API Bearer จะตรวจสอบ token กับ audience นี้ ซึ่งทำให้ authorization server เดียวสามารถรองรับได้ทั้งสองกรณีการใช้งาน

เพิ่ม custom scope สำหรับการเข้าถึง Halo API​

2. Navigate to the Scopes tab on the authorization server and add a new scope:
   • ชื่อ: halo.api
   • วลีที่แสดง: Halo API
   • คำอธิบาย: Access to Halo API
   • เลือก Set as a default scope

หมายเหตุ: OIDC scope (เช่น openid, profile, email) ใช้ได้เฉพาะในบริบทของผู้ใช้เท่านั้น และไม่สามารถใช้กับ Client Credentials flow ได้ จำเป็นต้องมี custom scope สำหรับการเข้าถึง API แบบ machine-to-machine

ตั้งค่า claims​

3. กำหนดค่า claims ที่บริการ Halo ต้องใช้ ไปที่แท็บ Claims บน authorization server

   • Full name:
     • ชื่อ: name
     • รวมในประเภท token: Access Token
     • ประเภทค่า: Expression
     • ค่า: user.firstName + " " + user.lastName
     • รวมใน: Any scope
   • Family name:
     • ชื่อ: family_name
     • รวมในประเภท token: Access Token
     • ประเภทค่า: Expression
     • ค่า: user.lastName
     • รวมใน: Any scope
   • Given name:
     • ชื่อ: given_name
     • รวมในประเภท token: Access Token
     • ประเภทค่า: Expression
     • ค่า: user.firstName
     • รวมใน: Any scope
   • Email ID:
     • ชื่อ: unique_name
     • รวมในประเภท token: Access Token
     • ประเภทค่า: Expression
     • ค่า: user.email
     • รวมใน: Any scope

กำหนดบทบาท​

หมายเหตุ: Halo ใช้ role claim แยกกันสองรายการ:

• roles: ใช้โดย Portal (ผ่าน Portal-Access) เพื่อควบคุมการเข้าถึง UI
• role: ใช้โดยบริการ API-Access สำหรับการกำหนดสิทธิ์ของ endpoint

หากไม่ได้กำหนดค่า role claim ไว้ Portal จะใช้บทบาทแบบอ่านอย่างเดียวเป็นค่าเริ่มต้น และ API จะใช้บทบาท User เป็นค่าเริ่มต้น ดู Portal Roles to Action Mapping และ API Roles to Action Mapping สำหรับรายละเอียดเกี่ยวกับสิ่งที่แต่ละบทบาทสามารถเข้าถึงได้

4. Halo รู้จักค่าบทบาทสองค่า: User และ Admin (ไม่สนใจตัวพิมพ์เล็ก-ใหญ่) Okta ไม่มีวิธีแบบเนทีฟในการกำหนดบทบาทใน Authorization servers จำเป็นต้องเพิ่ม role claim เพื่อส่งบทบาทของผู้ใช้/ไคลเอนต์ใน access token

บทบาท Portal SSO (roles claim)​

claim นี้ถูกใช้โดย Portal เพื่อกำหนดว่าหน้าและฟีเจอร์ใดบ้างที่พร้อมใช้งานสำหรับผู้ใช้ เราแนะนำให้ใช้ชื่อกลุ่มที่เฉพาะเจาะจงสำหรับ Halo แทนกลุ่มทั่วไปอย่าง User หรือ Admin ซึ่งอาจขัดแย้งกับแอปพลิเคชันอื่นในองค์กร Okta ของคุณ

1. สร้างกลุ่มใน Okta ไปที่ Directory -> Groups แล้วสร้าง:

   • Halo_User
   • Halo_Admin

2. กำหนดผู้ใช้ให้กับกลุ่มที่เหมาะสม

3. ไปที่แท็บ Claims ของ authorization server และสร้าง claim roles ที่แปลงชื่อกลุ่มเป็นค่า role ของ Halo:

   • ชื่อ: roles
   • รวมในประเภท token: Access Token
   • ประเภทค่า: Expression
   • Value:

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

   • รวมใน: Any scope

   

หมายเหตุ: ฟังก์ชัน isMemberOfGroupName() ใช้งานได้เฉพาะใน user-context flows (เช่น Authorization Code) เท่านั้น โดยไม่ใช้กับ Client Credentials (machine-to-machine) flows

role ของ API (role claim)​

claim นี้ถูกใช้โดยบริการ API-Access เพื่ออนุญาตการดำเนินการต่างๆ เนื่องจาก API clients ใช้ Client Credentials flow (ไม่มี user context) นิพจน์การเป็นสมาชิกกลุ่มจึงใช้ไม่ได้ แต่ให้แมป client_id ไปเป็นค่า role แทน

4. ไปที่แท็บ Claims ของ authorization server และสร้าง claim role:

   • ชื่อ: role
   • รวมในประเภท token: Access Token
   • ประเภทค่า: Expression
   • Value:

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

   • รวมใน: Any scope

   

หมายเหตุ: แทนที่ <your-api-client-id> ด้วย client_id ของแอปพลิเคชัน API Services ของคุณ และเพิ่มเงื่อนไขเพิ่มเติมสำหรับ API clients หลายรายการ เช่น:

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

ขั้นตอนถัดไป​

เมื่อกำหนดค่า authorization server แล้ว ให้ดำเนินการตั้งค่าอย่างใดอย่างหนึ่งหรือทั้งสองอย่างต่อไปนี้:

• Halo Portal SSO - กำหนดค่า Okta เป็นผู้ให้บริการข้อมูลประจำตัวสำหรับ Halo Portal
• Halo API Bearer Authentication - กำหนดค่าการยืนยันตัวตนด้วย Bearer token สำหรับ Halo API

คู่มือแต่ละฉบับรวมถึงการกำหนดค่า access policy บน authorization server นี้สำหรับ client ที่เกี่ยวข้อง