Keycloak SSO Integration

अवलोकन

यह मार्गदर्शिका ऑफ़लाइन (air-gapped), on-premises वातावरण में Glasswall Halo प्लेटफ़ॉर्म के साथ Keycloak Single Sign-On (SSO) को एकीकृत करने के लिए चरण-दर-चरण निर्देश प्रदान करती है।

यह मानकर चलता है कि आपने पहले ही Single Node Halo प्लेटफ़ॉर्म को परिनियोजित कर लिया है (उदाहरण के लिए, Proxmox या ESXi के माध्यम से VMs पर) और अब Keycloak का उपयोग करके OIDC-आधारित SSO सक्षम करना चाहते हैं।

आप सीखेंगे कि कैसे:

ऑफ़लाइन वातावरण में HTTPS के साथ Keycloak server सेट अप करें (preloaded container image या manual VM installation का उपयोग करके)।
प्रदान की गई glasswall-realm.json Keycloak configuration को import करें और अनुकूलित करें।
Keycloak और Halo दोनों के लिए TLS certificates और DNS/host resolution कॉन्फ़िगर करें।
Deploy the Halo portal and related services:
- cdrplatform-portal
- cdrplatform-portalaccess
- cdrplatform-api-access

Glasswall Halo की Keycloak SSO Integration Guide

पूर्वापेक्षाएँ

Environment requirements

यह setup air-gapped या सख्ती से on-premises environments के लिए अभिप्रेत है।
Single Node Halo cluster पहले से deployed होना चाहिए।
Internal DNS resolution पहले से उपलब्ध होना चाहिए, चाहे local DNS server के माध्यम से या /etc/hosts entries के जरिए मैन्युअली।
Keycloak को किसी host या virtual machine पर लोकली इंस्टॉल किया जाना चाहिए. → Keycloak दस्तावेज़ीकरण & इंस्टॉलेशन

आवश्यक संसाधन

एक pre-configured realm फ़ाइल (glasswall-realm.json), जो Glasswall Support द्वारा प्रदान की गई है.
Single Node Halo cluster के भीतर deployment के लिए Halo Helm charts तक लोकल एक्सेस.

DNS/hosts कॉन्फ़िगरेशन

सुनिश्चित करें कि आपके Keycloak server का hostname client machines और Halo platform components, दोनों द्वारा resolve किया जा सके.

आंतरिक DNS के साथ: keycloak.dev.local के लिए एक A record बनाएं जो Keycloak server के IP address की ओर point करता हो.
आंतरिक DNS के बिना: प्रत्येक उस machine पर hosts फ़ाइल में निम्नलिखित entry जोड़ें जिसे एक्सेस की आवश्यकता है:

चरण 1 - Glasswall Halo SSO के लिए Keycloak कॉन्फ़िगर करना

Glasswall एक Keycloak realm configuration (JSON फ़ाइल के रूप में) प्रदान करता है, जो Halo के SSO के लिए आवश्यक realm, clients, roles और scopes को परिभाषित करती है.

मैन्युअल सेटअप से बचने के लिए आप इस configuration को import कर सकते हैं. ऑफ़लाइन सेटअप में, यह कार्य Keycloak Admin UI के माध्यम से करें.

1.1 - Glasswall realm configuration को import करना

A. realm export प्राप्त करें: आपके पास glasswall-realm.json नाम की एक फ़ाइल होनी चाहिए. इस फ़ाइल में Halo के SSO के लिए realm settings शामिल हैं.

Glasswall realm सारांश

Glasswall realm में निम्नलिखित pre-configured items शामिल हैं:

Realm ID: Glasswall
क्लाइंट्स
- Halo-portal-client
- Halo-API-access
- Halo-portal-access
मुख्य भूमिकाएँ
- Realm-level: admin, user
- क्लाइंट-स्तर: Halo क्लाइंट एडमिन और उपयोगकर्ता भूमिकाएँ।
- क्लाइंट स्कोप्स (mappers के साथ पहले से कॉन्फ़िगर किए गए):
- Portaluserscope: tokens के लिए आवश्यक claims (roles, email)।
टोकन अवधि
- SSO सत्र निष्क्रिय टाइमआउट: 30 मिनट
प्रमाणीकरण: मानक उपयोगकर्ता नाम/पासवर्ड।

B. Keycloak Admin में लॉग इन करें

वेब ब्राउज़र का उपयोग करके, https://<KEYCLOAK_HOST>:8443/ पर Keycloak Admin Console पर जाएँ और master admin account से लॉग इन करें।

01_Keycloak

C. realm इम्पोर्ट करें.

admin console में वह dropdown चुनें जो वर्तमान में "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 settings सत्यापित करें

After import, review key settings and ensure:
- Realm का नाम glasswall है।
- Realm सक्षम है।
- SSL required: संभवतः external पर सेट है।
- Clients should include:
  - halo-portal-client
  - halo-portal-access
  - halo-api-access

05_Keycloak

1.2 client settings को अनुकूलित करना (hostnames और redirect URIs)

इसके बाद, प्रत्येक Halo client के लिए, configuration को अपने environment के अनुसार अपडेट करें।

Halo-portal-client (portal frontend)

06_Keycloak

Valid redirect URIs: realm JSON में placeholder domain को अपने वास्तविक portal domain से बदलें। sample configuration में एक test domain उपयोग किया गया है (उदाहरण के लिए, https://pvetest.cdr.glasswall.dev/authentication/login-callback)। इस मान को उस URL से मेल खाने के लिए अपडेट करें जिसका उपयोग users आपके Halo portal तक पहुँचने के लिए करेंगे।

उदाहरण के लिए, यदि आपका Halo portal https://halo.dev.local/ पर उपलब्ध है और application का login callback path /authentication/login-callback है, तो सेट करें:

मान्य 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 उपयोगकर्ता बनाना और roles असाइन करना

अब आप उपयोगकर्ता बनाएंगे और Halo roles असाइन करेंगे।

09_Keycloak

A. glasswall realm में, Users → Add user पर जाएँ। B. Username और विवरण भरें। C. Credentials सेक्शन में, एक password सेट करें और "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 platform services (Portal, Portal-Access, API-Access) को Keycloak के प्रमाणपत्र पर trust होना चाहिए।

2.2 DNS और /etc/hosts

सुनिश्चित करें:

Keycloak hostname सभी services और users के लिए resolve हो
Halo domains भी resolve हों

चरण 3 - Keycloak SSO के साथ Halo services deploy करना (Helm configurations)

Halo को Helm के माध्यम से deploy किया जाता है; offline environments में system के साथ bundled charts का उपयोग किया जाता है।

Halo portal deploy करें

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 deploy करें

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 deploy करें

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 config दिखाई दे।

14_Keycloak

चरण 4 - SSO integration का सत्यापन और परीक्षण

15_Keycloak

A. Halo portal लॉन्च करें. B. Keycloak login पर रीडायरेक्ट हो जाएँ।

16_Keycloak

C. अपने खाते में साइन इन करें।

17_Keycloak

D. प्रमाणित होने के बाद Halo पर वापस लौटें।

18_Keycloak

चरण 5 - समस्या निवारण

गलत तरीके से कॉन्फ़िगर किया गया redirect URI

जाँचें कि portal और Keycloak के बीच URIs मेल खाते हैं।

क्लॉक स्क्यू

सिस्टम clocks को sync करें।

TLS trust त्रुटियाँ

सुनिश्चित करें कि Halo, Keycloak के cert पर trust करता है।

संदर्भ

Keycloak दस्तावेज़ीकरण

अवलोकन​

Glasswall Halo की Keycloak SSO Integration Guide​

पूर्वापेक्षाएँ​

Environment requirements​

आवश्यक संसाधन​

DNS/hosts कॉन्फ़िगरेशन​

चरण 1 - Glasswall Halo SSO के लिए Keycloak कॉन्फ़िगर करना​

1.1 - Glasswall realm configuration को import करना​

1.2 client settings को अनुकूलित करना (hostnames और redirect URIs)​

Halo-portal-client (portal frontend)​

Halo-portal-access (पोर्टल बैकएंड)​

Halo-API-access​

1.3 उपयोगकर्ता बनाना और roles असाइन करना​

चरण 2 - TLS प्रमाणपत्र और DNS संबंधी विचार​

2.1 TLS trust​

2.2 DNS और /etc/hosts​

चरण 3 - Keycloak SSO के साथ Halo services deploy करना (Helm configurations)​

Halo portal deploy करें​

portal-access deploy करें​

API-access deploy करें​

3.1 परिनियोजन के बाद की चेकलिस्ट​

चरण 4 - SSO integration का सत्यापन और परीक्षण​

4.1 ब्राउज़र लॉगिन परीक्षण​

चरण 5 - समस्या निवारण​

गलत तरीके से कॉन्फ़िगर किया गया redirect URI​

क्लॉक स्क्यू​

TLS trust त्रुटियाँ​

संदर्भ​