Tích hợp SSO Keycloak

Tổng quan

Hướng dẫn này cung cấp các bước chi tiết để tích hợp Keycloak Single Sign-On (SSO) với nền tảng Glasswall Halo trong môi trường on-premises ngoại tuyến (air-gapped).

Hướng dẫn này giả định rằng bạn đã triển khai nền tảng Halo Single Node (ví dụ: trên VM thông qua Proxmox hoặc ESXi) và hiện muốn bật SSO dựa trên OIDC bằng Keycloak.

Bạn sẽ tìm hiểu cách:

Thiết lập máy chủ Keycloak với HTTPS trong môi trường ngoại tuyến (sử dụng image container được nạp sẵn hoặc cài đặt VM thủ công).
Nhập và tùy chỉnh cấu hình Keycloak glasswall-realm.json được cung cấp.
Cấu hình chứng chỉ TLS và phân giải DNS/host cho cả Keycloak và Halo.
Deploy the Halo portal and related services:
- cdrplatform-portal
- cdrplatform-portalaccess
- cdrplatform-api-access

Hướng dẫn tích hợp SSO Keycloak của Glasswall Halo

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

Yêu cầu môi trường

Thiết lập này dành cho các môi trường air-gapped hoặc on-premises được kiểm soát nghiêm ngặt.
Cụm Halo Single Node phải được triển khai sẵn.
Phải có cơ chế phân giải DNS nội bộ, thông qua máy chủ DNS cục bộ hoặc cấu hình thủ công bằng các mục trong /etc/hosts.
Keycloak phải được cài đặt cục bộ trên máy chủ hoặc máy ảo. → Tài liệu & cài đặt Keycloak

Tài nguyên bắt buộc

Một tệp realm được cấu hình sẵn (glasswall-realm.json), do Glasswall Support cung cấp.
Quyền truy cập cục bộ vào các biểu đồ Helm của Halo để triển khai trong cụm Single Node Halo.

Cấu hình DNS/hosts

Đảm bảo hostname cho máy chủ Keycloak của bạn có thể được phân giải bởi cả máy khách và các thành phần nền tảng Halo.

Có DNS nội bộ: tạo bản ghi A cho keycloak.dev.local trỏ tới địa chỉ IP của máy chủ Keycloak.
Không có DNS nội bộ: thêm mục sau vào tệp hosts trên mỗi máy cần truy cập:

Bước 1 - Cấu hình Keycloak cho SSO của Glasswall Halo

Glasswall cung cấp một cấu hình realm Keycloak (dưới dạng tệp JSON) xác định realm, client, role và scope cần thiết cho SSO của Halo.

Bạn có thể nhập cấu hình này để tránh thiết lập thủ công. Trong thiết lập ngoại tuyến, hãy thực hiện việc này qua Keycloak Admin UI.

1.1 - Nhập cấu hình realm Glasswall

A. Lấy bản xuất realm: bạn phải có một tệp tên là glasswall-realm.json. Tệp này chứa các cài đặt realm cho SSO của Halo.

Tóm tắt realm Glasswall

Realm Glasswall bao gồm các mục được cấu hình sẵn sau đây:

ID Realm: Glasswall
Client
- Halo-portal-client
- Halo-API-access
- Halo-portal-access
Vai trò chính
- Cấp realm: admin, user
- Cấp client: các vai trò quản trị viên và người dùng của client Halo.
- Phạm vi client (được cấu hình sẵn với mapper):
- Portaluserscope: các claim cần thiết (roles, email) cho token.
Thời hạn token
- Thời gian chờ phiên SSO khi không hoạt động: 30 phút
Xác thực: tên người dùng/mật khẩu tiêu chuẩn.

B. Đăng nhập vào Keycloak Admin

Sử dụng trình duyệt web, truy cập Keycloak Admin Console tại https://<KEYCLOAK_HOST>:8443/ và đăng nhập bằng tài khoản quản trị viên master.

01_Keycloak

C. Nhập realm.

Trong bảng điều khiển quản trị, chọn danh sách thả xuống hiện đang hiển thị "Master" và nhấp vào Create realm.

02_Keycloak

Từ màn hình Create realm, chọn Import và tải lên tệp glasswall-realm.json.

03_Keycloak

Keycloak will parse the file and populate the realm name (e.g.,glasswall).
- Xác nhận việc nhập.

04_Keycloak

D. Xác minh cài đặt realm

After import, review key settings and ensure:
- Tên realm là glasswall.
- Realm đã được bật.
- Yêu cầu SSL: có thể được đặt thành external.
- Clients should include:
  - halo-portal-client
  - halo-portal-access
  - halo-api-access

05_Keycloak

1.2 Tùy chỉnh cài đặt client (tên máy chủ và URI chuyển hướng)

Tiếp theo, đối với từng client của Halo, hãy cập nhật cấu hình để phù hợp với môi trường của bạn.

Halo-portal-client (giao diện người dùng cổng thông tin)

06_Keycloak

Valid redirect URIs: thay thế miền giữ chỗ trong JSON của realm bằng miền cổng thông tin thực tế của bạn. Cấu hình mẫu sử dụng một miền thử nghiệm (ví dụ: https://pvetest.cdr.glasswall.dev/authentication/login-callback). Hãy cập nhật giá trị này để khớp với URL mà người dùng sẽ dùng để truy cập cổng thông tin Halo của bạn.

Ví dụ: nếu cổng thông tin Halo của bạn khả dụng tại https://halo.dev.local/ và đường dẫn callback đăng nhập của ứng dụng là /authentication/login-callback, hãy đặt:

Valid redirect URIs: https://halo.dev.local/authentication/*
Web origins: https://halo.dev.local
URL gốc (tùy chọn):https://halo.dev.local
URI chuyển hướng hợp lệ sau khi đăng xuất:https://halo.dev.local/authentication/logout-callback

07_Keycloak

Halo-portal-access (backend của cổng thông tin)

Valid redirect URIs: (e.g.,https://pvetest.cdr.glasswall.dev/*)
- Cập nhật thành miền cổng thông tin của bạn.
Web origins: https://halo.dev.local

Halo-API-access

Giữ nguyên cài đặt chuyển hướng và lưu cài đặt của từng client.

08_Keycloak

1.3 Tạo người dùng và gán vai trò

Bây giờ bạn sẽ tạo người dùng và gán vai trò Halo.

09_Keycloak

A. Trong realm glasswall, điều hướng đến Users → Add user. B. Điền Username và các thông tin chi tiết. C. Trong phần Credentials, đặt mật khẩu và bỏ chọn "Temporary". D. Trong Role mappings, gán:

Realm roles:
- Admin
- User
Client roles:
- halo-portal-client[Admin, user]
- halo-api-access[Admin, user]
- halo-portal-access[Admin, user]

10_Keycloak

Người dùng Admin sẽ thấy:

11_Keycloak

Và có thể quản lý:

12_Keycloak

Bao gồm:

13_Keycloak

Bước 2 - Chứng chỉ TLS và các lưu ý về DNS

Đảm bảo thiết lập tin cậy TLS và DNS phù hợp cho tất cả các thành phần.

2.1 Tin cậy TLS

Các dịch vụ nền tảng Halo (Portal, Portal-Access, API-Access) phải tin cậy chứng chỉ của Keycloak.

2.2 DNS và /etc/hosts

Đảm bảo:

Hostname của Keycloak được phân giải cho tất cả dịch vụ và người dùng
Các miền của Halo cũng được phân giải

Bước 3 - Triển khai các dịch vụ Halo với SSO Keycloak (cấu hình Helm)

Halo được triển khai qua Helm; các môi trường ngoại tuyến sử dụng chart đi kèm với hệ thống.

Triển khai cổng Halo

portal_image_tag=$(k get deploy portal  -o json | jq -r '.spec.template.spec.containers[0].image' | cut -d":" -f2)
portal_domain="glasswall.example.com"
keycloak_domain="keycloak.example.com"
helm upgrade --install cdrplatform-portal ./cdrplatform-portal \
  --set image.tag="${portal_image_tag:?}" \
  --set image.pullPolicy=IfNotPresent \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain="${portal_domain:?}" \
  --set ingress.tls.secretName="tls-secret" \
  --set configuration.BackendUrl="https://${portal_domain:?}" \
  --set configuration.HaloVersion="2.12.0" \
  --set configuration.EnabledPages="SystemSettings\,PolicySettings\,ValidationSettings" \
  --set configuration.OIDC.ProviderOptions.Authority="https://${keycloak_domain:?}/realms/glasswall" \
  --set configuration.OIDC.ProviderOptions.ClientId="halo-portal-client" \
  --set configuration.OIDC.ProviderOptions.RedirectUri="https://${portal_domain:?}/authentication/login-callback" \
  --set configuration.OIDC.ProviderOptions.PostLogoutRedirectUri="https://${portal_domain:?}/authentication/logout-callback" \
  --set configuration.OIDC.ProviderOptions.Scope="openid profile api://cdrplatform-portal-access/PortalUserScope" \
  --set configuration.OIDC.ProviderOptions.SilentCheckSsoRedirectUri="https://${portal_domain:?}/silent-check-sso.html" \
  --set appenvironment.HTTP_CSP_FRAME_SRC="'self' https://${keycloak_domain:?} https://${portal_domain:?}/silent-check-sso.html" \
  --set appenvironment.HTTP_CSP_CONNECT_SRC="'self' https://${keycloak_domain:?}" \
  --set configuration.Authentication__Schemes__Bearer__RequireHttpsMetadata=true \
  --set configuration.Authentication__Schemes__Bearer__MetadataAddress="https://${keycloak_domain:?}/realms/glasswall/.well-known/openid-configuration" \
  --set configuration.Logging__LogLevel__Keycloak="Debug" \
  --atomic

Triển khai portal-access

image_tag=$(k get deploy portal-access  -o json | jq -r '.spec.template.spec.containers[0].image' | cut -d":" -f2)
portal_domain="glasswall.example.com"
keycloak_domain="keycloak.example.com"
helm upgrade --install cdrplatform-portal-access ./cdrplatform-portal-access \
  --set image.tag="${image_tag:?}" \
  --set image.pullPolicy=IfNotPresent \
  --set ingress.tls.domain="${portal_domain:?}" \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName="tls-secret" \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://cdrplatform-portal-access" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="https://${keycloak_domain:?}/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__Authority="https://${keycloak_domain:?}/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__RequireHttpsMetadata=true \
  --set configuration.Authentication__Schemes__Bearer__MetadataAddress="https://${keycloak_domain:?}/realms/glasswall/.well-known/openid-configuration" \
  --set configuration.Authentication__Schemes__Bearer__JwksUri="https://${keycloak_domain:?}/realms/glasswall/protocol/openid-connect/certs" \
  --atomic

Triển khai API-access

api_access_image_tag=$(k get deploy api-access  -o json | jq -r '.spec.template.spec.containers[0].image' | cut -d":" -f2)
portal_domain="test.cdr.glasswall.dev"
keycloak_domain="pbkc.cdr.glasswall.dev"
helm upgrade --install cdrplatform-api-access ./cdrplatform-api-access \
  --set image.tag="${api_access_image_tag:?}" \
  --set image.pullPolicy=IfNotPresent \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName="tls-secret" \
  --set ingress.tls.domain="${portal_domain:?}" \
  --set configuration.AuthenticationScheme="Bearer" \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0="api://cdrplatform-api-access" \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer="https://${keycloak_domain:?}/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__Authority="https://${keycloak_domain:?}/realms/glasswall" \
  --set configuration.Authentication__Schemes__Bearer__RequireHttpsMetadata=true \
  --set configuration.Authentication__Schemes__Bearer__MetadataAddress="https://${keycloak_domain:?}/realms/glasswall/.well-known/openid-configuration" \
  --set configuration.Authentication__Schemes__Bearer__JwksUri="https://${keycloak_domain:?}/realms/glasswall/protocol/openid-connect/certs" \
  --atomic

3.1 Danh sách kiểm tra sau triển khai

Đảm bảo rằng các pod đang chạy (không có CrashLoopBackOff).
Đồng thời kiểm tra rằng nhật ký hiển thị cấu hình Keycloak OIDC thành công.

14_Keycloak

Bước 4 - Xác thực và kiểm thử tích hợp SSO

15_Keycloak

A. Khởi chạy cổng thông tin Halo. B. Được chuyển hướng đến trang đăng nhập Keycloak.

16_Keycloak

C. Đăng nhập vào tài khoản của bạn.

17_Keycloak

D. Quay lại Halo sau khi được xác thực.

18_Keycloak

Bước 5 - Khắc phục sự cố

URI chuyển hướng được cấu hình sai

Kiểm tra để bảo đảm các URI khớp nhau giữa cổng thông tin và Keycloak.

Độ lệch đồng hồ

Đồng bộ đồng hồ hệ thống.

Lỗi tin cậy TLS

Đảm bảo Halo tin cậy chứng chỉ của Keycloak.

Tài liệu tham khảo

Tài liệu Keycloak

Tổng quan​

Hướng dẫn tích hợp SSO Keycloak của Glasswall Halo​

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

Yêu cầu môi trường​

Tài nguyên bắt buộc​

Cấu hình DNS/hosts​

Bước 1 - Cấu hình Keycloak cho SSO của Glasswall Halo​

1.1 - Nhập cấu hình realm Glasswall​

1.2 Tùy chỉnh cài đặt client (tên máy chủ và URI chuyển hướng)​

Halo-portal-client (giao diện người dùng cổng thông tin)​

Halo-portal-access (backend của cổng thông tin)​

Halo-API-access​

1.3 Tạo người dùng và gán vai trò​

Bước 2 - Chứng chỉ TLS và các lưu ý về DNS​

2.1 Tin cậy TLS​

2.2 DNS và /etc/hosts​

Bước 3 - Triển khai các dịch vụ Halo với SSO Keycloak (cấu hình Helm)​

Triển khai cổng Halo​

Triển khai portal-access​

Triển khai API-access​

3.1 Danh sách kiểm tra sau triển khai​

Bước 4 - Xác thực và kiểm thử tích hợp SSO​

4.1 Kiểm thử đăng nhập trên trình duyệt​

Bước 5 - Khắc phục sự cố​

URI chuyển hướng được cấu hình sai​

Độ lệch đồng hồ​

Lỗi tin cậy TLS​

Tài liệu tham khảo​