การผสานรวม Keycloak SSO

ภาพรวม

คู่มือนี้ให้คำแนะนำทีละขั้นตอนสำหรับการผสานรวม Keycloak Single Sign-On (SSO) กับแพลตฟอร์ม Glasswall Halo ในสภาพแวดล้อม on-premises แบบออฟไลน์ (air-gapped)

คู่มือนี้ตั้งอยู่บนสมมติฐานว่าคุณได้ปรับใช้แพลตฟอร์ม Halo แบบ Single Node แล้ว (เช่น บน VM ผ่าน Proxmox หรือ ESXi) และขณะนี้ต้องการเปิดใช้งาน SSO ที่ใช้ OIDC โดยใช้ Keycloak

คุณจะได้เรียนรู้วิธีการดังต่อไปนี้:

ตั้งค่าเซิร์ฟเวอร์ Keycloak พร้อม HTTPS ในสภาพแวดล้อมออฟไลน์ (โดยใช้อิมเมจคอนเทนเนอร์ที่โหลดไว้ล่วงหน้าหรือการติดตั้ง VM ด้วยตนเอง)
นำเข้าการกำหนดค่า Keycloak glasswall-realm.json ที่ให้มาและปรับแต่งตามต้องการ
กำหนดค่าใบรับรอง TLS และการแก้ไขชื่อ DNS/โฮสต์สำหรับทั้ง Keycloak และ Halo
Deploy the Halo portal and related services:
- cdrplatform-portal
- cdrplatform-portalaccess
- cdrplatform-api-access

คู่มือการผสานรวม Keycloak SSO ของ Glasswall Halo

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

ข้อกำหนดด้านสภาพแวดล้อม

การตั้งค่านี้มีไว้สำหรับสภาพแวดล้อมแบบ air-gapped หรือ on-premises ที่มีข้อจำกัดอย่างเข้มงวด
ต้องปรับใช้คลัสเตอร์ Halo แบบโหนดเดียวเรียบร้อยแล้ว
ต้องมีการแก้ไขชื่อ DNS ภายในไว้แล้ว ไม่ว่าจะผ่านเซิร์ฟเวอร์ DNS ภายในเครื่องหรือกำหนดด้วยตนเองผ่านรายการใน /etc/hosts
ต้องติดตั้ง Keycloak ภายในเครื่องบนโฮสต์หรือเครื่องเสมือน → เอกสารประกอบและการติดตั้ง Keycloak

ทรัพยากรที่จำเป็น

ไฟล์ realm ที่กำหนดค่าไว้ล่วงหน้า (glasswall-realm.json) ซึ่งจัดเตรียมโดย Glasswall Support.
การเข้าถึง Halo Helm charts ภายในเครื่องสำหรับการปรับใช้ภายในคลัสเตอร์ Single Node Halo

การกำหนดค่า DNS/hosts

ตรวจสอบให้แน่ใจว่าชื่อโฮสต์สำหรับเซิร์ฟเวอร์ Keycloak ของคุณสามารถ resolve ได้โดยทั้งเครื่องไคลเอนต์และคอมโพเนนต์ของแพลตฟอร์ม Halo

เมื่อมี internal DNS: สร้างระเบียน A สำหรับ keycloak.dev.local ให้ชี้ไปยังที่อยู่ IP ของเซิร์ฟเวอร์ Keycloak
เมื่อไม่มี internal DNS: เพิ่มรายการต่อไปนี้ลงในไฟล์ hosts บนแต่ละเครื่องที่ต้องการเข้าถึง:

ขั้นตอนที่ 1 - การกำหนดค่า Keycloak สำหรับ Glasswall Halo SSO

Glasswall จัดเตรียมการกำหนดค่า Keycloak realm (ในรูปแบบไฟล์ JSON) ที่กำหนด realm, clients, roles และ scopes ที่จำเป็นสำหรับ SSO ของ Halo

คุณสามารถนำเข้าการกำหนดค่านี้เพื่อหลีกเลี่ยงการตั้งค่าด้วยตนเอง ในการตั้งค่าแบบออฟไลน์ ให้ดำเนินการผ่าน Keycloak Admin UI

1.1 - การนำเข้าการกำหนดค่า Glasswall realm

A. รับไฟล์ส่งออก realm: คุณควรมีไฟล์ชื่อ glasswall-realm.json ไฟล์นี้มีการตั้งค่า realm สำหรับ SSO ของ Halo

สรุป Glasswall realm

Glasswall realm มีรายการที่กำหนดค่าไว้ล่วงหน้าดังต่อไปนี้:

Realm ID: Glasswall
ไคลเอนต์
- Halo-portal-client
- Halo-API-access
- Halo-portal-access
บทบาทหลัก
- ระดับ Realm: admin, user
- ระดับไคลเอนต์: บทบาทผู้ดูแลระบบและผู้ใช้ของไคลเอนต์ Halo
- ขอบเขตไคลเอนต์ (กำหนดค่าไว้ล่วงหน้าพร้อม mappers):
- Portaluserscope: claims ที่จำเป็น (roles, email) สำหรับโทเค็น
อายุการใช้งานของโทเค็น
- ระยะหมดเวลาเมื่อไม่มีการใช้งานของเซสชัน SSO: 30 นาที
การยืนยันตัวตน: ชื่อผู้ใช้/รหัสผ่านมาตรฐาน

B. เข้าสู่ระบบ Keycloak Admin

ใช้เว็บเบราว์เซอร์ ไปที่ Keycloak Admin Console ที่ https://<KEYCLOAK_HOST>:8443/ และเข้าสู่ระบบด้วยบัญชีผู้ดูแลระบบหลัก

01_Keycloak

C. นำเข้า realm.

ในคอนโซลผู้ดูแลระบบ ให้เลือกเมนูดรอปดาวน์ที่ขณะนี้แสดง "Master" แล้วคลิก Create realm.

02_Keycloak

จากหน้าจอ Create realm ให้เลือก Import แล้วอัปโหลดไฟล์ glasswall-realm.json

03_Keycloak

Keycloak will parse the file and populate the realm name (e.g.,glasswall).
- ยืนยันการนำเข้า

04_Keycloak

D. ตรวจสอบการตั้งค่า realm

After import, review key settings and ensure:
- ชื่อ Realm คือglasswall
- Realm ถูกเปิดใช้งานอยู่
- ต้องใช้ SSL: โดยทั่วไปตั้งค่าเป็นexternal
- Clients should include:
  - halo-portal-client
  - halo-portal-access
  - halo-api-access

05_Keycloak

1.2 การปรับแต่งการตั้งค่า client (ชื่อโฮสต์และ redirect URI)

ถัดไป สำหรับแต่ละ client ของ Halo ให้อัปเดตการกำหนดค่าให้ตรงกับสภาพแวดล้อมของคุณ

Halo-portal-client (ฟรอนต์เอนด์ของพอร์ทัล)

06_Keycloak

Valid redirect URIs: แทนที่โดเมนตัวอย่างใน realm JSON ด้วยโดเมนพอร์ทัลจริงของคุณ การกำหนดค่าตัวอย่างใช้โดเมนทดสอบ (ตัวอย่างเช่น https://pvetest.cdr.glasswall.dev/authentication/login-callback) อัปเดตค่านี้ให้ตรงกับ URL ที่ผู้ใช้จะใช้เพื่อเข้าถึงพอร์ทัล Halo ของคุณ

ตัวอย่างเช่น หากพอร์ทัล Halo ของคุณพร้อมใช้งานที่ https://halo.dev.local/ และพาธ login callback ของแอปพลิเคชันคือ /authentication/login-callback ให้ตั้งค่าดังนี้:

Valid redirect URIs:https://halo.dev.local/authentication/*
Web origins:https://halo.dev.local
Root URL (ไม่บังคับ):https://halo.dev.local
Valid post logout redirect URIs:https://halo.dev.local/authentication/logout-callback

07_Keycloak

Halo-portal-access (แบ็กเอนด์พอร์ทัล)

Valid redirect URIs: (e.g.,https://pvetest.cdr.glasswall.dev/*)
- อัปเดตเป็นโดเมนพอร์ทัลของคุณ
Web origins:https://halo.dev.local

Halo-API-access

คงการตั้งค่า redirect ไว้ตามเดิม และบันทึกการตั้งค่าของแต่ละ client

08_Keycloak

1.3 การสร้างผู้ใช้และกำหนดบทบาท

ตอนนี้คุณจะสร้างผู้ใช้และกำหนดบทบาทของ Halo

09_Keycloak

A. ใน realm glasswall ไปที่ Users → Add user B. กรอก Username และรายละเอียด C. ในส่วน Credentials ให้ตั้งรหัสผ่านและยกเลิกเลือก "Temporary" D. ใน Role mappings ให้กำหนด:

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

10_Keycloak

ผู้ใช้ Admin จะเห็น:

11_Keycloak

และสามารถจัดการ:

12_Keycloak

รวมถึง:

13_Keycloak

ขั้นตอนที่ 2 - ใบรับรอง TLS และข้อพิจารณาเกี่ยวกับ DNS

ตรวจสอบให้แน่ใจว่ามี TLS trust และ DNS ที่ถูกต้องสำหรับทุกคอมโพเนนต์

2.1 TLS trust

บริการแพลตฟอร์ม Halo (Portal, Portal-Access, API-Access) ต้องเชื่อถือใบรับรองของ Keycloak

2.2 DNS และ /etc/hosts

ตรวจสอบให้แน่ใจว่า:

ชื่อโฮสต์ของ Keycloak ต้องสามารถ resolve ได้สำหรับทุกบริการและผู้ใช้
โดเมนของ Halo ต้องสามารถ resolve ได้เช่นกัน

ขั้นตอนที่ 3 - การปรับใช้บริการ Halo ด้วย Keycloak SSO (การกำหนดค่า Helm)

Halo ถูกปรับใช้ผ่าน Helm; สภาพแวดล้อมออฟไลน์จะใช้ charts ที่มาพร้อมกับระบบ

ปรับใช้พอร์ทัล 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

ปรับใช้ 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

ปรับใช้ 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 รายการตรวจสอบหลังการปรับใช้

ตรวจสอบให้แน่ใจว่า pods กำลังทำงานอยู่ (ไม่มีCrashLoopBackOff)
ตรวจสอบด้วยว่า logs แสดงการกำหนดค่า Keycloak OIDC สำเร็จ

14_Keycloak

ขั้นตอนที่ 4 - การตรวจสอบความถูกต้องและการทดสอบการผสานรวม SSO

15_Keycloak

A. เปิดพอร์ทัล Halo B. ถูกเปลี่ยนเส้นทางไปยังหน้าเข้าสู่ระบบ Keycloak

16_Keycloak

C. ลงชื่อเข้าใช้บัญชีของคุณ

17_Keycloak

D. กลับไปที่ Halo หลังจากยืนยันตัวตนแล้ว

18_Keycloak

ขั้นตอนที่ 5 - การแก้ไขปัญหา

Redirect URI กำหนดค่าไม่ถูกต้อง

ตรวจสอบว่า URI ตรงกันระหว่างพอร์ทัลและ Keycloak

Clock skew

ซิงก์นาฬิการะบบ

ข้อผิดพลาดด้านความเชื่อถือ TLS

ตรวจสอบให้แน่ใจว่า Halo เชื่อถือ cert ของ Keycloak

ข้อมูลอ้างอิง

เอกสารประกอบ Keycloak

ภาพรวม​

คู่มือการผสานรวม Keycloak SSO ของ Glasswall Halo​

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

ข้อกำหนดด้านสภาพแวดล้อม​

ทรัพยากรที่จำเป็น​

การกำหนดค่า DNS/hosts​

ขั้นตอนที่ 1 - การกำหนดค่า Keycloak สำหรับ Glasswall Halo SSO​

1.1 - การนำเข้าการกำหนดค่า Glasswall realm​

1.2 การปรับแต่งการตั้งค่า client (ชื่อโฮสต์และ redirect URI)​

Halo-portal-client (ฟรอนต์เอนด์ของพอร์ทัล)​

Halo-portal-access (แบ็กเอนด์พอร์ทัล)​

Halo-API-access​

1.3 การสร้างผู้ใช้และกำหนดบทบาท​

ขั้นตอนที่ 2 - ใบรับรอง TLS และข้อพิจารณาเกี่ยวกับ DNS​

2.1 TLS trust​

2.2 DNS และ /etc/hosts​

ขั้นตอนที่ 3 - การปรับใช้บริการ Halo ด้วย Keycloak SSO (การกำหนดค่า Helm)​

ปรับใช้พอร์ทัล Halo​

ปรับใช้ portal-access​

ปรับใช้ API-access​

3.1 รายการตรวจสอบหลังการปรับใช้​

ขั้นตอนที่ 4 - การตรวจสอบความถูกต้องและการทดสอบการผสานรวม SSO​

4.1 การทดสอบการเข้าสู่ระบบผ่านเบราว์เซอร์​

ขั้นตอนที่ 5 - การแก้ไขปัญหา​

Redirect URI กำหนดค่าไม่ถูกต้อง​

Clock skew​

ข้อผิดพลาดด้านความเชื่อถือ TLS​

ข้อมูลอ้างอิง​