Lumaktaw sa pangunahing nilalaman

Keycloak SSO Integration

Pangkalahatang-ideya​

Nagbibigay ang gabay na ito ng sunod-sunod na mga tagubilin para sa pag-integrate ng Keycloak Single Sign-On (SSO) sa Glasswall Halo platform sa isang offline (air-gapped), on-premises na environment.

Ipinapalagay nito na na-deploy mo na ang Single Node Halo platform (hal., sa mga VM sa pamamagitan ng Proxmox o ESXi) at nais mo na ngayong paganahin ang OIDC-based SSO gamit ang Keycloak.

Matututuhan mo kung paano:

  • Mag-set up ng Keycloak server na may HTTPS sa isang offline na environment (gamit ang preloaded container image o manual na pag-install ng VM).
  • I-import at i-customize ang ibinigay na glasswall-realm.json na configuration ng Keycloak.
  • I-configure ang mga TLS certificate at DNS/host resolution para sa parehong Keycloak at Halo.
  • Deploy the Halo portal and related services:
    • cdrplatform-portal
    • cdrplatform-portalaccess
    • cdrplatform-api-access

Gabay sa Integrasyon ng Keycloak SSO ng Glasswall Halo​

Mga Kinakailangan​

Mga kinakailangan sa environment​

  • Ang setup na ito ay inilaan para sa mga air-gapped o mahigpit na on-premises na environment.
  • Ang Single Node Halo cluster ay dapat na na-deploy na.
  • Dapat ay nakaayos na ang internal DNS resolution, alinman sa pamamagitan ng lokal na DNS server o mano-manong sa pamamagitan ng mga entry sa /etc/hosts.
  • Dapat i-install ang Keycloak nang lokal sa isang host o virtual machine. → dokumentasyon at pag-install ng Keycloak

Mga kinakailangang resource​

  • Isang paunang na-configure na realm file (glasswall-realm.json), na ibinigay ng Glasswall Support.
  • Lokal na access sa mga Halo Helm chart para sa deployment sa loob ng Single Node Halo cluster.

Configuration ng DNS/hosts​

Tiyaking ang hostname para sa iyong Keycloak server ay nare-resolve ng parehong mga client machine at mga component ng Halo platform.

  • May internal DNS: gumawa ng A record para sa keycloak.dev.local na tumuturo sa IP address ng Keycloak server.
  • Walang internal DNS: idagdag ang sumusunod na entry sa hosts file sa bawat machine na nangangailangan ng access:

Hakbang 1 - Pag-configure ng Keycloak para sa Glasswall Halo SSO​

Nagbibigay ang Glasswall ng configuration ng Keycloak realm (bilang JSON file) na tumutukoy sa realm, clients, roles, at scopes na kailangan para sa SSO ng Halo.

Maaari mong i-import ang configuration na ito upang maiwasan ang manu-manong setup. Sa isang offline na setup, gawin ito sa pamamagitan ng Keycloak Admin UI.

1.1 - Pag-import ng configuration ng Glasswall realm​

A. Kunin ang realm export: dapat ay mayroon kang file na pinangalanang glasswall-realm.json. Ang file na ito ay naglalaman ng mga setting ng realm para sa SSO ng Halo.

Buod ng Glasswall realm

Kasama sa Glasswall realm ang mga sumusunod na paunang na-configure na item:

  • Realm ID: Glasswall

  • Mga client

    • Halo-portal-client
    • Halo-API-access
    • Halo-portal-access

  • Mahahalagang role

    • Antas ng realm: admin, user
    • Antas ng client: mga role ng admin at user ng Halo client.
    • Mga client scope (nauna nang naka-configure gamit ang mga mapper):
    • Portaluserscope: mga kinakailangang claim (roles, email) para sa mga token.

  • Haba ng buhay ng token

    • Timeout ng pagiging idle ng session ng SSO: 30 minuto

  • Authentication: karaniwang username/password.

B. Mag-log in sa Keycloak Admin

  • Gamit ang web browser, pumunta sa Keycloak Admin Console sa https://<KEYCLOAK_HOST>:8443/ at mag-log in gamit ang master admin account.

01_Keycloak

C. I-import ang realm.

  • Sa admin console, piliin ang dropdown na kasalukuyang nagpapakita ng "Master" at i-click ang Create realm.

02_Keycloak

  • Mula sa screen na Create realm, piliin ang Import, at i-upload ang file na glasswall-realm.json.

03_Keycloak

  • Keycloak will parse the file and populate the realm name (e.g.,glasswall).
    • Kumpirmahin ang import.

04_Keycloak

D. I-verify ang mga setting ng realm

  • After import, review key settings and ensure:
    • Ang pangalan ng realm ay glasswall.
    • Naka-enable ang realm.
    • Kinakailangan ang SSL: malamang na nakatakda sa external.
    • Clients should include:
      • halo-portal-client
      • halo-portal-access
      • halo-api-access

05_Keycloak

1.2 Pag-customize ng mga setting ng client (mga hostname at redirect URI)​

Susunod, para sa bawat isa sa mga Halo client, i-update ang configuration upang tumugma sa iyong environment.

Halo-portal-client (frontend ng portal)​

06_Keycloak

Valid redirect URIs: palitan ang placeholder domain sa realm JSON ng iyong aktuwal na portal domain. Gumagamit ang sample configuration ng test domain (halimbawa, https://pvetest.cdr.glasswall.dev/authentication/login-callback). I-update ang value na ito upang tumugma sa URL na gagamitin ng mga user para ma-access ang iyong Halo portal.

Halimbawa, kung available ang iyong Halo portal sa https://halo.dev.local/ at ang login callback path ng application ay /authentication/login-callback, itakda ang:

  • Valid redirect URIs: https://halo.dev.local/authentication/*
  • Web origins: https://halo.dev.local
  • Root URL (opsyonal):https://halo.dev.local
  • Mga valid na post logout redirect URI:https://halo.dev.local/authentication/logout-callback

07_Keycloak

Halo-portal-access (portal backend)​

  • Valid redirect URIs: (e.g.,https://pvetest.cdr.glasswall.dev/*)
    • I-update ito sa domain ng iyong portal.
  • Web origins: https://halo.dev.local

Halo-API-access​

  • Iwanang walang pagbabago ang mga setting ng redirect, at i-save ang mga setting ng bawat client.

08_Keycloak

1.3 Paglikha ng mga user at pagtatalaga ng mga role​

Ngayon, gagawa ka ng mga user at magtatalaga ng mga role sa Halo.

09_Keycloak

A. Sa realm na glasswall, pumunta sa Users → Add user. B. Punan ang Username at mga detalye. C. Sa seksyong Credentials, magtakda ng password at alisin ang check sa "Temporary". D. Sa Role mappings, italaga ang:

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

10_Keycloak

Nakikita ng isang Admin user ang:

11_Keycloak

At maaaring pamahalaan ang:

12_Keycloak

Kabilang ang:

13_Keycloak

Hakbang 2 - Mga sertipiko ng TLS at mga konsiderasyon sa DNS​

Tiyakin ang wastong TLS trust at DNS para sa lahat ng component.

2.1 TLS trust​

Ang mga serbisyo ng Halo platform (Portal, Portal-Access, API-Access) ay dapat magtiwala sa certificate ng Keycloak.

2.2 DNS at /etc/hosts​

Tiyakin ang sumusunod:

  • Nare-resolve ang hostname ng Keycloak para sa lahat ng serbisyo at user
  • Nare-resolve rin ang mga domain ng Halo

Hakbang 3 - Pag-deploy ng mga serbisyo ng Halo gamit ang Keycloak SSO (mga configuration ng Helm)​

Ang Halo ay dine-deploy sa pamamagitan ng Helm; ang mga offline na environment ay gumagamit ng mga chart na kasama sa system.

I-deploy ang Halo portal​

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

I-deploy ang 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

I-deploy ang 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 Checklist pagkatapos ng deployment​

  • Tiyaking tumatakbo ang mga pod (walang CrashLoopBackOff).
  • Suriin din na nagpapakita ang mga log ng matagumpay na Keycloak OIDC config.

14_Keycloak

Hakbang 4 - Pagpapatunay at pagsubok ng SSO integration​

15_Keycloak

4.1 Pagsubok sa pag-login sa browser​

A. Buksan ang Halo portal. B. Ire-redirect sa Keycloak login.

16_Keycloak

C. Mag-sign in sa iyong account.

17_Keycloak

D. Bumalik sa Halo pagkatapos ma-authenticate.

18_Keycloak

Hakbang 5 - Pag-troubleshoot​

Maling pagkaka-configure ng redirect URI​

Suriin na magkatugma ang mga URI sa pagitan ng portal at Keycloak.

Hindi tugmang oras ng system​

I-sync ang mga system clock.

Mga error sa TLS trust​

Tiyaking pinagkakatiwalaan ng Halo ang cert ng Keycloak.

Mga Sanggunian​

Huling na-update noong