設定 Keycloak

了解如何設定和啟動 Keycloak

本指南說明 Keycloak 的設定方法，以及如何啟動和套用偏好的設定。它包含優化 Keycloak 以實現更快啟動和更低記憶體佔用的設定指南。

Keycloak 的設定來源

Keycloak 從四個來源載入設定，這些來源在此按應用順序列出。

  1. 命令列參數

  2. 環境變數

  3. 在 conf/keycloak.conf 檔案中定義的選項，或在使用者建立的設定檔中定義的選項。

  4. 在使用者建立的 Java 金鑰儲存檔案中定義的敏感選項。

當一個選項在多個來源中設定時，清單中第一個出現的來源決定該選項的值。例如，命令列參數設定的選項值優先於相同選項的環境變數。

範例：設定 db-url-host 參數

以下範例顯示如何在四個設定來源中設定 db-url 值

來源 格式

命令列參數

--db-url=cliValue

環境變數

KC_DB_URL=envVarValue

設定檔

db-url=confFileValue

Java 金鑰儲存檔案

kc.db-url=keystoreValue

根據應用優先順序，啟動時使用的值為 cliValue，因為命令列的優先順序最高。

如果未使用 --db-url=cliValue，則套用的值將為 KC_DB_URL=envVarValue。如果該值未透過命令列或環境變數套用，則會使用 db-url=confFileValue。如果沒有套用以上任何值，則會使用 kc.db-url=keystoreValue 的值，因為它在可用的設定來源中優先順序最低。

設定的格式

設定使用每個來源統一的格式，這簡化了從一個設定來源到另一個來源的鍵/值對的轉換。請注意，這些格式也適用於 spi 選項。

命令列參數格式

命令列的值使用 --<key-with-dashes>=<value> 格式。對於某些值，也存在 -<abbreviation>=<value> 簡寫。

環境變數格式

環境變數的值使用大寫的 KC_<key_with_underscores>=<value> 格式。

設定檔格式

進入設定檔的值使用 <key-with-dashes>=<value> 格式。

金鑰儲存設定檔格式

進入金鑰儲存設定檔的值使用 kc.<key-with-dashes> 格式。然後，<value> 是儲存在金鑰儲存中的密碼。

在每個設定指南的末尾，尋找「相關選項」標題，其中定義了適用的設定格式。如需所有設定選項，請參閱所有設定。選擇適用於您的使用案例的設定來源和格式。

範例 - 基於設定來源的替代格式

以下範例顯示三個設定來源的 db-url-host 設定格式

命令列參數
bin/kc.[sh|bat] start --db-url-host=mykeycloakdb
環境變數
export KC_DB_URL_HOST=mykeycloakdb
conf/keycloak.conf
db-url-host=mykeycloakdb

命令列參數的格式

Keycloak 包含許多用於設定的命令列參數。要查看可用的設定格式，請輸入以下命令

bin/kc.[sh|bat] start --help

或者，請參閱所有設定以取得所有伺服器選項。

環境變數的格式

您可以使用預留位置，透過使用 ${ENV_VAR} 語法，從 keycloak.conf 檔案內的環境變數解析特定環境的值

db-url-host=${MY_DB_HOST}

如果無法解析環境變數，您可以指定後備值。在 mydb 之前使用 : (冒號)，如下所示

db-url-host=${MY_DB_HOST:mydb}

包含特定設定檔的格式

預設情況下，伺服器始終從 conf/keycloak.conf 檔案中提取設定選項。對於新的安裝，此檔案僅包含註解設定，作為您在生產環境中執行時想要設定的建議。

您也可以使用 [-cf|--config-file] 選項，透過輸入以下命令來指定明確的設定檔位置

bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start

設定該選項會使 Keycloak 從指定的檔案讀取設定，而不是從 conf/keycloak.conf 讀取。

使用 Java 金鑰儲存檔案設定敏感選項

感謝金鑰儲存設定來源，您可以使用 [--config-keystore] 和 [--config-keystore-password] 選項直接從 Java 金鑰儲存載入屬性。或者，您可以使用 [--config-keystore-type] 選項指定金鑰儲存類型。預設情況下，金鑰儲存類型為 PKCS12。

金鑰儲存中的密碼需要使用 PBE（基於密碼的加密）金鑰演算法儲存，其中金鑰是從金鑰儲存密碼衍生而來的。您可以使用以下 keytool 命令產生此類金鑰儲存

keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v

執行命令後，系統會提示您輸入要儲存的密碼，這代表上述 kc.db-password 屬性的值。

建立金鑰儲存後，您可以使用以下參數啟動伺服器

bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=keystorepass --config-keystore-type=PKCS12

原始 Quarkus 屬性的格式

在大多數情況下，可用的設定選項應足以設定伺服器。但是，對於 Keycloak 設定中遺失的特定行為或功能，您可以使用基礎 Quarkus 框架的屬性。

如果可能，請避免直接使用 Quarkus 的屬性，因為 Keycloak 不支援它們。如果您的需求至關重要，請考慮先開啟一個增強要求。這種方法有助於我們改進 Keycloak 的設定以滿足您的需求。

如果無法提出增強要求，您可以使用原始 Quarkus 屬性設定伺服器

  1. 在 conf 目錄中建立 quarkus.properties 檔案。

  2. 在該檔案中定義所需的屬性。

    您只能使用在Quarkus 文件中定義的Quarkus 擴充功能子集。此外，請注意 Quarkus 屬性的以下差異

    • Quarkus 文件中 Quarkus 屬性的鎖定圖示表示建置時間屬性。您執行 build 命令以套用此屬性。如需有關 build 命令的詳細資訊，請參閱後續有關優化 Keycloak 的章節。

    • Quarkus 指南中沒有屬性的鎖定圖示表示 Quarkus 和 Keycloak 的執行時間屬性。

  3. 使用 [-cf|--config-file] 命令列參數來包含該檔案。

同樣地，您也可以將 Quarkus 屬性儲存在 Java 金鑰儲存中。

請注意，某些 Quarkus 屬性已對應在 Keycloak 設定中，例如 quarkus.http.port 和類似的基本屬性。如果 Keycloak 使用了該屬性，則在 quarkus.properties 中定義該屬性金鑰無效。Keycloak 設定值優先於 Quarkus 屬性值。

在值中使用特殊字元

Keycloak 依賴 Quarkus 和 MicroProfile 來處理設定值。請注意，支援值表達式。例如，${some_key} 會評估為 some_key 的值。

要停用表達式評估，\ 字元會用作逸出字元。特別是，當它們出現以定義表達式或重複時，必須使用它來逸出 $ 字元的使用。例如，如果您想要設定值 my$$password，請改用 my\$\$password。請注意，在大多數 unix shell 中使用時，或當它出現在屬性檔案中時，\ 字元需要額外的逸出或引用。例如，bash 單引號會保留單個反斜線 --db-password='my\$\$password'。此外，對於 bash 雙引號，您需要額外的反斜線 --db-password="my\\$\\$password"。同樣地，在屬性檔案中，也必須逸出反斜線字元：kc.db-password=my\\$\\$password

啟動 Keycloak

您可以在 開發模式 或 生產模式 中啟動 Keycloak。每種模式都為預期的環境提供不同的預設值。

在開發模式下啟動 Keycloak

首次試用 Keycloak 時使用開發模式，以便快速啟動並執行。此模式為開發人員提供方便的預設值，例如開發新的 Keycloak 主題。

若要在開發模式下啟動，請輸入以下命令

bin/kc.[sh|bat] start-dev
預設值

開發模式設定以下預設設定

  • 已啟用 HTTP

  • 已停用嚴格的主機名稱解析

  • 快取設定為本機（沒有用於高可用性的分散式快取機制）

  • 已停用主題快取和範本快取

在生產模式下啟動 Keycloak

在生產環境中部署 Keycloak 時使用生產模式。此模式遵循預設安全原則。

若要在生產模式下啟動，請輸入以下命令

bin/kc.[sh|bat] start

如果沒有進一步的設定，此命令將無法啟動 Keycloak，而是顯示錯誤。之所以如此回應，是因為 Keycloak 遵循預設安全原則。生產模式需要設定主機名稱，並且在啟動時必須提供 HTTPS/TLS 設定。

預設值

生產模式設定以下預設值

  • 由於傳輸層安全 (HTTPS) 至關重要，因此已停用 HTTP

  • 預期會有主機名稱設定

  • 預期會有 HTTPS/TLS 設定

在生產環境中部署 Keycloak 之前，請務必遵循設定 Keycloak 進行生產中概述的步驟。

預設情況下，生產模式的範例設定選項會在預設的 conf/keycloak.conf 檔案中註解掉。這些選項讓您了解在生產環境中執行 Keycloak 時要考慮的主要設定。

建立初始管理員使用者

您可以使用 Web 前端建立初始管理員使用者，您可以使用本機連線 (localhost) 存取該前端。您也可以使用環境變數建立此使用者。為初始管理員使用者名稱設定 KC_BOOTSTRAP_ADMIN_USERNAME=<username>，並為初始管理員密碼設定 KC_BOOTSTRAP_ADMIN_PASSWORD=<password>。

Keycloak 會在第一次啟動時剖析這些值，以建立具有管理權限的初始使用者。一旦存在具有管理權限的第一個使用者，您可以使用管理主控台或命令列工具 kcadm.[sh|bat] 來建立其他使用者。

如果初始管理員已存在，且環境變數在啟動時仍然存在，則會在記錄中顯示一則錯誤訊息，指出建立初始管理員失敗。Keycloak 會忽略這些值並正確啟動。

最佳化 Keycloak 啟動

我們建議您在生產環境中部署 Keycloak 之前，先最佳化 Keycloak，以提供更快的啟動速度和更好的記憶體消耗。本節說明如何套用 Keycloak 最佳化，以獲得最佳效能和執行時間行為。

建立最佳化的 Keycloak 組建

預設情況下，當您使用 start 或 start-dev 命令時，Keycloak 為了方便起見，會在底層執行 build 命令。

這個 build 命令會執行一組針對啟動和執行時行為的優化。建置過程可能需要幾秒鐘。尤其是在 Kubernetes 或 OpenShift 等容器化環境中執行 Keycloak 時，啟動時間非常重要。為了避免浪費時間，請在啟動之前顯式執行 build，例如在 CI/CD 管道中的一個獨立步驟。

第一步：顯式執行建置

若要執行 build，請輸入以下命令

bin/kc.[sh|bat] build <build-options>

此命令會顯示您輸入的 build options。Keycloak 區分 建置選項 (build options)（在執行 build 命令時可用）和 組態選項 (configuration options)（在啟動伺服器時可用）。

對於 Keycloak 的非最佳化啟動，此區別沒有影響。但是，如果您在啟動前執行建置，則只有一部分選項可用於建置命令。此限制是因為建置選項會被持久化到最佳化的 Keycloak 映像中。例如，為了安全起見，db-password 等憑證的組態（屬於組態選項）不得持久化。

所有建置選項都以純文字形式持久化。請勿將任何敏感資料儲存為建置選項。這適用於所有可用的組態來源，包括 KeyStore 組態來源。因此，我們也不建議將任何建置選項儲存在 Java 金鑰庫中。此外，關於組態選項，我們建議主要使用 KeyStore 組態來源來儲存敏感資料。對於非敏感資料，您可以使用其餘的組態來源。

建置選項在所有組態中以工具圖示標記。若要尋找可用的建置選項，請參閱選取建置選項的所有組態頁面或輸入以下命令

bin/kc.[sh|bat] build --help
範例：在啟動前執行 build 以將資料庫設定為 PostgreSQL
bin/kc.[sh|bat] build --db=postgres

第二步：使用 --optimized 啟動 Keycloak

成功建置後，您可以啟動 Keycloak 並關閉預設啟動行為，方法是輸入以下命令

bin/kc.[sh|bat] start --optimized <configuration-options>

--optimized 參數會告知 Keycloak 假設正在使用預先建置且已最佳化的 Keycloak 映像。因此，Keycloak 會避免在啟動時直接檢查和執行建置，從而節省時間。

您可以在啟動時輸入所有組態選項；這些選項是在所有組態中 未 以工具圖示標記的選項。

  • 如果在啟動時發現建置選項的值與輸入 build 時使用的值相同，則在使用 --optimized 參數時，該選項會被靜默忽略。

  • 如果該選項的值與輸入建置時使用的值不同，則會在記錄檔中顯示警告，並且會使用先前建置的值。若要使此值生效，請在啟動前執行新的 build。

建立最佳化建置

以下範例說明如何建立最佳化建置，然後在啟動 Keycloak 時使用 --optimized 參數。

  1. 使用建置命令設定 PostgreSQL 資料庫供應商的建置選項

    bin/kc.[sh|bat] build --db=postgres

  2. 在 conf/keycloak.conf 檔案中設定 postgres 的執行階段組態選項。

    db-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.com
https-certificate-file

  3. 使用 optimized 參數啟動伺服器

    bin/kc.[sh|bat] start --optimized

透過使用 build 命令，您可以實現大多數啟動和執行階段行為的最佳化。此外，透過使用 keycloak.conf 檔案作為組態來源，您可以避免啟動時的一些步驟，否則這些步驟將需要命令列參數，例如初始化 CLI 本身。因此，伺服器啟動速度會更快。

底層概念

本節概述 Keycloak 使用的底層概念，尤其是在最佳化啟動方面。

Keycloak 在底層使用 Quarkus 框架和重新增強/可變 jar 方法。當執行 build 命令時，就會啟動這個過程。

以下是 build 命令執行的一些最佳化

  • 建立關於已安裝供應商的新封閉世界假設，這表示不需要在每次 Keycloak 啟動時重新建立登錄檔並初始化工廠。

  • 會預先剖析組態檔，以減少啟動伺服器時的 I/O。

  • 會設定和準備資料庫特定資源，以針對特定資料庫供應商執行。

  • 透過將建置選項持久化到伺服器映像中，伺服器不會執行任何額外步驟來解譯組態選項和 (重新) 設定自身。

您可以在特定的 Quarkus 指南 中閱讀更多內容

本頁面
編輯本指南