Máy chủ ủy quyền Okta

Thiết lập một máy chủ ủy quyền Okta tùy chỉnh với các claim, vai trò và policy truy cập mà Halo yêu cầu. Đây là điều kiện tiên quyết cho cả Halo Portal SSO và Halo API Bearer Authentication.

Điều kiện tiên quyết​

• Một tổ chức Okta có quyền truy cập quản trị viên
• Quyền truy cập mạng từ triển khai Halo của bạn tới Okta

Tạo máy chủ ủy quyền​

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

   • Đặt tên phù hợp. Ví dụ: Glasswall Halo

   • Nhập một giá trị audience chung sẽ được chia sẻ trên tất cả ứng dụng khách Halo (Portal và API). Ví dụ: api://halo

   • Nhập mô tả phù hợp. Ví dụ: Glasswall Halo Authorization server

   • Sau khi lưu, hãy ghi lại Issuer Metadata URI. Xóa /.well-known/oauth-authorization-server ở cuối URI. Ví dụ:

     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"
     

Lưu ý: audience api://halo được dùng chung cho tất cả client của Halo. Cả xác thực Portal SSO và API Bearer đều xác thực token dựa trên audience này. Điều này cho phép một authorization server duy nhất phục vụ cả hai trường hợp sử dụng.

Thêm scope tùy chỉnh cho quyền truy cập Halo API​

2. Navigate to the Scopes tab on the authorization server and add a new scope:
   • Tên: halo.api
   • Cụm từ hiển thị: Halo API
   • Mô tả: Access to Halo API
   • Chọn Set as a default scope

Lưu ý: Các scope OIDC (ví dụ: openid, profile, email) chỉ dành cho ngữ cảnh người dùng và không thể dùng với luồng Client Credentials. Cần có scope tùy chỉnh cho quyền truy cập API giữa máy với máy.

Thiết lập claims​

3. Cấu hình các claims cần thiết cho các dịch vụ Halo. Điều hướng đến tab Claims trên authorization server.

   • Full name:
     • Tên: name
     • Bao gồm trong loại token: Access Token
     • Loại giá trị: Expression
     • Giá trị: user.firstName + " " + user.lastName
     • Bao gồm trong: Any scope
   • Family name:
     • Tên: family_name
     • Bao gồm trong loại token: Access Token
     • Loại giá trị: Expression
     • Giá trị: user.lastName
     • Bao gồm trong: Any scope
   • Given name:
     • Tên: given_name
     • Bao gồm trong loại token: Access Token
     • Loại giá trị: Expression
     • Giá trị: user.firstName
     • Bao gồm trong: Any scope
   • Email ID:
     • Tên: unique_name
     • Bao gồm trong loại token: Access Token
     • Loại giá trị: Expression
     • Giá trị: user.email
     • Bao gồm trong: Any scope

Định nghĩa vai trò​

Lưu ý: Halo sử dụng hai role claim riêng biệt:

• roles: được Portal sử dụng (thông qua Portal-Access) để kiểm soát quyền truy cập UI
• role: được dịch vụ API-Access sử dụng để phân quyền endpoint

Nếu các role claim chưa được cấu hình, Portal mặc định dùng vai trò chỉ đọc và API mặc định dùng vai trò User. Xem Portal Roles to Action Mapping và API Roles to Action Mapping để biết chi tiết về những gì mỗi vai trò có thể truy cập.

4. Halo nhận diện hai giá trị vai trò: User và Admin (không phân biệt chữ hoa chữ thường). Okta không có cách gốc để định nghĩa vai trò trong Authorization servers. Cần thêm role claim để truyền vai trò người dùng/ứng dụng khách trong access token.

Vai trò SSO của Portal (claim roles)​

Claim này được Portal sử dụng để xác định những trang và tính năng nào khả dụng cho người dùng. Chúng tôi khuyến nghị sử dụng tên nhóm dành riêng cho Halo thay vì các nhóm chung chung như User hoặc Admin, vì chúng có thể xung đột với các ứng dụng khác trong tổ chức Okta của bạn.

1. Tạo các nhóm trong Okta. Điều hướng đến Directory -> Groups và tạo:

   • Halo_User
   • Halo_Admin

2. Gán người dùng vào nhóm phù hợp.

3. Đi tới tab Claims của authorization server và tạo một claim roles để chuyển đổi tên nhóm thành các giá trị vai trò của Halo:

   • Tên: roles
   • Bao gồm trong loại token: Access Token
   • Loại giá trị: Expression
   • Value:

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

   • Bao gồm trong: Any scope

   

Lưu ý: Hàm isMemberOfGroupName() chỉ hoạt động trong các luồng theo ngữ cảnh người dùng (ví dụ: Authorization Code). Hàm này không áp dụng cho các luồng Client Credentials (machine-to-machine).

Vai trò API (role claim)​

Claim này được dịch vụ API-Access sử dụng để cấp quyền cho các thao tác. Vì các API client sử dụng luồng Client Credentials (không có ngữ cảnh người dùng), các biểu thức thành viên nhóm không áp dụng. Thay vào đó, ánh xạ client_id tới một giá trị vai trò.

4. Đi tới tab Claims của authorization server và tạo một claim role:

   • Tên: role
   • Bao gồm trong loại token: Access Token
   • Loại giá trị: Expression
   • Value:

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

   • Bao gồm trong: Any scope

   

Lưu ý: Thay <your-api-client-id> bằng client_id của ứng dụng API Services của bạn. Thêm các điều kiện bổ sung cho nhiều API client, ví dụ:

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

Các bước tiếp theo​

Sau khi authorization server được cấu hình, hãy tiếp tục thiết lập một hoặc cả hai mục sau:

• Halo Portal SSO - cấu hình Okta làm nhà cung cấp danh tính cho Halo Portal
• Halo API Bearer Authentication - cấu hình xác thực Bearer token cho Halo API

Mỗi hướng dẫn bao gồm việc cấu hình một policy truy cập trên authorization server này cho client tương ứng của nó.