Keycloak SSO 統合

概要​

このガイドでは、オフライン（エアギャップ）なオンプレミス環境で、Keycloak Single Sign-On (SSO) を Glasswall Halo プラットフォームと統合するための手順を段階的に説明します。

このガイドは、すでに Single Node Halo プラットフォーム（例: Proxmox または ESXi 上の VM）をデプロイ済みで、これから Keycloak を使用した OIDC ベースの SSO を有効化したいことを前提としています。

以下を学習します:

• オフライン環境で HTTPS を使用して Keycloak サーバーをセットアップする（事前に読み込んだコンテナイメージまたは手動の VM インストールを使用）。
• 提供されている glasswall-realm.json の Keycloak 設定をインポートしてカスタマイズします。
• Keycloak と Halo の両方について、TLS 証明書と DNS/ホスト名解決を設定します。
• Deploy the Halo portal and related services:
  • cdrplatform-portal
  • cdrplatform-portalaccess
  • cdrplatform-api-access

Glasswall Halo の Keycloak SSO 統合ガイド​

• 前提条件
• ステップ 1 - Glasswall Halo SSO 向けの keycloak の設定
• ステップ 2 - TLS 証明書と DNS に関する考慮事項
• ステップ 3 - Keycloak SSO を使用した Halo サービスのデプロイ（Helm 構成）
• ステップ 4 - SSO 統合の検証とテスト
• ステップ 5 - トラブルシューティング

前提条件​

環境要件​

• このセットアップは、エアギャップ環境または厳格なオンプレミス環境を対象としています。
• Single Node Halo クラスターは、あらかじめデプロイされている必要があります。
• 内部 DNS 名前解決は、ローカル DNS サーバーを使用するか、/etc/hosts エントリを手動で設定することで、構成されている必要があります。
• Keycloak は、ホストまたは仮想マシン上にローカルでインストールされている必要があります。 → Keycloak のドキュメントとインストール

必要なリソース​

• 事前設定済みの realm ファイル（glasswall-realm.json）。これはGlasswall Supportから提供されます。
• Single Node Halo cluster 内にデプロイするための、Halo Helm charts へのローカルアクセス。

DNS/hosts の設定​

Keycloak サーバーの hostname が、クライアントマシンと Halo platform コンポーネントの両方から名前解決可能であることを確認してください。

• 内部 DNS を使用する場合: Keycloak サーバーの IP address を指す keycloak.dev.local の A record を作成します。
• 内部 DNS を使用しない場合: アクセスが必要な各マシンの hosts file に次のエントリを追加します:

ステップ 1 - Glasswall Halo SSO 向けの Keycloak の設定​

Glasswall は、Halo の SSO に必要な realm、clients、roles、scopes を定義した Keycloak realm configuration（JSON file として）を提供します。

手動設定を避けるために、この設定をインポートできます。オフライン環境では、Keycloak Admin UI からこれを実行します。

1.1 - Glasswall realm configuration のインポート​

A. realm export を取得する: glasswall-realm.json という名前の file があるはずです。この file には、Halo の SSO 用の realm settings が含まれています。

Glasswall realm の概要

Glasswall realm には、以下の事前設定済み項目が含まれています:

• Realm ID: Glasswall

• クライアント

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

• 主要なロール

  • レルムレベル: admin, user
  • クライアントレベル: Halo クライアントの admin および user ロール。
  • クライアントスコープ（mapper が事前設定済み）:
  • Portaluserscope: 必要なクレーム（roles、email）をトークンに追加します。

• トークンの有効期間

  • SSO セッションのアイドルタイムアウト: 30 分

• 認証: 標準のユーザー名/パスワード。

B. Keycloak Admin にログイン

• Web ブラウザーを使用して、https://<KEYCLOAK_HOST>:8443/ の Keycloak Admin Console にアクセスし、master admin アカウントでログインします。

C. レルムをインポート。

• admin console で現在 "Master" と表示されているドロップダウンを選択し、Create realm をクリックします。

• Create realm 画面で、Import を選択し、glasswall-realm.json ファイルをアップロードします。

• Keycloak will parse the file and populate the realm name (e.g.,glasswall).
  • インポートを確認します。

D. realm 設定を確認

• 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

1.2 クライアント設定のカスタマイズ（ホスト名とリダイレクト URI）​

次に、各 Halo クライアントについて、お使いの環境に合わせて設定を更新します。

Halo-portal-client（ポータル フロントエンド）​

Valid redirect URIs: realm JSON 内のプレースホルダー ドメインを実際のポータル ドメインに置き換えます。サンプル設定ではテスト用ドメイン（例: https://pvetest.cdr.glasswall.dev/authentication/login-callback）を使用しています。ユーザーが Halo ポータルへのアクセスに使用する URL に一致するよう、この値を更新してください。

たとえば、Halo ポータルが https://halo.dev.local/ で利用可能で、アプリケーションのログイン コールバック パスが /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

Halo-portal-access（ポータルバックエンド）​

• Valid redirect URIs: (e.g.,https://pvetest.cdr.glasswall.dev/*)
  • これをポータルのドメインに更新します。
• Web origins:https://halo.dev.local

Halo-API-access​

• リダイレクト設定はそのままにして、各クライアントの設定を保存します。

1.3 ユーザーの作成とロールの割り当て​

次に、ユーザーを作成し、Halo のロールを割り当てます。

A. glasswall realm で、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]

Admin ユーザーには次が表示されます:

また、次を管理できます:

以下を含みます:

ステップ 2 - TLS 証明書と DNS に関する考慮事項​

すべてのコンポーネントで適切な TLS 信頼と DNS を確保してください。

2.1 TLS 信頼​

Halo platform services（Portal、Portal-Access、API-Access）は、Keycloak の証明書を信頼している必要があります。

2.2 DNS と /etc/hosts​

以下を確認してください:

• Keycloak のホスト名がすべてのサービスおよびユーザーに対して名前解決されること
• Halo のドメインも名前解決されること

ステップ 3 - Keycloak SSO を使用した Halo services のデプロイ（Helm 構成）​

Halo は Helm を介してデプロイされます。オフライン環境では、システムにバンドルされた chart を使用します。

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

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 デプロイ後チェックリスト​

• Pod が実行中であることを確認します（CrashLoopBackOff になっていないこと）。
• ログに Keycloak OIDC の設定成功が表示されていることも確認します。

ステップ 4 - SSO 統合の検証とテスト​

4.1 ブラウザログインテスト​

A. Halo ポータルを起動します。 B. Keycloak のログイン画面にリダイレクトされます。

C. アカウントにサインインします。

D. 認証後に Halo に戻ります。

ステップ 5 - トラブルシューティング​

リダイレクト URI の設定ミス​

ポータルと Keycloak の間で URI が一致していることを確認します。

クロックスキュー​

システムクロックを同期します。

TLS 信頼エラー​

Halo が Keycloak の証明書を信頼していることを確認します。

参考資料​

• Keycloak ドキュメント