spi-<spi-id>-<provider-id>-<property>=<value>
伺服器的建構理念是以可擴展性為核心,為此它提供了許多服務供應商介面 (Service Provider Interfaces, SPI),每個介面負責為伺服器提供特定的功能。在本指南中,您將了解圍繞 SPI 及其各自供應商配置的核心概念。
閱讀本指南後,您應該能夠運用本文解釋的概念和步驟來安裝、解除安裝、啟用、停用和設定任何供應商,包括您為了更好地滿足您的需求而實作以擴展伺服器功能的供應商。
可以使用特定的配置格式來設定供應商。此格式包含:
spi-<spi-id>-<provider-id>-<property>=<value>
<spi-id>
是您要設定的 SPI 的名稱。
<provider-id>
是您要設定的供應商的 ID。這是設定給對應供應商工廠實作的 ID。
<property>
是您要為給定供應商設定的屬性的實際名稱。
所有這些名稱(用於 spi、供應商和屬性)都應為小寫,如果名稱採用駝峰式命名法,例如 myKeycloakProvider
,則應在每個大寫字母前加上破折號 (-
),如下所示: my-keycloak-provider
。
以 HttpClientSpi
SPI 為例,SPI 的名稱為 connectionsHttpClient
,其中一個可用的供應商實作名稱為 default
。為了設定 connectionPoolSize
屬性,您將使用如下的設定選項:
spi-connections-http-client-default-connection-pool-size=10
供應商設定選項在啟動伺服器時提供。請參閱 設定 Keycloak 中關於選項的所有支援設定來源和格式。例如,透過命令列選項:
connections-http-client
SPI 的 default
供應商設定 connection-pool-size
bin/kc.[sh|bat] start --spi-connections-http-client-default-connection-pool-size=10
根據 SPI 的不同,多個供應商實作可以同時存在,但運行時只會使用其中一個。對於這些 SPI,特定的供應商是主要實作,將在運行時被啟用和使用。
若要將供應商設定為單一供應商,您應該執行 build
命令,如下所示:
mycustomprovider
供應商標記為 email-template
SPI 的單一供應商bin/kc.[sh|bat] build --spi-email-template-provider=mycustomprovider
根據 SPI 的不同,多個供應商實作可以同時存在,且其中一個預設使用。對於這些 SPI,特定的供應商是預設實作,除非請求特定供應商,否則將會被選中。
以下邏輯用於判斷預設供應商:
明確設定的預設供應商
順序最高的供應商(順序 ⇐ 0 的供應商會被忽略)
ID 設定為 default
的供應商
若要將供應商設定為預設供應商,您應該執行 build
命令,如下所示:
mycustomhash
供應商標記為 password-hashing
SPI 的預設供應商bin/kc.[sh|bat] build --spi-password-hashing-provider-default=mycustomprovider
若要啟用或停用供應商,您應該執行 build
命令,如下所示:
bin/kc.[sh|bat] build --spi-email-template-mycustomprovider-enabled=true
若要停用供應商,請使用相同的命令,並將 enabled
屬性設定為 false
。
自訂供應商應打包在 Java 歸檔 (JAR) 檔案中,並複製到發行版本的 providers
目錄。之後,您必須執行 build
命令,以便使用 JAR 檔案中的實作更新伺服器的供應商註冊表。
此步驟是為了最佳化伺服器運行時,以便預先知道所有供應商,而不是僅在啟動伺服器或運行時才發現。
若要解除安裝供應商,您應該從 providers
目錄中移除 JAR 檔案,然後再次執行 build
命令。
實作供應商時,您可能需要使用伺服器發行版本中未提供的協力廠商相依性。
在這種情況下,您應該將任何其他相依性複製到 providers
目錄,並執行 build
命令。執行此操作後,伺服器會在運行時讓這些額外的相依性可供任何依賴它們的供應商使用。