Integrasi SSO Keycloak

Ikhtisar

Panduan ini menyediakan petunjuk langkah demi langkah untuk mengintegrasikan Keycloak Single Sign-On (SSO) dengan platform Glasswall Halo dalam lingkungan on-premises offline (air-gapped).

Panduan ini mengasumsikan Anda telah menerapkan platform Halo Single Node (misalnya, pada VM melalui Proxmox atau ESXi) dan sekarang ingin mengaktifkan SSO berbasis OIDC menggunakan Keycloak.

Anda akan mempelajari cara:

Menyiapkan server Keycloak dengan HTTPS dalam lingkungan offline (menggunakan image container yang telah dimuat sebelumnya atau instalasi VM manual).
Impor dan sesuaikan konfigurasi Keycloak glasswall-realm.json yang disediakan.
Konfigurasikan sertifikat TLS dan resolusi DNS/host untuk Keycloak dan Halo.
Deploy the Halo portal and related services:
- cdrplatform-portal
- cdrplatform-portalaccess
- cdrplatform-api-access

Panduan Integrasi SSO Keycloak untuk Glasswall Halo

Prasyarat

Persyaratan lingkungan

Pengaturan ini ditujukan untuk lingkungan air-gapped atau on-premises yang sangat ketat.
Cluster Halo Single Node harus sudah diterapkan.
Resolusi DNS internal harus sudah tersedia, baik melalui server DNS lokal maupun secara manual melalui entri /etc/hosts.
Keycloak harus diinstal secara lokal pada host atau mesin virtual. → Dokumentasi & instalasi Keycloak

Sumber daya yang diperlukan

File realm yang telah dikonfigurasi sebelumnya (glasswall-realm.json), disediakan oleh Glasswall Support.
Akses lokal ke chart Helm Halo untuk deployment di dalam cluster Single Node Halo.

Konfigurasi DNS/hosts

Pastikan hostname untuk server Keycloak Anda dapat di-resolve oleh mesin klien dan komponen platform Halo.

Dengan DNS internal: buat record A untuk keycloak.dev.local yang mengarah ke alamat IP server Keycloak.
Tanpa DNS internal: tambahkan entri berikut ke file hosts pada setiap mesin yang memerlukan akses:

Langkah 1 - Mengonfigurasi Keycloak untuk SSO Glasswall Halo

Glasswall menyediakan konfigurasi realm Keycloak (sebagai file JSON) yang mendefinisikan realm, client, role, dan scope yang diperlukan untuk SSO Halo.

Anda dapat mengimpor konfigurasi ini untuk menghindari penyiapan manual. Dalam penyiapan offline, lakukan ini melalui UI Admin Keycloak.

1.1 - Mengimpor konfigurasi realm Glasswall

A. Dapatkan ekspor realm: Anda seharusnya memiliki file bernama glasswall-realm.json. File ini berisi pengaturan realm untuk SSO Halo.

Ringkasan realm Glasswall

Realm Glasswall mencakup item yang telah dikonfigurasi sebelumnya berikut ini:

ID Realm: Glasswall
Klien
- Halo-portal-client
- Halo-API-access
- Halo-portal-access
Peran utama
- Tingkat realm: admin, user
- Tingkat klien: peran admin dan user klien Halo.
- Cakupan klien (sudah dikonfigurasi sebelumnya dengan mapper):
- Portaluserscope: klaim yang diperlukan (roles, email) ke token.
Masa berlaku token
- Batas waktu idle sesi SSO: 30 menit
Autentikasi: username/password standar.

B. Masuk ke Admin Keycloak

Menggunakan browser web, buka Keycloak Admin Console di https://<KEYCLOAK_HOST>:8443/ dan masuk dengan akun master admin.

01_Keycloak

C. Impor realm.

Di konsol admin, pilih dropdown yang saat ini menampilkan "Master" lalu klik Create realm.

02_Keycloak

Dari layar Create realm, pilih Import, lalu unggah file glasswall-realm.json.

03_Keycloak

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

04_Keycloak

D. Verifikasi pengaturan realm

After import, review key settings and ensure:
- Nama realm adalah glasswall.
- Realm diaktifkan.
- SSL required: kemungkinan disetel ke external.
- Clients should include:
  - halo-portal-client
  - halo-portal-access
  - halo-api-access

05_Keycloak

1.2 Menyesuaikan pengaturan client (hostname dan URI pengalihan)

Selanjutnya, untuk masing-masing client Halo, perbarui konfigurasi agar sesuai dengan environment Anda.

Halo-portal-client (frontend portal)

06_Keycloak

Valid redirect URIs: ganti domain placeholder dalam JSON realm dengan domain portal Anda yang sebenarnya. Konfigurasi contoh menggunakan domain uji (misalnya, https://pvetest.cdr.glasswall.dev/authentication/login-callback). Perbarui nilai ini agar sesuai dengan URL yang akan digunakan pengguna untuk mengakses portal Halo Anda.

Sebagai contoh, jika portal Halo Anda tersedia di https://halo.dev.local/ dan path callback login aplikasi adalah /authentication/login-callback, setel:

Valid redirect URIs: https://halo.dev.local/authentication/*
Web origins: https://halo.dev.local
Root URL (opsional):https://halo.dev.local
Valid post logout redirect URIs:https://halo.dev.local/authentication/logout-callback

07_Keycloak

Halo-portal-access (backend portal)

Valid redirect URIs: (e.g.,https://pvetest.cdr.glasswall.dev/*)
- Perbarui ke domain portal Anda.
Web origins: https://halo.dev.local

Halo-API-access

Biarkan pengaturan redirect apa adanya, lalu simpan pengaturan setiap client.

08_Keycloak

1.3 Membuat pengguna dan menetapkan peran

Sekarang Anda akan membuat pengguna dan menetapkan peran Halo.

09_Keycloak

A. Di realm glasswall, buka Users → Add user. B. Isi Username dan detailnya. C. Di bagian Credentials, tetapkan kata sandi dan hapus centang "Temporary". D. Di 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 dapat mengelola:

12_Keycloak

Termasuk:

13_Keycloak

Langkah 2 - Sertifikat TLS dan pertimbangan DNS

Pastikan kepercayaan TLS dan DNS yang tepat untuk semua komponen.

2.1 Kepercayaan TLS

Layanan platform Halo (Portal, Portal-Access, API-Access) harus mempercayai sertifikat Keycloak.

2.2 DNS dan /etc/hosts

Pastikan:

Hostname Keycloak dapat di-resolve untuk semua layanan dan pengguna
Domain Halo juga dapat di-resolve

Langkah 3 - Mendeploy layanan Halo dengan Keycloak SSO (konfigurasi Helm)

Halo dideploy melalui Helm; lingkungan offline menggunakan chart yang dibundel dengan sistem.

Deploy 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

Deploy 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

Deploy 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 Daftar periksa pascadeployment

Pastikan pod berjalan (tidak ada CrashLoopBackOff).
Periksa juga bahwa log menampilkan konfigurasi OIDC Keycloak yang berhasil.

14_Keycloak

Langkah 4 - Validasi dan pengujian integrasi SSO

15_Keycloak

A. Buka portal Halo. B. Anda akan diarahkan ke login Keycloak.

16_Keycloak

C. Masuk ke akun Anda.

17_Keycloak

D. Kembali ke Halo setelah berhasil diautentikasi.

18_Keycloak

Langkah 5 - Pemecahan masalah

Redirect URI salah konfigurasi

Periksa apakah URI cocok antara portal dan Keycloak.

Clock skew

Sinkronkan jam sistem.

Kesalahan kepercayaan TLS

Pastikan Halo memercayai sertifikat Keycloak.

Referensi

Dokumentasi Keycloak

Ikhtisar​

Panduan Integrasi SSO Keycloak untuk Glasswall Halo​

Prasyarat​

Persyaratan lingkungan​

Sumber daya yang diperlukan​

Konfigurasi DNS/hosts​

Langkah 1 - Mengonfigurasi Keycloak untuk SSO Glasswall Halo​

1.1 - Mengimpor konfigurasi realm Glasswall​

1.2 Menyesuaikan pengaturan client (hostname dan URI pengalihan)​

Halo-portal-client (frontend portal)​

Halo-portal-access (backend portal)​

Halo-API-access​

1.3 Membuat pengguna dan menetapkan peran​

Langkah 2 - Sertifikat TLS dan pertimbangan DNS​

2.1 Kepercayaan TLS​

2.2 DNS dan /etc/hosts​

Langkah 3 - Mendeploy layanan Halo dengan Keycloak SSO (konfigurasi Helm)​

Deploy portal Halo​

Deploy portal-access​

Deploy API-access​

3.1 Daftar periksa pascadeployment​

Langkah 4 - Validasi dan pengujian integrasi SSO​

4.1 Uji login browser​

Langkah 5 - Pemecahan masalah​

Redirect URI salah konfigurasi​

Clock skew​

Kesalahan kepercayaan TLS​

Referensi​