設定主機名稱 (v2)

了解如何設定 Keycloak 所公開的前端和後端通道端點。

設定主機名稱選項的重要性

預設情況下，Keycloak 強制設定 hostname 選項，且不會動態解析 URL。這是一項安全措施。

Keycloak 會自由公開其自身的 URL，例如透過 OIDC Discovery 端點，或作為電子郵件中重設密碼連結的一部分。如果主機名稱是從主機名稱標頭動態解譯，則可能會讓潛在的攻擊者有機會操縱電子郵件中的 URL，將使用者重新導向至攻擊者的偽造網域，並竊取敏感資料，例如操作權杖、密碼等。

透過明確設定 hostname 選項，我們可以避免由詐欺發行者發行權杖的情況。可以使用以下命令，以明確的主機名稱啟動伺服器

bin/kc.[sh|bat] start --hostname my.keycloak.org
這些範例會在生產模式下啟動 Keycloak 實例，這需要公用憑證和私密金鑰才能保護通訊。如需更多資訊，請參閱為生產環境設定 Keycloak。

定義主機名稱選項的特定部分

如先前的範例所示，不需要明確指定 scheme 和 port。在這種情況下，Keycloak 會自動處理這些方面。例如，在給定的範例中，伺服器將可透過 https://my.keycloak.org:8443 存取。但是，反向代理通常會以預設的 port (例如 443) 公開 Keycloak。在這種情況下，最好在 hostname 選項中指定完整的 URL，而不是保持 URL 的部分動態。然後可以使用以下方式啟動伺服器

bin/kc.[sh|bat] start --hostname https://my.keycloak.org

同樣地，您的反向代理可能會在不同的內容路徑上公開 Keycloak。可以透過 hostname 和 hostname-admin 選項設定 Keycloak 來反映這一點。請參閱以下範例

bin/kc.[sh|bat] start --hostname https://my.keycloak.org:123/auth

利用內部 URL 進行客戶端之間的通訊

Keycloak 具有為後端通道請求提供個別 URL 的功能，允許內部通訊，同時為前端通道請求保持使用公用 URL。此外，後端通道會根據傳入的標頭動態解析。請考慮以下範例

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic true

透過這種方式，您的應用程式 (稱為客戶端) 可以透過您的本機網路與 Keycloak 連線，同時伺服器仍可透過 https://my.keycloak.org 公開存取。

使用邊緣 TLS 終止

如您所見，HTTPS 協定是預設的選擇，符合 Keycloak 對安全最佳實務的承諾。但是，Keycloak 也為使用者提供了在必要時選擇 HTTP 的彈性。只需指定 HTTP 接聽程式即可達成此目的，請參閱設定 TLS 以了解詳細資訊。使用邊緣 TLS 終止代理，您可以按如下方式啟動伺服器

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --http-enabled true

此設定的結果是，您可以繼續透過 HTTPS 在 https://my.keycloak.org 存取 Keycloak，同時代理使用 HTTP 和 port 8080 與實例互動。

使用反向代理

當代理轉發 http 或重新加密的 TLS 請求時，應設定 proxy-headers 選項。根據主機名稱設定，可能會動態判斷部分或全部 URL。

如果選取 forwarded 或 xforwarded，請確保您的反向代理正確設定並覆寫 Forwarded 或 X-Forwarded-* 標頭。若要設定這些標頭，請參閱反向代理的文件。設定錯誤會讓 Keycloak 暴露於安全漏洞。

完全動態的 URL。

例如，如果您的反向代理正確設定了 Forwarded 標頭，且您不想硬式編碼主機名稱，Keycloak 可以容納這一點。您只需按如下方式啟動伺服器

bin/kc.[sh|bat] start --hostname-strict false --proxy-headers forwarded

使用此設定，伺服器會遵循 Forwarded 標頭所設定的值。這也表示所有端點都會動態解析。

部分動態的 URL

當未將 hostname 選項指定為完整 URL 時，也可以使用 proxy-headers 選項來部分動態解析 URL。例如

bin/kc.[sh|bat] start --hostname my.keycloak.org --proxy-headers xforwarded

在這種情況下，scheme、port 和內容路徑會從 X-Forwarded-* 標頭動態解析，而主機名稱則會靜態定義為 my.keycloak.org。

固定的 URL

即使將 hostname 設定為完整 URL，proxy-headers 仍然相關，因為標頭是用來判斷請求的來源。例如

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --proxy-headers xforwarded

在這種情況下，雖然沒有從 X-Forwarded-* 標頭動態解析任何內容，但 X-Forwarded-* 標頭是用來判斷請求的正確來源。

在個別主機名稱上公開管理主控台

如果您希望在不同的主機上公開管理主控台，可以使用以下命令執行此操作

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443

這可讓您在 https://my.keycloak.org 存取 Keycloak，並在 https://admin.my.keycloak.org:8443 存取管理主控台，同時後端繼續使用 https://my.keycloak.org。

請記住，主機名稱和代理選項不會變更伺服器接聽的 port。相反地，它只會變更靜態資源的 port，例如 JavaScript 和 CSS 連結、OIDC 已知端點、重新導向 URI 等，這些資源將在代理前面使用。您需要使用 HTTP 設定選項來變更伺服器接聽的實際 port。如需詳細資訊，請參閱所有設定。
使用 hostname-admin 選項並不會阻止透過 hostname 選項指定的前端 URL 存取管理 REST API 端點。如果您想要限制對管理 REST API 的存取，您需要在反向代理層級執行此操作。管理主控台會使用 hostname-admin 選項指定的 URL，隱式存取 API。

背景 - 伺服器端點

Keycloak 公開多個端點，每個端點都有不同的用途。它們通常用於應用程式之間的通訊或管理伺服器。我們識別出 3 個主要的端點群組

  • 前端

  • 後端

  • 管理

如果您想要使用這些端點的任何一個，您需要設定基本 URL。基本 URL 由幾個部分組成

  • scheme (例如 https 協定)

  • 主機名稱 (例如 example.keycloak.org)

  • port (例如 8443)

  • 路徑 (例如 /auth)

每個群組的基本 URL 對於權杖的發行和驗證方式、對於需要將使用者重新導向至 Keycloak 的動作 (例如，透過電子郵件連結重設密碼時) 建立連結的方式，以及最重要的是，應用程式在從 realms/{realm-name}/.well-known/openid-configuration 擷取 OpenID Connect Discovery 文件時如何探索這些端點，具有重要的影響。

前端

使用者和應用程式使用前端 URL 透過前端通道存取 Keycloak。前端通道是公開可存取的通訊通道。例如，基於瀏覽器的流程 (存取登入頁面、按一下重設密碼的連結或繫結權杖) 可以視為前端通道請求。

為了使 Keycloak 可透過前端 URL 存取，您需要設定 hostname 選項

bin/kc.[sh|bat] start --hostname my.keycloak.org

後端

後端端點是那些可透過公用網域或透過私有網路存取的端點。它們與 Keycloak 與客戶端 (由 Keycloak 保護的應用程式) 之間的直接後端通訊相關。這種通訊可能透過本機網路進行，避免了反向代理。屬於此群組的端點範例包括授權端點、權杖和權杖內省端點、userinfo 端點、JWKS URI 端點等。

hostname-backchannel-dynamic 選項的預設值為 false，這表示後端通道 URL 與前端通道 URL 相同。可以透過設定以下選項，啟用從傳入請求標頭動態解析後端通道 URL

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-backchannel-dynamic true

請注意，hostname 選項必須設定為 URL。如需更多資訊，請參閱下方的 驗證 章節。

管理

與基本前端 URL 類似，您也可以設定管理主控台資源和端點的基本 URL。伺服器會使用特定的 URL 公開管理主控台和靜態資源。此 URL 用於重新導向 URL、載入資源 (CSS、JS)、管理 REST API 等。可以透過設定 hostname-admin 選項來達成此目的

bin/kc.[sh|bat] start --hostname https://my.keycloak.org --hostname-admin https://admin.my.keycloak.org:8443

同樣地，hostname 選項必須設定為 URL。如需更多資訊，請參閱下方的 驗證 章節。

解析 URL 的來源

如先前章節所述，URL 可以透過幾種方式解析：它們可以動態產生、硬式編碼或兩者的組合

  • 從傳入請求動態解析

    • Host 標頭、scheme、伺服器 port、內容路徑

    • 代理設定的標頭：Forwarded 和 X-Forwarded-*

  • 硬式編碼

    • 伺服器範圍的設定 (例如 hostname、hostname-admin 等)

    • 前端 URL 的領域設定

驗證

  • 驗證 hostname URL 和 hostname-admin URL 使用完整 URL，包括 scheme 和主機名稱。port 僅在存在時才驗證，否則會假設指定協定的預設 port (80 或 443)。

  • 在生產設定檔 (kc.sh|bat start) 中，必須明確設定 --hostname 或 --hostname-strict false。

    • 這不適用於開發設定檔 (kc.sh|bat start-dev)，其中 --hostname-strict false 是預設值。

  • 如果未設定 --hostname

    • hostname-backchannel-dynamic 必須設定為 false。

    • hostname-strict 必須設定為 false。

  • 如果設定了 hostname-admin，則 hostname 必須設定為 URL (而不只是主機名稱)。否則，Keycloak 將無法知道存取管理主控台時正確的前端 URL (包括 port 等)。

  • 如果將 hostname-backchannel-dynamic 設定為 true，則 hostname 必須設定為 URL (而不只是主機名稱)。否則，當透過動態解析的後端通道存取時，Keycloak 將無法知道正確的前端 URL (包括 port 等)。

此外，如果設定了主機名稱，則會忽略 hostname-strict。

疑難排解

若要對主機名稱設定進行疑難排解，您可以使用專用的偵錯工具，其可啟用為

Keycloak 設定
bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-debug=true

Keycloak 正確啟動後，開啟您的瀏覽器並前往：http://mykeycloak:8080/realms/<your-realm>/hostname-debug

相關選項

表 1. 預設情況下，此端點為停用狀態 (--hostname-debug=false)
數值

hostname

伺服器對外公開的位址。

可以是完整 URL，或僅是主機名稱。當僅提供主機名稱時，協定、連接埠和上下文路徑會從請求中解析。

CLI: --hostname
Env: KC_HOSTNAME

僅當啟用 hostname:v2 功能時可用

hostname-admin

用於存取管理控制台的位址。

如果您使用與 hostname 選項中指定的不同位址上的反向代理公開管理控制台，請使用此選項。

CLI: --hostname-admin
Env: KC_HOSTNAME_ADMIN

僅當啟用 hostname:v2 功能時可用

hostname-backchannel-dynamic

啟用後端通道 URL 的動態解析，包括主機名稱、協定、連接埠和上下文路徑。

如果您的應用程式透過私有網路存取 Keycloak，請設定為 true。如果設定為 true，則 hostname 選項需要指定為完整 URL。

CLI: --hostname-backchannel-dynamic
Env: KC_HOSTNAME_BACKCHANNEL_DYNAMIC

僅當啟用 hostname:v2 功能時可用

true、false (預設)

hostname-debug

切換主機名稱偵錯頁面，該頁面可透過 /realms/master/hostname-debug 存取。

CLI: --hostname-debug
Env: KC_HOSTNAME_DEBUG

僅當啟用 hostname:v2 功能時可用

true、false (預設)

hostname-strict

停用從請求標頭動態解析主機名稱。

在生產環境中應始終設定為 true，除非您的反向代理覆寫了 Host 標頭。如果啟用，則需要指定 hostname 選項。

CLI: --hostname-strict
Env: KC_HOSTNAME_STRICT

僅當啟用 hostname:v2 功能時可用

true (預設), false
在此頁面
編輯本指南