Integrasi SSO Keycloak

Gambaran keseluruhan

Panduan ini menyediakan arahan langkah demi langkah untuk mengintegrasikan Keycloak Single Sign-On (SSO) dengan platform Glasswall Halo dalam persekitaran luar talian (air-gapped), on-premises.

Ia mengandaikan anda telah pun menggunakan platform Single Node Halo (contohnya, pada VM melalui Proxmox atau ESXi) dan kini ingin mendayakan SSO berasaskan OIDC menggunakan Keycloak.

Anda akan mempelajari cara untuk:

Menyediakan pelayan Keycloak dengan HTTPS dalam persekitaran luar talian (menggunakan imej kontena pramuat atau pemasangan VM manual).
Import dan sesuaikan konfigurasi Keycloak glasswall-realm.json yang disediakan.
Konfigurasikan sijil TLS dan resolusi DNS/hos untuk kedua-dua Keycloak dan Halo.
Deploy the Halo portal and related services:
- cdrplatform-portal
- cdrplatform-portalaccess
- cdrplatform-api-access

Panduan Integrasi SSO Keycloak Glasswall Halo

Prasyarat

Keperluan persekitaran

Persediaan ini ditujukan untuk persekitaran air-gapped atau on-premises yang dikawal ketat.
Kluster Halo Nod Tunggal mesti telah pun dikerahkan.
Resolusi DNS dalaman mesti tersedia, sama ada melalui pelayan DNS tempatan atau secara manual melalui entri /etc/hosts.
Keycloak mesti dipasang secara setempat pada hos atau mesin maya. → dokumentasi & pemasangan Keycloak

Sumber yang diperlukan

Fail realm yang telah diprakonfigurasi (glasswall-realm.json), disediakan oleh Glasswall Support.
Akses setempat kepada carta Helm Halo untuk deployment dalam kluster Single Node Halo.

Konfigurasi DNS/hosts

Pastikan nama hos untuk pelayan Keycloak anda boleh diselesaikan oleh kedua-dua mesin klien dan komponen platform Halo.

Dengan DNS dalaman: cipta rekod A untuk keycloak.dev.local yang menunjuk kepada alamat IP pelayan Keycloak.
Tanpa DNS dalaman: tambah entri berikut ke fail hosts pada setiap mesin yang memerlukan akses:

Langkah 1 - Mengkonfigurasi Keycloak untuk Glasswall Halo SSO

Glasswall menyediakan konfigurasi realm Keycloak (sebagai fail JSON) yang mentakrifkan realm, klien, peranan dan skop yang diperlukan untuk SSO Halo.

Anda boleh mengimport konfigurasi ini untuk mengelakkan persediaan manual. Dalam persediaan luar talian, lakukan ini melalui Keycloak Admin UI.

1.1 - Mengimport konfigurasi realm Glasswall

A. Dapatkan eksport realm: anda sepatutnya mempunyai fail bernama glasswall-realm.json. Fail ini mengandungi tetapan realm untuk SSO Halo.

Ringkasan realm Glasswall

Realm Glasswall merangkumi item pra-konfigurasi berikut:

ID Realm: Glasswall
Klien
- Halo-portal-client
- Halo-API-access
- Halo-portal-access
Peranan utama
- Peringkat realm: admin, user
- Peringkat klien: peranan admin dan user klien Halo.
- Skop klien (diprakonfigurasikan dengan mapper):
- Portaluserscope: tuntutan yang diperlukan (roles, email) kepada token.
Jangka hayat token
- Masa tamat melahu sesi SSO: 30 minit
Pengesahan: nama pengguna/kata laluan standard.

B. Log masuk ke Keycloak Admin

Menggunakan pelayar web, navigasi ke Keycloak Admin Console di https://<KEYCLOAK_HOST>:8443/ dan log masuk dengan akaun admin master.

01_Keycloak

C. Import realm.

Dalam konsol admin pilih menu lungsur yang kini memaparkan "Master" dan klik Create realm.

02_Keycloak

Daripada skrin Create realm, pilih Import, dan muat naik fail glasswall-realm.json.

03_Keycloak

Keycloak will parse the file and populate the realm name (e.g.,glasswall).
- Sahkan import.

04_Keycloak

D. Sahkan tetapan realm

After import, review key settings and ensure:
- Nama realm ialah glasswall.
- Realm didayakan.
- SSL diperlukan: kemungkinan ditetapkan kepada external.
- Clients should include:
  - halo-portal-client
  - halo-portal-access
  - halo-api-access

05_Keycloak

1.2 Menyesuaikan tetapan klien (nama hos dan URI ubah hala)

Seterusnya, untuk setiap klien Halo, kemas kini konfigurasi agar sepadan dengan persekitaran anda.

Halo-portal-client (frontend portal)

06_Keycloak

Valid redirect URIs: gantikan domain pemegang tempat dalam JSON realm dengan domain portal sebenar anda. Konfigurasi sampel menggunakan domain ujian (contohnya, https://pvetest.cdr.glasswall.dev/authentication/login-callback). Kemas kini nilai ini agar sepadan dengan URL yang akan digunakan pengguna untuk mengakses portal Halo anda.

Sebagai contoh, jika portal Halo anda tersedia di https://halo.dev.local/ dan laluan callback log masuk aplikasi ialah /authentication/login-callback, tetapkan:

Valid redirect URIs: https://halo.dev.local/authentication/*
Web origins: https://halo.dev.local
URL Root (pilihan):https://halo.dev.local
URI ubah hala sah selepas log keluar:https://halo.dev.local/authentication/logout-callback

07_Keycloak

Halo-portal-access (bahagian belakang portal)

Valid redirect URIs: (e.g.,https://pvetest.cdr.glasswall.dev/*)
- Kemas kini kepada domain portal anda.
Web origins: https://halo.dev.local

Halo-API-access

Biarkan tetapan ubah hala seperti sedia ada, dan simpan tetapan setiap klien.

08_Keycloak

1.3 Mencipta pengguna dan menetapkan peranan

Sekarang anda akan mencipta pengguna dan menetapkan peranan Halo.

09_Keycloak

A. Dalam realm glasswall, pergi ke Users → Add user. B. Isikan Username dan butiran. C. Dalam bahagian Credentials, tetapkan kata laluan dan nyahpilih "Temporary". D. Dalam Role mappings, tetapkan:

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

10_Keycloak

Pengguna Admin melihat:

11_Keycloak

Dan boleh menguruskan:

12_Keycloak

Termasuk:

13_Keycloak

Langkah 2 - Sijil TLS dan pertimbangan DNS

Pastikan kepercayaan TLS dan DNS yang betul untuk semua komponen.

2.1 Kepercayaan TLS

Perkhidmatan platform Halo (Portal, Portal-Access, API-Access) mesti mempercayai sijil Keycloak.

2.2 DNS dan /etc/hosts

Pastikan:

Nama hos Keycloak dapat diselesaikan untuk semua perkhidmatan dan pengguna
Domain Halo juga dapat diselesaikan

Langkah 3 - Mengerahkan perkhidmatan Halo dengan SSO Keycloak (konfigurasi Helm)

Halo dikerahkan melalui Helm; persekitaran luar talian menggunakan carta yang dibundel bersama sistem.

Kerahkan portal 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

Kerahkan 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

Kerahkan 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 Senarai semak selepas deployment

Pastikan pod sedang berjalan (tiada CrashLoopBackOff).
Semak juga bahawa log menunjukkan konfigurasi Keycloak OIDC yang berjaya.

14_Keycloak

Langkah 4 - Pengesahan dan ujian integrasi SSO

15_Keycloak

A. Lancarkan portal Halo. B. Dialihkan ke log masuk Keycloak.

16_Keycloak

C. Log masuk ke akaun anda.

17_Keycloak

D. Kembali ke Halo selepas berjaya diautentikasi.

18_Keycloak

Langkah 5 - Penyelesaian masalah

URI redirect yang tersalah konfigurasi

Semak bahawa URI sepadan antara portal dan Keycloak.

Penyimpangan masa

Segerakkan jam sistem.

Ralat kepercayaan TLS

Pastikan Halo mempercayai sijil Keycloak.

Rujukan

Dokumentasi Keycloak

Gambaran keseluruhan​

Panduan Integrasi SSO Keycloak Glasswall Halo​

Prasyarat​

Keperluan persekitaran​

Sumber yang diperlukan​

Konfigurasi DNS/hosts​

Langkah 1 - Mengkonfigurasi Keycloak untuk Glasswall Halo SSO​

1.1 - Mengimport konfigurasi realm Glasswall​

1.2 Menyesuaikan tetapan klien (nama hos dan URI ubah hala)​

Halo-portal-client (frontend portal)​

Halo-portal-access (bahagian belakang portal)​

Halo-API-access​

1.3 Mencipta pengguna dan menetapkan peranan​

Langkah 2 - Sijil TLS dan pertimbangan DNS​

2.1 Kepercayaan TLS​

2.2 DNS dan /etc/hosts​

Langkah 3 - Mengerahkan perkhidmatan Halo dengan SSO Keycloak (konfigurasi Helm)​

Kerahkan portal Halo​

Kerahkan portal-access​

Kerahkan API-access​

3.1 Senarai semak selepas deployment​

Langkah 4 - Pengesahan dan ujian integrasi SSO​

4.1 Ujian log masuk pelayar​

Langkah 5 - Penyelesaian masalah​

URI redirect yang tersalah konfigurasi​

Penyimpangan masa​

Ralat kepercayaan TLS​

Rujukan​