升級指南

編列是將 Java 物件轉換成位元組，以在 Keycloak 伺服器之間透過網路傳送它們的程序。在 Keycloak 26 中，編列程式庫已從 JBoss 編列變更為 Infinispan Protostream。這些程式庫彼此不相容，而且需要一些步驟來確保工作階段資料不會遺失。

為了防止遺失使用者工作階段，請先升級至 Keycloak 25，然後啟用 Keycloak 25 的遷移指南中概述的永久工作階段功能。

運算子不再預設為 proxy=passthrough 的主機名稱 v1 設定。這允許使用主機名稱 v2 的部署，以在沒有其他選項的情況下，按照預期方式運作的固定邊緣主機名稱。

下列方法已新增至 org.keycloak.cluster.ClusterProvider

當多個事件傳送至相同的 taskKey 時，這個方法會批次處理事件，並僅執行單一網路呼叫。這是一個最佳化方法，可減少流量和與網路相關的資源。

在 Keycloak 26 中，新的方法具有預設實作，以保持與自訂實作的向後相容性。預設實作會對每個事件執行單一網路呼叫，而且它將在未來版本的 Keycloak 中移除。

為了提高群組的延展性，現在移除網域時會直接從資料庫中移除它們。因此，當移除網域時，不再觸發群組相關事件，例如 GroupRemovedEvent。

如果您有延伸模組在移除網域時處理任何群組相關事件，請務必改為使用 RealmRemovedEvent，以在移除網域及其群組時執行任何清除或自訂處理。

GroupProvider 介面也會更新為新的 preRemove(RealmModel) 方法，以強制實作在移除網域時正確處理群組的移除。

指定 http-relative-path 屬性時，使用者會自動重新導向至 Keycloak 主機的路徑。這表示當相對路徑設定為 /auth，且使用者存取 localhost:8080/ 時，頁面會重新導向至 localhost:8080/auth。

當指定 http-management-relative-path 或 http-relative-path 屬性時，管理介面也會套用相同的情況。

這可改善使用者體驗，因為使用者不再需要將相對路徑明確設定為 URL。

現在 Keycloak Pod 將具有預設關聯性，以防止來自相同 CR 的多個執行個體部署在相同的節點上，且來自相同 CR 的所有 Pod 將優先位於相同的區域中，以防止延伸快取叢集。

為了遵循最佳做法，已導入運算子的預設 CPU 和記憶體限制/要求。它會影響非 OLM 和 OLM 安裝。若要覆寫 OLM 安裝的預設值，請編輯運算子的訂閱中的 resources 區段。

下列項目已過時，將在即將推出的 Keycloak 版本中移除，且沒有替代項目

org.keycloak.common.util.Encode 現在始終對 URL 編碼使用 UTF-8 字元集，而不是隱含地依賴 file.encoding 系統屬性。

在此版本中，LDAP 連線集區設定僅依賴系統屬性。主要原因是 LDAP 連線集區設定是 JVM 層級設定，而不是特定於個別網域或 LDAP 提供者執行個體。

與先前的版本相比，任何與 LDAP 連接池相關的 realm 配置都將被忽略。如果您是從先前的版本遷移，並且在您的 LDAP 提供者中設定了以下任何設定，請考慮改用系統屬性。

如需更多詳細資訊，請參閱設定連線池。

此版本引入了為 base/login 和 keycloak.v2/login 主題的登入頁面輕鬆新增自訂頁尾的功能。為了使用自訂頁尾，請在您的自訂登入主題中建立一個包含所需內容的 footer.ftl 檔案。

如需更多詳細資訊，請參閱將自訂頁尾新增至登入主題。

在此版本中，預設情況下，當使用嵌入式快取時，撤銷的存取權杖會寫入資料庫，並在叢集重新啟動時重新載入。

若要停用此行為，請使用 所有提供者設定 指南中概述的 SPI 選項 spi-single-use-object-infinispan-persist-revoked-tokens。

SingleUseObjectProvider 的 SPI 行為已變更，對於撤銷的權杖，僅必須使用 put 和 contains 方法。這是預設強制執行的，可以使用 SPI 選項 spi-single-use-object-infinispan-persist-revoked-tokens 來停用。

Keycloak 26 對建議的 HA 多站點架構進行了重大改進，最值得注意的是：

由於上述變更，您現有的 Keycloak 部署需要進行以下變更。

如果您在單站點設定中使用外部 Infinispan，則先前的 Keycloak 版本不支援此功能，Keycloak 26 也不支援此功能。為了保護使用者避免意外地透過 Keycloak 快取 XML 中的手動設定或透過 CLI 選項來使用它，現在會使用功能標誌 cache-embedded-remote-store 來保護它。它被標記為實驗性功能，因此不受支援。除非啟用此實驗性功能，否則 Keycloak 26 不會以這種設定啟動，而是會顯示錯誤。

如果您一直使用外部 Infinispan 來保持使用者在重新啟動和升級之間登入，請改用預設啟用的 persistent-user-sessions 功能。然後不再需要外部 Infinispan。

實驗性功能 cache-embedded-remote-store 將在未來的次要版本中移除。

當所有管理員使用者都被鎖定時，以前很難重新取得 Keycloak 執行個體的存取權。此過程需要多個進階步驟，包括直接資料庫存取和手動變更。為了改善使用者體驗，Keycloak 現在提供了多種引導新管理員帳戶的方式，這些方式可用於從此類情況中復原。

因此，環境變數 KEYCLOAK_ADMIN 和 KEYCLOAK_ADMIN_PASSWORD 已被棄用。您應該改用 KC_BOOTSTRAP_ADMIN_USERNAME 和 KC_BOOTSTRAP_ADMIN_PASSWORD。這些也是一般選項，因此可以透過 cli 或其他配置來源指定，例如 --bootstrap-admin-username=admin。如需更多資訊，請參閱新的 引導管理員和復原 指南。

現在，當從應用程式啟動的必要操作執行重新導向時，必要操作提供者名稱會透過 kc_action 參數傳回。這有助於偵測為客戶端執行了哪個必要操作。執行的結果可以透過 kc_action_status 參數確定。

注意：此功能需要變更 Keycloak JS 配接器，因此建議您升級到最新版本的配接器，如果您想要使用此功能。

UserSessionCrossDCManager 類別已被棄用，並計劃在 Keycloak 的未來版本中移除。請閱讀 UserSessionCrossDCManager Javadoc 以取得要使用的替代方法。

作為改善 realm 和組織在擁有許多身分提供者時的可擴展性的一部分，realm 表示法不再保留身分提供者的清單。但是，在匯出 realm 時，它們仍然可以從 realm 表示法中取得。

若要取得查詢 realm 中的身分提供者，請優先使用 /realms/{realm}/identity-provider/instances 端點。此端點支援篩選器和分頁。

CLI 命令 kc.[sh|bat] import 現在已啟用預留位置替換。先前預留位置替換僅在啟動時為 realm 匯入啟用。

如果您希望停用 import 命令的預留位置替換，請新增系統屬性 -Dkeycloak.migration.replace-placeholders=false

RealmProvider Java API 現在包含一個新的方法 Stream<RealmModel> getRealmsStream(String search)，它允許依名稱搜尋 realm。雖然有一個預設的實作在從提供者載入後篩選串流，但鼓勵實作提供更有效率的實作。

Keycloak 現在根據副檔名來決定金鑰儲存區和信任儲存區的格式。如果副檔名是 .p12、.pkcs12 或 .pfx，則格式為 PKCS12。如果副檔名是 .jks、.keystore 或 .truststore，則格式為 JKS。如果副檔名是 .pem、.crt 或 .key，則格式為 PEM。

您仍然可以明確指定 https-key-store-type 和 https-trust-store-type 來覆寫自動偵測。這也適用於管理介面及其 https-management-key-store-type。FIPS 嚴格模式的限制保持不變。

已將新的索引新增至 IDENTITY_PROVIDER 資料表，以改善擷取與組織相關聯的 IDP 的查詢效能，並擷取可用於登入的 IDP（已啟用、不是 link_only、未標記為 hide_on_login 的 IDP）。

如果資料表目前包含超過 300,000 個條目，Keycloak 預設會在自動架構遷移期間跳過建立索引，而是在遷移期間將 SQL 陳述式記錄在主控台上。在這種情況下，必須在 Keycloak 啟動後在資料庫中手動執行陳述式。

此外，kc.org 和 hideOnLoginPage 設定屬性已遷移到身分提供者本身，以便在搜尋提供者時允許更有效率的查詢。因此，API 用戶端應使用 IdentityProviderRepresentation 中的 getOrganizationId/setOrganizationId 和 isHideOnLogin/setHideOnLogin 方法，並避免使用現在已被棄用的舊版設定屬性來設定這些屬性。

GELF 支援已棄用一段時間，在此版本中，它最終已從 Keycloak 中移除。其他記錄處理常式可用且完全支援用來替代 GELF，例如 Syslog。如需詳細資訊，請參閱 記錄指南。

keycloak 主題的 common 資源的一些路徑已變更，特別是協力廠商程式庫的資源。請務必據此更新您的自訂主題

此外，以下資源已從 common 主題中移除

如果您先前在您的主題中使用任何已移除的資源，請務必將它們新增到您自己的主題資源中。

Keycloak 預設不使用 XA 資料來源。但是，如果使用多個資料來源，這被認為是不安全的。從此版本開始，如果您要向 Keycloak 新增額外的資料來源，則需要使用 XA 資料來源。如果預設資料來源支援 XA，您可以使用設定 --transaction-xa-enabled=true 選項來達成。對於額外的資料來源，您需要在您的 quarkus.properties 檔案中使用 quarkus.datasource.<您的資料來源名稱>.jdbc.transactions=xa 選項。最多只能有一個資料來源是非 XA。當您沒有交易儲存的持久性儲存時，不支援復原。

已移除已棄用的主機名稱 v1 功能。此功能已在 Keycloak 25 中棄用，並由主機名稱 v2 取代。如果您仍在使用此功能，則必須遷移到主機名稱 v2。有關詳細資訊，請參閱設定主機名稱 (v2) 和 初始遷移指南。

已移除已棄用的 proxy 選項。此選項已在 Keycloak 24 中棄用，並由 proxy-headers 選項與需要時的主機名稱選項組合取代。有關詳細資訊，請參閱使用反向 Proxy 和 初始升級指南。

由於資料庫現在是使用者會期的真實來源，因此可以限制會期快取的大小以減少記憶體使用量。如果您使用預設的 conf/cache-ispn.xml 檔案，用於儲存使用者和用戶端會期的快取預設設定為僅儲存 10000 個會期和每個條目的一個擁有者。

使用與下方所示類似的組態來更新您的自訂嵌入式 Infinispan 快取組態檔案，適用於快取 sessions、clientSessions、offlineSessions 和 offlineClientSessions

有關詳細資訊，請繼續閱讀設定分散式快取指南。

先前版本的 Keycloak 為使用者和用戶端會期的閒置時間增加兩分鐘的寬限期。這是由於先前的架構在叢集中非同步複製會期重新整理時間。使用持久性使用者會期，這不再必要，因此現在已移除寬限期。

要保留舊的行為，請更新您的領域組態並將會期和用戶端閒置時間延長兩分鐘。

先前版本的 Keycloak 支援使用者自動登出並透過開啟登出端點 URL（例如 http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri）重新導向至應用程式。此功能已在 Keycloak 18 中棄用，並在此版本中移除，以支援遵循 OpenID Connect 規格。

作為此變更的一部分，以下相關的 SPI 組態選項已被移除

如果您仍然使用這些選項或用於登出的 redirect_uri 參數，則應改為實作OpenID Connect RP 起始登出規格。

現在，--optimized 啟動選項要求必須先建置最佳化伺服器映像。這可以透過先執行 kc.sh|bat build 或任何其他不含 --optimized 旗標的伺服器命令（例如 start、export、import）來達成。

已移除 org.keycloak.bom:keycloak-adapter-bom 和 org.keycloak.bom:keycloak-misc-bom BOM 檔案。配接器 BOM 已不再有用，因為大多數 Java 配接器已移除。雜項 BOM 僅包含一個成品，keycloak-test-helper，並且該成品也在此版本中移除。

此版本已移除 Maven 成品 org.keycloak:keycloak-test-helper。該成品提供了幾個用於處理 Java 管理用戶端的輔助方法。如果您使用輔助方法，可以根據需要在您的應用程式中分支它們。

此版本已移除 JEE 管理用戶端。我們仍然支援 Jakarta 管理用戶端。

現在有更新 (UPDATE_CREDENTIAL) 和移除 (REMOVE_CREDENTIAL) 憑證的通用事件。憑證類型在事件的 credential_type 屬性中描述。電子郵件事件接聽器支援新的事件類型。

以下事件類型現在已棄用，並將在未來的版本中移除：UPDATE_PASSWORD、UPDATE_PASSWORD_ERROR、UPDATE_TOTP、UPDATE_TOTP_ERROR、REMOVE_TOTP、REMOVE_TOTP_ERROR

當在主領域存在之前使用 --import-realm 選項執行 start 或 start-dev 命令時，如果匯入材料中存在主領域，則會匯入該主領域。先前的行為是先建立主領域，然後略過其匯入。

現在使用 BouncyCastle FIPS 程式庫的第 2 版測試並支援我們的 FIPS 140-2 整合。此版本已通過 Java 21 認證。如果您使用 FIPS 140-2 整合，建議您將 BouncyCastle FIPS 程式庫升級到最新文件中提到的版本。

BouncyCastle FIPS 第 2 版已通過 FIPS 140-3 認證。因此，只要在符合 FIPS 140-3 標準的系統上使用 Keycloak，Keycloak 就可以符合 FIPS 140-3 標準。這可能是基於 RHEL 9 的系統，其本身符合 FIPS 140-3 標準。但請注意，基於 RHEL 8 的系統僅通過 FIPS 140-2 認證。

已從基於 JavaScript 的管理用戶端中移除 groups.setOrCreateChild() 方法。如果您仍然使用此方法，請改為使用 createChildGroup() 或 updateChildGroup() 方法。

此版本包括 Keycloak JS 程式庫的幾項變更，應予以考量。這些變更的主要動機是將程式庫與 Keycloak 伺服器分離，以便可以獨立重構程式庫，簡化程式碼並使其更容易在未來維護。變更如下

當提供的建置時選項在啟動時與上次最佳化 Keycloak 建置期間儲存在伺服器映像中的值不同時，Keycloak 現在將無法啟動。先前，在這種情況下會顯示警告訊息。

透過功能版本，功能 account3、admin2 和 login2 已重新命名。停用功能時，無需使用版本，例如，現在使用 --features-disabled=admin 停用管理主控台。

若要使用特定版本的 login，請使用 --features=login:v1。

如果攻擊者並行發起多次登入嘗試，那麼攻擊者猜測密碼的次數可能會超過暴力破解保護設定所允許的次數。這是因為暴力破解檢查發生在暴力破解保護器鎖定使用者之前。為了防止這種競爭情況，暴力破解保護器現在會拒絕在同一伺服器中另一個登入正在進行時發生的所有登入嘗試。

如果因為任何原因要停用此新功能，有一個啟動工廠選項可以設定

當刪除客戶端範圍或整個領域時，也應該移除相關的使用者同意。已在 USER_CONSENT_CLIENT_SCOPE 表格上新增一個新的索引以提高效能。

請注意，如果表格包含超過 300,000 個項目，Keycloak 預設會跳過自動架構遷移期間索引的建立，而改為將 SQL 陳述式記錄到主控台。在 Keycloak 啟動後，必須在資料庫中手動執行這些陳述式。請參閱升級指南，以了解如何設定不同的限制。

預設支援主機名稱 v2 選項，因為舊的主機名稱選項已棄用，並將在後續版本中移除。預設會啟用新的選項，因此 Keycloak 將無法識別舊的選項。

必要的遷移列表

如您所見，hostname 和 hostname-admin 選項已移除 *-url 後綴。hostname 選項接受主機名稱和網址，但 hostname-admin 現在只接受完整的網址。

此外，無法單獨設定 path 或 port。您可以透過為 hostname 和 hostname-admin 選項提供完整的網址來實現。

如果埠號不是網址的一部分，則會從傳入的請求標頭動態解析。

除非 HTTPS 是 hostname 和 hostname-admin 網址的一部分，否則不再強制執行 HTTPS。如果未指定，使用的通訊協定 (http/https) 會從傳入的請求動態解析。已移除 hostname-strict-https 選項。

先前版本的 Keycloak 僅在資料庫中儲存離線使用者和離線用戶端工作階段。新的 persistent-user-sessions 功能不僅將線上使用者工作階段和線上用戶端工作階段儲存在記憶體中，還儲存在資料庫中。這將允許使用者即使在重新啟動或升級 Keycloak 的所有執行個體後仍保持登入狀態。

嵌入式快取的指標現在預設啟用。若要啟用延遲的直方圖，請將選項 cache-metrics-histograms-enabled 設定為 true。

Keycloak 提供的指標現在包含以 http_server 開頭的 HTTP 伺服器指標。請參閱下方的一些範例。

使用新的選項 http-metrics-histograms-enabled 和 http-metrics-slos 來啟用預設的直方圖儲存區或服務級目標 (SLO) 的特定儲存區。如需更多關於直方圖的資訊，請參閱 Prometheus 關於直方圖的文件，瞭解如何使用 http_server_requests_seconds_bucket 中提供的其他指標序列。

在 Keycloak 24 版本中，我們在密碼雜湊演算法中進行了變更，導致 CPU 使用率增加。為了處理這個問題，我們為非 FIPS 環境選擇了不同的預設雜湊演算法 Argon2，這將 CPU 使用率恢復到 Keycloak 24 版本之前的狀態。

在某些情況下，例如中介，Keycloak 使用 HTTP 與外部伺服器通訊。為了避免在這些提供者傳送過多資料時發生阻斷服務，Keycloak 現在預設將回應限制為 10 MB。

使用者可以透過設定提供者配置選項 spi-connections-http-client-default-max-consumed-response-size 來配置此限制

spi-truststore-file-hostname-verification-policy 和新的 tls-hostname-verifier 選項的預設值現在為 DEFAULT，而不是 WILDCARD。WILDCARD 和 STRICT 選項值已棄用 - 您應該只依賴 DEFAULT 即可。

WILDCARD 支援但 DEFAULT 不支援的行為：* 允許子網域名稱中的萬用字元（例如 *.foo.com）來比對任何內容，包括多個層級（例如 a.b.foo.com）。* 允許比對知名的公開後綴 - 例如 foo.co.gl 可能會比對 *.co.gl

STRICT 支援但 DEFAULT 不支援的行為：* STRICT 在判斷萬用字元是否比對時，會對以 2 個字母頂級結尾的 2 或 3 個字母網域名稱使用一個小型排除清單（*.XXX.YY）。相反地，DEFAULT 使用來自 https://publicsuffix.org/list/ 的更完整的公開後綴規則和排除清單。

不希望您依賴 WILDCARD 或 STRICT 選項中的這些行為。

當驗證階段過期且使用者已登入時，Keycloak 現在不會向最終使用者顯示「您已登入」的訊息。相反地，它會將有關過期驗證階段的錯誤重新導向到用戶端應用程式，以便用戶端可以對其採取動作並重新開始驗證，如伺服器管理指南驗證階段章節中所述。您可能會考慮更新您的應用程式，使其能夠處理此錯誤。

模組 org.keycloak:keycloak-model-legacy 模組已在先前的版本中棄用，並在此版本中移除。請改用 org.keycloak:keycloak-model-storage 模組。

在先前的版本中棄用後，啟動時預先載入離線階段的舊行為現在已移除。

選項 cache、cache-stack 和 cache-config-file 不再是建置選項，而且只能在執行階段指定。這消除了因為它們而需要執行建置階段並重建映像的需要。請注意，它們在 build 階段不會被識別，因此您需要移除它們。

kcadm 和 kcreg 如何剖析和處理選項和參數已變更。來自使用錯誤、錯誤的選項或參數的錯誤訊息可能與先前的版本略有不同。此外，使用錯誤的結束代碼將為 2，而不是 1。

當依使用者屬性搜尋使用者時，Keycloak 不再搜尋強制小寫比較的的使用者屬性名稱。這表示在搜尋時，Keycloak 使用者屬性資料表上的原生索引現在將會被使用。如果您已建立自己的索引（基於 lower(name)）來加速搜尋，您現在可以移除它。

名為 basic 的新用戶端範圍已新增為領域「預設」用戶端範圍，因此將會新增到所有新建立的 OIDC 用戶端。此用戶端範圍也會在移轉期間自動新增到所有現有的 OIDC 用戶端。

此範圍包含針對以下宣告預先配置的通訊協定對應器

這額外有助於減少輕量存取權杖中的宣告數量，但也提供配置始終自動新增的宣告的機會。

包含與 sid 宣告相同值的 session_state 宣告現在已從所有權杖中移除，因為根據 OpenID Connect 前端通道登出和 OpenID Connect 後端通道登出規格，它並非必要。session_state 宣告仍會根據 OpenID Connect 階段管理規格，存在於存取權杖回應中。

請注意，setSessionState() 方法也已從 IDToken 類別中移除，改為使用 setSessionId() 方法，而 getSessionState() 方法現在已棄用。

新的 階段狀態 (session_state) 對應器也包含在內，並且可以指派給用戶端範圍（例如 basic 用戶端範圍）以還原為舊行為。

如果使用舊版本的 JS 介面卡，也應該透過使用如上所述的用戶端範圍來使用 階段狀態 (session_state) 對應器。

sub 宣告一直以來都會加入存取令牌中，現在預設會透過新的 Subject (sub) 協定對應器加入。

Subject (sub) 對應器預設會在 basic 用戶端範圍中設定。因此，升級到此版本後不需要額外設定。

如果您使用 Pairwise subject identifier 對應器來對應存取令牌的 sub 宣告，您可以考慮停用或移除 Subject (sub) 對應器，但這並非嚴格必要，因為 Subject (sub) 協定對應器會在 Pairwise subject identifier 對應器之前執行，因此 pairwise 值將會覆蓋 Subject (sub) 對應器加入的值。這也可能適用於其他自訂協定對應器實作，它們會覆蓋 sub 宣告，因為 Subject (sub) 對應器目前是第一個執行的協定對應器。

您可以使用 Subject (sub) 對應器來設定僅用於存取令牌、輕量級存取令牌和內省回應的 sub 宣告。IDToken 和 Userinfo 始終包含 sub 宣告。

此對應器對服務帳戶沒有影響，因為沒有使用者工作階段存在，並且 sub 宣告始終會加入存取令牌中。

現在 nonce 宣告僅嚴格依照 OpenID Connect Core 1.0 規範加入 ID 令牌。如規範所述，當授權請求中傳送相同的參數時，該宣告在 ID 令牌內是強制性的。規範也建議在 重新整理請求之後不要加入 nonce。先前，該宣告在所有回應（包括重新整理）中設定給所有令牌（存取、重新整理和 ID）。

軟體中也包含新的 Nonce backwards compatible 對應器，可以將其指派給用戶端範圍以還原舊行為。例如，JS 轉接器在修正 #26651 於 24.0.0 版本中的問題之前，會檢查所有令牌中傳回的 nonce 宣告。因此，如果使用舊版本的 JS 轉接器，則應透過使用用戶端範圍將對應器加入所需的用戶端中。

REFRESH_TOKEN 事件中的 userId 現在始終從使用者工作階段取得，而不是從重新整理令牌中的 sub 宣告取得。REFRESH_TOKEN_ERROR 事件中的 userId 現在始終為 null。此變更的原因是，隨著可選 sub 宣告的引入，重新整理令牌中的 sub 宣告值可能為 null，或者在使用成對主體識別碼或其他覆蓋 sub 宣告的方式時，甚至可能與真實的使用者 ID 不同。

然而，現在加入了一個 refresh_token_sub 詳細資訊作為向後相容性，以便在 REFRESH_TOKEN_ERROR 事件中缺少 userId 的情況下提供有關使用者的資訊。

如果您在應用程式中使用最新的 Keycloak 伺服器搭配較舊版本的 JavaScript 轉接器，您可能會受到上述令牌變更的影響，因為先前版本的 JavaScript 轉接器依賴 Keycloak 加入的宣告，但 OIDC 規範並不支援這些宣告。這包括

您可以將協定對應器直接加入對應的用戶端，或加入某些用戶端範圍，這些用戶端範圍可以被依賴於較舊版本 Keycloak JavaScript 轉接器的用戶端應用程式使用。有關 session_state 和 nonce 宣告的更多詳細資訊，請參閱先前的章節。

如果未設定 http-pool-max-threads，則預設值將為 50 或 4 x（可用處理器）的較大者。先前預設值為 200 或 8 x（可用處理器）的較大者。在大多數使用情境中，減少任務執行緒的數量將會因減少活動執行緒之間的內容切換而產生稍高的效能。

/health 和 /metrics 端點可透過預設啟用的管理埠 9000 存取。這表示這些端點不再暴露於標準 Keycloak 埠 8080 和 8443。

為了反映舊的行為，請使用屬性 --legacy-observability-interface=true，這將不會在管理埠上暴露這些端點。然而，此屬性已棄用，將在未來版本中移除，因此建議不要使用它。

管理介面使用與預設 Keycloak HTTP 伺服器不同的 HTTP 伺服器，並且可以單獨設定它們。請注意，如果未提供管理介面屬性的值，則它們會繼承自預設 Keycloak HTTP 伺服器。

如需更多詳細資訊，請參閱設定管理介面。

Keycloak 從未逸出群組路徑中的斜線。因此，名為 group/slash 的群組在 top 下方會使用完整路徑 /top/group/slash，這顯然會產生誤導。從此版本開始，可以啟動伺服器以執行名稱中斜線的逸出。

逸出字元是波浪符號 ~。先前的範例會產生路徑 /top/group~/slash。逸出標記最後一個斜線是名稱的一部分，而不是層次結構分隔符。

逸出目前預設為停用，因為它代表行為的變更。儘管如此，仍建議啟用逸出，並且在未來版本中可能會是預設值。

方法 EnvironmentDependentProviderFactory.isSupported() 已被棄用數個版本，現在已移除。

請改為實作 isSupported(Config.Scope config)。

在 22.0.2 版本中，LinkedIn 的 OAuth 2.0 社交提供者已由新的 OpenId Connect 實作取代。舊版提供者已棄用但未移除，以防它在某些現有領域中仍然可以使用。Keycloak 25.0.0 確實移除了舊版提供者及其相關的 linkedin-oauth 功能。從現在開始，預設的 LinkedIn 社交提供者是唯一可用的選項。

當 RESOURCE_SERVER_RESOURCE 和 RESOURCE_SERVER_PERM_TICKET 表格的條目超過 10 萬個，且使用者被授予超過 1 千個資源的存取權時，這些查詢的效能會很差。查詢已簡化，並為 requester 和 owner 欄位引入了新的索引。

新的索引都已套用至 RESOURCE_SERVER_PERM_TICKET 表格。如果表格目前包含超過 300,000 個條目，Keycloak 將會在自動結構描述移轉期間預設跳過索引的建立，而是會在移轉期間將 SQL 陳述式記錄到主控台上。在這種情況下，必須在 Keycloak 啟動後在資料庫中手動執行陳述式。

有關如何設定不同限制的詳細資訊，請參閱升級指南。

以下方法已從 AccessToken 類別中移除

以下方法已從 IDToken 類別中移除

以下方法已從 JsonWebToken 類別中移除

您也應預期令牌中未設定 exp 和 nbf 宣告，因為它們是可選的。先前，這些宣告會設定為值 0，這沒有意義，因為它們的值應為有效的 NumericDate。

由於從 AccessToken、IDToken 和 JsonWebToken 中移除了已棄用的方法，SingleUseObjectKeyModel 也進行了變更，以保持與到期值相關的方法名稱一致。

先前的 getExpiration 方法現在已棄用，您應優先使用新引入的 getExp 方法，以避免 2038 年之後發生溢位。

介面 org.keycloak.credential.hash.PasswordHashProvider 上的方法 String encode(String rawPassword, int iterations) 已棄用。該方法將在未來 Keycloak 版本中移除。可能會在 Keycloak 27 版本中移除。

方法 org.keycloak.common.util.CollectionUtil.intersection 已移除。您應在現有集合上改用 'java.util.Collection.retainAll'。

org.keycloak.common.util.Resteasy 已棄用。您應改用 org.keycloak.util.KeycloakSessionUtil 來取得 KeycloakSession。

強烈建議避免透過建立自訂提供者以外的方式取得 KeycloakSession。

在先前版本中，當驗證工作階段是否仍然有效時，工作階段最大生命週期和閒置逾時計算略有不同。因為現在該驗證使用與專案其餘部分相同的程式碼。

如果工作階段使用記住我功能，則閒置逾時和最大生命週期是常見 SSO 和記住我設定值之間的最大值。

Keycloak 現在要求外部 Infinispan 部署至少使用 15.0.0 版本的 Infinispan 伺服器。如 HA 指南中所述，多站點設定支援外部 Infinispan 部署。

Oracle 資料庫 JDBC 驅動程式不再是 Keycloak 發行版的一部分。如果您希望使用 Oracle DB，您必須手動安裝與您的特定環境相容的 Oracle 驅動程式版本。有關此流程的說明，請參閱設定資料庫指南。

以下變數在 Admin 佈景主題中已棄用，將在未來版本中移除

以下變數在帳戶佈景主題中已棄用，將在未來版本中移除

介面 org.keycloak.models.AuthenticatedClientSessionModel 中的方法 String getCurrentRefreshToken()、void setCurrentRefreshToken(String currentRefreshToken)、int getCurrentRefreshTokenUseCount() 和 void setCurrentRefreshTokenUseCount(int currentRefreshTokenUseCount) 已被棄用。它們已被類似的方法取代，這些方法需要一個識別符號作為參數，例如 getRefreshToken(String reuseId)，以便在客戶端會話中管理多個刷新令牌。這些方法將在未來版本的 Keycloak 中移除。可能在 Keycloak 27 版本中移除。

透過管理使用者 API 更新使用者屬性時，更新使用者屬性時無法執行部分更新，包括根屬性，如 username、email、firstName 和 lastName。

如果您透過管理使用者 API 更新使用者屬性，但未傳遞管理員具有寫入權限的所有屬性，則會移除遺失的屬性。另一方面，如果某個屬性被標記為管理員的唯讀，則不傳送該屬性不會將其移除。

有關使用者設定檔設定的詳細資訊，請參閱使用者設定檔文件。

為了在領域中正確支援多個使用者儲存供應商，org.keycloak.userprofile.UserProfileDecorator 介面已變更。

decorateUserProfile 方法不再於首次剖析使用者設定檔設定 (並快取它) 時叫用，而是在每次透過使用者設定檔供應商管理使用者時叫用。因此，該方法變更了其合約為

與先前的合約和行為不同，此方法僅針對從中載入使用者的使用者儲存供應商叫用。

由於安全考量，如果傳遞的重新導向 URI 包含 userinfo 部分或其 path 存取父目錄 (/../)，重新導向 URI 驗證現在會執行精確字串比對 (不涉及萬用字元)。

完整的萬用字元 * 仍然可以在開發中使用，作為具有這些特徵的 http(s) URI 的有效重新導向。在生產環境中，需要為任何該類型的 URI 設定沒有萬用字元的精確有效重新導向 URI。

請注意，不建議在生產環境中使用萬用字元有效重新導向 URI，且 OAuth 2.0 規範不涵蓋此類 URI。

用於移除使用者憑證的帳戶 REST 端點已被棄用。從此版本開始，帳戶主控台不再使用此端點。它已被「刪除憑證」應用程式起始的動作取代，當使用者想要移除使用者的憑證時，帳戶主控台會觸發此動作。

Keycloak 24.0.0 的版本資訊已更新，其中包含對變更的預期效能影響的更正描述，以及調整大小指南。

「歡迎」主題已更新為使用新的佈局，現在使用 PatternFly 5，而不是 PatternFly 3。如果您正在擴充主題或提供自己的主題，則可能需要按如下方式更新它

如果您先前正在擴充現已棄用的帳戶主控台主題版本 2，則您需要更新您的主題以使用新的帳戶主控台主題版本 3。新版本的帳戶主控台主題在自訂方式方面有一些變更。若要從全新的狀態開始，您可以遵循新的自訂快速入門。

若要移動您的自訂主題，請先將 parent 變更為新主題

如果您有任何自訂 React 元件，您將直接匯入 React，而不是使用相對路徑

如果您使用 content.json 來自訂主題，則檔案的結構有一些變更，特別是

如果您直接從 Keycloak 伺服器載入 Keycloak JS，則可以安全地忽略此節。如果您從 NPM 套件載入 Keycloak JS 並且正在使用 Webpack、Vite 等捆綁器，則可能需要對您的程式碼進行一些變更。Keycloak JS 套件現在在 package.json 檔案中使用 exports 欄位。這表示您可能必須變更您的匯入

不再允許在 --features 和 --features-disabled 清單中都有相同的功能。該功能應僅出現在一個清單中。

在 --features 清單中使用未版本化的功能名稱 (例如 docker) 將允許為您啟用最受支援/最新的功能版本。如果您需要在各個版本之間有更可預測的行為，請參考您想要的版本，例如 docker:v1。

spi-truststore-file-* 選項和與信任儲存區相關的選項 https-trust-store-* 已被棄用。因此，請使用信任儲存區材料的新預設位置 conf/truststores，或使用 truststore-paths 選項指定您想要的路徑。有關詳細資訊，請參閱相關的指南。

應該使用 tls-hostname-verifier 屬性，而不是 spi-truststore-file-hostname-verification-policy 屬性。

變更的附帶影響是，現在信任儲存區提供者總是會設定一些憑證（至少存在預設的 Java 受信任憑證）。此新行為可能會影響 Keycloak 的其他部分。

例如，如果將「證明傳達」設定為「直接」驗證，則 webauthn 註冊可能會失敗。先前，如果未設定信任儲存區提供者，則不會驗證傳入的憑證。但現在始終會執行此驗證。由於 dongle 發送的憑證鏈不受 Keycloak 信任，因此註冊會失敗並顯示 invalid cert path 錯誤。驗證器的憑證授權單位必須存在於信任儲存區提供者中，才能正確執行證明。

--proxy 選項已被棄用，並將在未來的版本中移除。下表說明已棄用選項如何對應到支援的選項。

您也可以在使用 Operator 時設定 proxy headers

org.keycloak.representations.idm.UserRepresentation 和 org.keycloak.representations.account.UserRepresentation 表示類別都已變更，以便當擷取或將表示法有效負載傳送至管理和帳戶 API 時，根使用者屬性（例如 username、email、firstName、lastName 和 locale）具有一致的表示法。

username、email、firstName、lastName 和 locale 屬性已移至新的 org.keycloak.representations.idm.AbstractUserRepresentation 基底類別。

此外，getAttributes 方法的目標是僅表示自訂屬性，因此您不應期望在此方法傳回的 map 中找到任何根屬性。此方法的主要目標是當用戶端更新或擷取給定使用者的任何自訂屬性時。

為了解析所有屬性（包括根屬性），新增了一個新的 getRawAttributes 方法，以便產生的 map 也包含根屬性。然而，此方法無法從表示法有效負載取得，其目標是供伺服器在管理使用者設定檔時使用。

選項 https-client-auth 一直被視為執行時期選項，但 Quarkus 不支援此選項。此選項需要在編譯時期處理。

從此版本開始，Keycloak 叢集的第一個成員將會循序載入遠端工作階段，而不是並行載入。如果啟用離線工作階段預先載入，這些工作階段也會循序載入。

先前的程式碼導致叢集在啟動時消耗大量資源，並且在生產環境中難以分析，如果節點在載入期間重新啟動，可能會導致複雜的失敗情境。因此，已將其變更為循序工作階段載入。

對於離線工作階段，Keycloak 在此版本和先前版本中的預設行為是根據需求載入這些工作階段，相較於嘗試平行預先載入它們，這在大量離線工作階段的情況下具有更好的擴展性。使用此預設設定的安裝不受離線工作階段載入策略變更的影響。已啟用離線工作階段預先載入的安裝應遷移到停用離線工作階段預先載入的設定。

Keycloak 的預設行為是根據需求載入離線工作階段。在啟動時預先載入它們的舊行為現已棄用，因為在啟動時預先載入它們無法隨著工作階段數量的增加而良好擴展，並會增加 Keycloak 的記憶體使用量。舊行為將在未來版本中移除。

若要重新啟用已棄用但尚未移除的舊行為，請使用如下所示的功能旗標和 SPI 選項

UserSessionProvider 的 API 已棄用方法 getOfflineUserSessionByBrokerSessionId(RealmModel realm, String brokerSessionId)。請改用 getOfflineUserSessionByBrokerUserIdStream(RealmModel, String brokerUserId) 來先取得使用者的工作階段，然後根據需要依據代理工作階段 ID 進行篩選。

當為 Keycloak 的嵌入式快取啟用指標時，這些指標現在會使用標籤來表示快取管理器和快取名稱。

若要還原安裝的變更，請使用自訂的 Infinispan XML 設定，並按照以下方式變更設定

從此版本開始，Keycloak 支援儲存和搜尋長度超過 255 個字元的使用者屬性值，這在之前是個限制。

在允許使用者更新屬性的設定中（例如透過帳戶控制台），請新增驗證以防止阻斷服務攻擊。確保不允許任何未受管理的屬性，並且所有可編輯的屬性都有驗證來限制輸入長度。

對於未受管理的屬性，最大長度為 2048 個字元。對於受管理的屬性，預設最大長度為 2048 個字元。管理員可以透過新增類型為 length 的驗證器來變更此設定。

此變更會在 USER_ATTRIBUTE 和 FED_USER_ATTRIBUTE 表格上新增索引。如果這些表格包含超過 300000 個條目，Keycloak 在自動結構描述遷移期間預設會跳過索引建立，而是在遷移期間於主控台上記錄 SQL 陳述式，以便在 Keycloak 啟動後手動套用。請參閱升級指南以了解如何設定不同的限制。

在此版本中，API 將使用 email-verification.ftl 範本，而不是 executeActions.ftl。

如果您已自訂 executeActions.ftl 範本來修改使用者如何使用此 API 驗證其電子郵件，請確保將您的修改轉移到新的範本。

將引入一個名為 lifespan 的新參數，以允許覆寫預設的生命週期值 (12 小時)。

如果您偏好先前的行為，請如下所示使用 execute-actions-email API。

版本 21 中引入的 SAML 加密相容模式現已移除。伺服器不再管理系統屬性 keycloak.saml.deprecated.encryption。仍使用舊簽署金鑰進行加密的用戶端應從新的 IDP 組態中繼資料更新它。

在此版本中，我們調整了密碼雜湊的預設值，以符合 OWASP 密碼儲存建議。

作為此變更的一部分，預設密碼雜湊供應商已從 pbkdf2-sha256 變更為 pbkdf2-sha512。此外，基於 pbkdf2 的密碼雜湊演算法的預設雜湊迭代次數也變更如下

如果領域未明確配置具有 hashAlgorithm 和 hashIterations 的密碼原則，則新配置將在下一次基於密碼的登入時，或在建立或更新使用者密碼時生效。

透過 Keycloak CR 參考的 Secrets 和 ConfigMaps 現在將輪詢變更，而不是透過 API 伺服器監看。可能需要大約 1 分鐘才能偵測到變更。

這樣做是為了不需要在這些資源上操作標籤。升級後，如果任何 Secret 仍然具有 operator.keycloak.org/component 標籤，則可能會將其移除或忽略。

移除 Map Store 後，以下設定選項已重新命名

移除 Map Store 後，以下模組已重新命名

org.keycloak:keycloak-model-legacy 模組已棄用，並將在下一個版本中移除，改用 org.keycloak:keycloak-model-storage 模組。

現在，當使用者因暴力破解保護器而被暫時鎖定時，會出現一個新的事件 USER_DISABLED_BY_TEMPORARY_LOCKOUT。ID 為 KC-SERVICES0053 的記錄已移除，因為新事件以結構化形式提供資訊。

由於它是一個成功事件，因此預設會在 DEBUG 層級記錄新事件。使用 伺服器管理指南中的事件接聽程式章節所述的設定 spi-events-listener-jboss-logging-success-level，以變更所有成功事件的記錄層級。

若要觸發自訂動作或自訂日誌條目，請依照伺服器開發人員指南中「事件監聽器 SPI」的說明，撰寫自訂事件監聽器。

Operator 用於進階設定的屬性鍵已從 operator.keycloak 變更為 kc.operator.keycloak。

當 Keycloak CR 和 KeycloakRealmImport CR 中未指定 resources 選項時，將使用預設值。Keycloak 部署和 realm 匯入 Job 的預設 requests 記憶體設定為 1700MiB，而 limits 記憶體則設定為 2GiB。

作為 Keycloak 中 cookie 處理重構的一部分，cookie 的設定方式有一些變更

對於自訂擴充功能，可能需要進行一些變更

Keycloak 用於簽署內部令牌（Keycloak 本身使用的 JWT，例如刷新令牌或動作令牌）的演算法，正從 HS256 變更為更安全的 HS512。現在為 realm 新增了一個名為 hmac-generated-hs512 的金鑰供應器。請注意，在遷移的 realm 中，舊的 hmac-generated 供應器和舊的 HS256 金鑰會被保留，並且仍然會驗證升級前發出的令牌。按照輪換金鑰指南，當不再存在舊令牌時，可以手動刪除 HS256 供應器。

在容器中執行時，JVM 選項 -Xms 和 -Xmx 已被 -XX:InitialRAMPercentage 和 -XX:MaxRAMPercentage 取代。Keycloak 不再使用靜態最大堆積大小設定，而是將最大值指定為容器總記憶體的 70%。

由於堆積大小是根據容器總記憶體動態計算的，因此您應**始終設定容器的記憶體限制**。

如需更多詳細資訊，請參閱在容器中執行 Keycloak 指南。

隨著提供與 GELF 整合的底層函式庫停止維護，Keycloak 將不再支援現成的 GELF 日誌處理器。此功能將在未來版本中移除。如果您需要外部日誌管理，請考慮使用檔案日誌剖析。

由於問題#25078，jboss-logging 訊息值現在會被加上引號（預設為字元 "），並經過清理以防止任何換行符號。供應器中有兩個新選項（spi-events-listener-jboss-logging-sanitize 和 spi-events-listener-jboss-logging-quotes）可讓您自訂新行為。例如，若要避免清理和加上引號，伺服器可以採用以下方式啟動

如需有關選項的更多資訊，請參閱所有供應器配置指南。

23.0.0 版本在 Groups 資源上引入了一個新的端點 getSubGroups ("children")，其中參數 briefRepresentation 的含義是指擷取子群組的完整表示法。現在含義已變更為傳回簡要表示法。

1.8.0 版本在比較重新導向 URI 與用戶端指定的有效重新導向時，引入了主機名稱和方案的小寫。不幸的是，它並未在所有協定中完全運作，例如，http 的主機已小寫，但 https 則否。由於OAuth 2.0 安全性最佳實務建議使用完全字串比對來比較 URI，因此 Keycloak 將遵循該建議，並且從現在開始，即使是主機名稱和方案，也將使用完全相同的大小寫比較有效重新導向。

對於依賴舊行為的 realm，其用戶端的有效重新導向 URI 現在應為伺服器應識別的每個 URI 保留單獨的項目。

雖然在設定用戶端時引入了更多步驟和冗長，但新行為可以實現更安全的部署，因為基於模式的檢查經常是導致安全問題的原因。這些問題是因其如何實作以及如何配置而產生。

舊版本的 operator 會建立 Secret 來追蹤受監控的 Secret。較新版本的 operator 不再使用 -secrets-store Secret，因此可以將其刪除。

如果您使用的是 23.0.0 或 23.0.1，並且在 operator 日誌中看到「org.keycloak.operator.controllers.KeycloakAdminSecretDependentResource → java.lang.IllegalStateException: More than 1 secondary resource related to primary」，則可以刪除 -secrets-store Secret，或是升級至 23.0.2，因為這不再是問題。

RFC 9207 OAuth 2.0 授權伺服器發行者識別規範在 OAuth 2.0/OpenID Connect 驗證回應中新增了參數 iss，以實現安全的授權回應。

在過去的版本中，我們沒有這個參數，但現在 Keycloak 預設會新增此參數，這是該規範的要求。

但是，某些 OpenID Connect/OAuth2 配接器，尤其是較舊的 Keycloak 配接器，可能存在此新參數的問題。

例如，在成功驗證至用戶端應用程式後，該參數將始終存在於瀏覽器 URL 中。在這些情況下，停用在驗證回應中新增 iss 參數可能很有用。這可以在 Keycloak 管理主控台中針對特定用戶端完成，在「OpenID Connect 相容性模式」區段中的用戶端詳細資料中進行描述，詳見與較舊配接器的相容性。存在專用的「從驗證回應中排除發行者」切換開關，可以開啟該開關以防止將 iss 參數新增至驗證回應。

JPA 在搜尋時允許萬用字元 % 和 _，而其他供應器（例如 LDAP）僅允許 *。由於 * 是 LDAP 中的自然萬用字元，因此它在所有位置都有效，而使用 JPA 時，它僅在搜尋字串的開頭和結尾有效。從此版本開始，唯一的萬用字元是 *，它在搜尋字串中的所有位置都以一致的方式運作。特定供應器中的所有特殊字元（例如 JPA 的 % 和 _）都會被逸出。對於精確搜尋，如果加上引號（例如 "w*ord"），則其行為與先前版本中的相同。

此版本現在遵循 Java 及更高版本的標準機制，該機制假設資源包檔案以 UTF-8 編碼。

先前版本的 Keycloak 支援在第一行使用註解（如 # encoding: UTF-8）指定編碼，但此功能不再受支援，並且會被忽略。

現在以 UTF-8 編碼讀取佈景主題的訊息屬性檔案，並自動回復為 ISO-8859-1 編碼。如果您使用其他編碼，請將檔案轉換為 UTF-8。

在此版本之前，當停用 Multivalued 設定時，realm (User Realm Role) 和用戶端 (User Client Role) 通訊協定對應器都會對應字串化的 JSON 陣列。

然而，Multivalued 設定會指示是否應將聲明對應為列表，如果停用，則僅對應來自相同值列表的單個值。

在此版本中，角色和用戶端對應器現在會將使用者的有效角色對應為單個值（當它們被標記為單值時，即 Multivalued 停用）。

在此版本中，我們希望引入一個切換開關來隱藏/顯示密碼輸入。

一般而言，所有 <input type="password" name="password" /> 現在都被封裝在一個 div 內。輸入元素後面跟著一個按鈕，該按鈕會切換密碼輸入的顯示狀態。

舊程式碼範例

新程式碼範例

在 OpenShift 上執行時，如果啟用 ingress，且 spec.ingress.classname 設定為 openshift-default，您可以將 Keycloak CR 中的 spec.hostname.hostname 保留為未填寫。操作員將會為 CR 的儲存版本分配一個預設的主機名稱，類似於沒有明確主機的 OpenShift Route 所建立的主機名稱 - 即 ingress-namespace.appsDomain。如果 appsDomain 變更，或者您因任何原因需要不同的主機名稱，請更新 Keycloak CR。

auto-build CLI 選項已標記為棄用很長一段時間。在此版本中，它已完全移除，不再支援。

執行 start 命令時，伺服器會根據組態自動建置。為了防止此行為，請設定 --optimized 旗標。

kc.sh 不再對參數和環境變數 JAVA_OPTS_APPEND 和 JAVA_ADD_OPENS 使用額外的 shell eval，因此繼續使用雙重跳脫/引號將會導致參數被誤解。例如，而不是

使用單個跳脫

此變更也意味著您不能使用單引號值來調用 kc.sh 的所有引數。例如，您不能再使用

它必須是個別的引數

同樣地，而不是

它必須是個別的引數

在 Dockerfile run 命令中也需要使用個別的引數。

表單動作 RegistrationProfile（在身份驗證流程的 UI 中顯示為 Profile Validation）已從程式碼庫和所有身份驗證流程中移除。預設情況下，它位於每個 realm 的內建註冊流程中。使用者屬性的驗證以及使用者（包括該使用者的所有屬性）的建立皆由 RegistrationUserCreation 表單動作處理，因此不再需要 RegistrationProfile。除非您在自己的提供者中使用 RegistrationProfile 類別，否則通常不需要針對此變更採取進一步的動作。

已新增一個新方法，允許搜尋和分頁瀏覽頂層群組。如果您實作此介面，您將需要實作以下方法

新增端點 GET {keycloak server}/realms/{realm}/groups/{group_id}/children，作為取得支援分頁的特定群組子群組的方法

依賴 RESTEasy Classic 已不再是一種選項，因為它不再可用。對於依賴 RESTEasy Classic 和 org.jboss.resteasy.spi.* 中相關套件的 SPI 和程式碼，將需要進行遷移。

端點 POST {keycloak server}/realms/{realm}/partial-export 和管理主控台中對應的動作現在需要 manage-realm 權限才能執行，而不是 view-realm。此端點會將 realm 設定匯出為 JSON 檔案，而新的權限更為合適。參數 exportGroupsAndRoles 和 exportClients（分別在匯出中包含 realm 群組/角色和用戶端）繼續管理相同的權限（query-groups 和 view-clients）。

自此版本起，Keycloak 支援 EventEntity 詳細資訊欄位的長值。因此，它不再支援修剪事件詳細資訊長度的選項 --spi-events-store-jpa-max-detail-length 和 --spi-events-store-jpa-max-field-length。

此版本包含許多與使用者設定檔相關的修正和更新，因為我們正在努力將此功能從預覽版提升為正式支援。SPI 存在一些小變更，例如在 UserProfileProvider 介面上新增的方法 boolean isEnabled(RealmModel realm)。此外，一些使用者設定檔類別和一些驗證器相關類別（但不是內建驗證器實作）已從 keycloak-server-spi-private 模組移至 keycloak-server-spi 模組。但是，Java 類別的套件保持不變。您在某些邊緣情況下可能會受到影響，例如當您使用自己的 UserProfileProvider 實作覆寫內建實作時。但是，請注意，UserProfileProvider 是一個不受支援的 SPI。

Map Store 在先前的版本中是一個實驗性功能。從此版本開始，它已被移除，使用者應繼續使用目前的 JPA 儲存。

自此版本起，不再可能使用 --storage 相關的 CLI 選項。keycloak-model-map* 模組已移除。

所有翻譯都移至管理主控台的一個檔案中。如果您已建立自己的翻譯或擴展了管理主控台，則需要將它們遷移至此新格式。此外，如果您的資料庫中有「覆寫」，則必須從金鑰中移除命名空間。某些金鑰是相同的，只是在不同的命名空間中，這對於說明最為明顯。在這些情況下，我們已在金鑰上加上 Help 後綴。

如果您需要，可以使用此節點指令碼來協助遷移。它將會採用所有單一檔案，並將它們放入一個新的檔案中，同時也會處理一些對應

將其儲存到您的 public/locale/<language> 資料夾中名為 transform.mjs 的檔案中，並使用以下命令執行它

新增了一個新參數 --spi-user-profile-declarative-user-profile-max-email-local-part-length，用於設定電子郵件本地部分的最大長度，同時考慮向後相容性。預設值為 64。使用範例

永不過期 選項現在已從「進階設定」用戶端索引標籤的所有組合中移除。此選項具有誤導性，因為不同的存留時間或閒置逾時從來都不是無限的，而是受到一般使用者工作階段或 realm 值的限制。因此，此選項已移除，改用其餘的兩個選項：繼承 realm 設定（用戶端使用一般 realm 逾時）和 在以下時間過期（該值會覆寫用戶端）。在內部，永不過期 以 -1 表示。現在，該值會在管理主控台中顯示警告，且管理員無法直接設定。

已為以商業和就業為重點的平台引入一個名為 LinkedIn OpenID Connect 的新社群身份提供者。LinkedIn 最近發布了一個針對開發人員的新產品，稱為 使用 OpenID Connect 登入 LinkedIn。該產品提供一種使用 OpenID Connect 驗證成員的新方法，但預設的 OpenID Connect v1.0 身份提供者目前無法與其搭配使用。因此，Keycloak 將此新的身份提供者新增為新產品的特定社群提供者。

舊的基於 OAuth 的 LinkedIn 方法似乎已從 開發人員入口網站 中完全移除。現有的 LinkedIn 社群提供者如何與目前的應用程式搭配運作尚不清楚。Keycloak 保留了重新命名為 LinkedIn (已棄用) 的舊提供者，但它在預設停用的 linkedin-oauth 這個已棄用的功能中。它將在未來的版本中移除。如果需要，請在啟動時再次啟用它

Keycloak 已將其程式碼庫從 Java EE (企業版) 遷移到其後繼版本 Jakarta EE，這為 Keycloak 帶來了各種變更。

我們已升級所有 Jakarta EE 規格，以支援 Jakarta EE 10，例如

Jakarta EE 10 提供了一種更現代化、更簡化、更輕量級的方法來建置雲端原生 Java 應用程式。此計畫中提供的主要變更包括將命名空間從 javax.* 變更為 jakarta.*。它不適用於 JDK 中直接提供的 javax.* 套件，例如 javax.security、javax.net、javax.crypto 等。

您的自訂擴充功能、供應商或 JPA 實體可能會受到這些變更的影響。

Keycloak 已升級至 Quarkus Java 框架的第 3 版。Quarkus 3 延續了快速發展並利用最新技術提供尖端使用者體驗的傳統，進一步推動 Java 開發。它持續改善整體效能和效率。

Quarkus 3 基於 Jakarta EE 10，與 Keycloak 相同，兩者之間具有順暢的互通性。此外，它還包含 Eclipse MicroProfile 6，與 Jakarta EE 10 Core Profile 對齊。Quarkus 3 升級的核心是內建支援 JPA 3.1 和 Hibernate ORM 6。

Keycloak 現在受益於升級至 Hibernate ORM 6.2，其中包括效能提升、更好的 SQL、現代 JDK 支援以及對現代 RDBMS 功能的支援。效能提升主要影響 JDBC、HQL 轉換和 Criteria 轉換。

如果您有自訂的供應商或 JPA 實體，這些變更可能會影響您。

我們建議您檢閱 Quarkus 移轉指南 或 Hibernate 版本說明，以取得更多資訊。

舊版 Promise API 方法已從 Keycloak JS 介面卡中移除。這表示不再可能在介面卡傳回的 promise 上呼叫 .success() 和 .error()。相反地，應該使用標準化的 Promise 方法，例如 .then() 和 .catch()。

在先前的版本中，export 和 import 命令需要先執行 build 命令。從此版本開始，如果建置時間設定已變更，則 export 和 import 命令會執行 Keycloak 的自動重建。

當移轉先執行 build 命令的現有指令碼時，請將 --optimized 命令列選項新增至 export 和 import 命令，以避免 Keycloak 自動重建映像。未在此新增 --optimized 選項可能會使 Keycloak 觸發重建並還原為預設值，然後連線到資料庫以進行匯出和匯入將無法運作。

以下範例假設執行階段參數（例如資料庫密碼）是透過設定檔或環境變數提供的。

在先前的版本中，export 和 import 命令僅允許在設定檔或環境變數中使用執行階段參數（例如資料庫 URL）。從此版本開始，這些執行階段參數現在也可以在命令列中使用。請使用 --help 選項來了解支援的參數。

升級至 Jakarta EE 後，Keycloak Admin 用戶端的成品已重新命名為更具描述性的名稱，並考量長期維護性。我們仍提供兩個不同的 Keycloak Admin 用戶端，一個具有 Jakarta EE 支援，另一個具有 Java EE 支援。

我們已停止發佈 org.keycloak:keycloak-admin-client-jakarta 成品。具有 Jakarta EE 支援的 Keycloak Admin 用戶端預設成品是 org.keycloak:keycloak-admin-client（自 22.0.0 版起）。

新的 Java EE 支援成品是 org.keycloak:keycloak-admin-client-jee。

Keycloak 針對模式 passthrough 的代理設定不再剖析要求中的 HTTP 轉送標頭，因為當代理在 passthrough 模式中轉送 HTTPS 連線時，代理無法新增、移除或更新 HTTP 標頭。

想要剖析用戶端要求中 HTTP 標頭的安裝應該使用 edge 或 reencrypt 設定。

如需詳細資訊，請參閱 使用反向代理。

當您使用領域本地化訊息時，此變更可能只會影響您。

在此版本之前，當使用領域本地化訊息時，跨佈景主題的備用訊息解析不一致。如需更多資訊，請參閱以下 問題。

現在已針對所有佈景主題統一實作。一般而言，最符合特定語言標籤的訊息具有最高優先順序。如果同時存在領域本地化訊息和佈景主題 i18n 訊息，則領域本地化訊息具有較高的優先順序。總結來說，訊息的優先順序如下（RL = 領域本地化，T = 佈景主題 i18n 檔案）：RL <變體> > T <變體> > RL <區域> > T <區域> > RL <語言> > T <語言> > RL en > T en。

或許可以透過範例更好地說明：當要求變體 de-CH-1996 且該變體存在領域本地化訊息時，將會使用此訊息。如果不存在此類領域本地化訊息，則會搜尋佈景主題 i18n 檔案中是否有對應該變體的訊息。如果不存在此類訊息，則會搜尋區域 (de-CH) 的領域本地化訊息。如果不存在此類領域本地化訊息，則會搜尋佈景主題 i18n 檔案中是否有對應該區域的訊息。如果仍然找不到訊息，則會搜尋語言 (de) 的領域本地化訊息。如果沒有相符的領域本地化訊息，則會搜尋佈景主題 i18n 檔案中是否有對應該語言的訊息。最後的備用方案是使用英文 (en) 翻譯：首先，會搜尋英文領域本地化，如果找不到，則會搜尋佈景主題 i18n 檔案中是否有英文訊息。

UserQueryProvider 介面已分成兩個。一個是 UserQueryMethodsProvider，提供查詢用戶的功能。第二個是 UserCountMethodsProvider，提供計算特定儲存中用戶數量的功能。

Keycloak 現在能夠區分可以有效執行計數查詢的用戶儲存供應商和無法執行計數查詢的用戶儲存供應商。UserQueryProvider 介面仍然存在，並延伸兩個新的介面。因此，由於 UserQueryProvider 保留相同的方法，因此現有 UserQueryProvider 實作中不需要進行任何修改。

從此版本開始，Keycloak 在查詢聯合 LDAP 資料庫時使用分頁機制。搜尋用戶應與本機資料庫中的搜尋一致。

自此版本起，LDAPStorageProvider 僅實作 UserQueryMethodsProvider，而非 UserQueryProvider。

從此版本開始，我們將不再投入時間於以下 Keycloak OpenID Connect 介面卡

此變動已反映在我們的文件中和快速入門存放庫中。請考慮查看以下參考資料以取得更多資訊

我們建議您開始研究將您的應用程式移至以上參考資料中的替代方案。這些介面卡在未來的版本中不應再可用。

Keycloak JEE SAML 介面卡已停止使用，在此版本之後，我們將不再投入時間於其開發。

官方介面卡現在基於 Jakarta，您應該在將應用程式切換至此技術後立即使用它。

此變更已在我們的文件中和快速入門存放庫中。如需更多資訊，請考慮查看以下參考資料

如果您無法將應用程式移轉至 Jakarta，您仍然可以使用「舊版」SAML JEE 介面卡，並且仍然能夠與伺服器的未來版本整合。但是，請盡快考慮升級您的應用程式，因為我們不再提供對 JEE 的支援。

預覽功能 openshift-integration 已從 Keycloak 程式碼庫中移除，並移至個別的擴充功能。這包括移動相關供應商，例如自訂用戶端儲存供應商和 Openshift 整合的權杖檢閱端點。

如果您使用了此功能，當啟動 Keycloak 伺服器時，您不應再使用 openshift-integration 功能，而是需要部署來自自訂擴充功能的 JAR 檔案。您可以查看 Openshift 擴充功能及其 README 檔案中的說明，瞭解如何將擴充功能部署到您的 Keycloak 伺服器。

移除 openshift-integration 允許我們從 Keycloak 發行版中移除一些第三方相依性。這包括 openshift-rest-client、okio-jvm、okhttp、commons-lang、commons-compress、jboss-dmr 和 kotlin-stdlib。這表示如果您使用任何這些程式庫作為部署到 Keycloak 伺服器的自訂提供者的相依性，您可能還需要將這些 jar 檔案明確複製到 Keycloak 發行版的 providers 目錄中。

為了提供更好的運行時效能並盡可能利用底層堆疊，所有使用 javax.ws.rs.core.Context 註解的上下文資料注入點都已移除。預期的效能提升包括不再於請求生命週期中多次建立代理實例，並大幅減少運行時的反射程式碼量。

如果您正在擴充下列其中一個 SPI

您應該檢查您的自訂 JAX-RS (子)資源，以按照以下方式取得任何上下文資料

如果您需要存取目前的請求和回應物件，現在可以直接從 KeycloakSession 取得它們的實例

已由以下取代

如果您在調用 JAX-RS 資源方法時無法存取 KeycloakSession 實例，您可以從 JAX-RS 運行時取得上下文資料，如下所示

可以透過 KeycloakContext 實例從運行時取得其他上下文資料

如果您正在透過下列 SPI 擴充伺服器的 REST API

您需要在封裝自訂提供者的 JAR 檔案中新增一個空的 META-INF/beans.xml。否則，它們在運行時將不會被伺服器識別。

如果您使用 RealmResourceSPI 或 AdminRealmResourceSpi，您可以選擇在 META-INF 下新增一個名為 beans.xml 的空檔案，或使用 jakarta.ws.rs.ext.Provider 註解來註解 JAX-RS 資源類別。

您也應該確保您的 JAX-RS 方法透過使用 @Consumes 和 @Produces 註解來分別宣告輸入和輸出的預期媒體類型。

在 Keycloak 的較早版本中，提供者和模型介面經歷了一個清理過程，其中涉及棄用某些方法。在此版本中，這些方法已移除，並棄用了一些額外的方法。來自 Keycloak 21 的這些方法的 Javadoc 包含了有關其對應替換的資訊。

可以在同一個命名空間中建立多個 Keycloak CR，並且將由運算子獨立管理。為了允許這樣做，必須重新建立舊版運算子所建立的 StatefulSet。這會在運算子升級時自動發生，並導致少量停機時間。

條件狀態欄位已從布林值變更為字串，以符合標準的 Kubernetes 條件。在 CRD 中，它將暫時表示為接受任何內容，但它只會是一個字串。請確保您對此欄位的任何使用方式都已更新為預期值「True」、「False」或「Unknown」，而不是 true 或 false。

Keycloak 支援 IPv4/IPv6 雙堆疊，並且預設可以透過 IPv4 和 IPv6 位址存取。在較舊版本的 Keycloak 中，預設方法是僅使用 IPv4 位址。

如需更多詳細資訊，請參閱使用 IPv4 或 IPv6 設定 Keycloak 伺服器。

在先前的版本中，當在 Java 17 上使用 Keycloak 和 Javascript 提供者（指令碼驗證器、Javascript 授權原則或 OIDC 和 SAML 用戶端的指令碼協定對應器）時，需要將 javascript 引擎複製到發行版。由於 Nashorn javascript 引擎預設在 Keycloak 伺服器中可用，因此不再需要這樣做。當您部署指令碼提供者時，建議不要將 nashorn 指令碼引擎及其相依性複製到 Keycloak 發行版中。

服務帳戶用戶端的預設 用戶端 ID 對應器已變更。Token Claim Name 欄位值已從 clientId 變更為 client_id。client_id 宣告符合 OAuth2 規範

clientId userSession 註解仍然存在。

過去可以透過直接呼叫 Keycloak() 函數來建立 Keycloak JS 配接器的實例

為了使之與 JavaScript 世界中的現代慣例一致，可以使用 new 運算子來建立實例

函數樣式的建構函式已被棄用一段時間，但從這個版本開始，當使用它時，我們將主動記錄棄用訊息。這種樣式的建構函式將在未來版本中移除，因此請務必遷移您的程式碼以使用 new 運算子。

terms_and_conditions 使用者屬性在 21.0.0 中意外變更為大寫。此版本將使用者屬性還原為小寫。接受「條款及條件」頁面時會設定屬性的值。

如果您的任何自訂擴充功能依賴此屬性，您可能需要調整您的程式碼以檢查 terms_and_conditions 和 TERMS_AND_CONDITIONS 屬性。

Keycloak 提供了一個可選的指標端點，用於匯出 Prometheus 格式的指標。在此版本中，提供此資料的實作已從 SmallRye 切換到 Micrometer，這是 Quarkus 建議的指標程式庫。

由於此變更，指標已重新命名。下表顯示了一些範例。

建議在升級之前檢查變更前後從端點傳回的所有指標，並更新它們在儀表板和警示中的使用方式。

可以在 SAML 配接器、用戶端和身分提供者上設定為 Signature algorithms 的 RSA_SHA1 和 DSA_SHA1 演算法已棄用。我們建議使用基於 SHA256 或 SHA512 的更安全替代方案。此外，在 Java 17 或更高版本上，驗證具有這些演算法的已簽署 SAML 文件或聲明上的簽名無效。如果您使用此演算法，並且使用您的 SAML 文件的其他方在 Java 17 或更高版本上執行，則驗證簽名將無法運作。

可能的解決方法是從檔案 $JAVA_HOME/conf/security/java.security 中 jdk.xml.dsig.secureValidationPolicy 屬性上設定的「不允許的演算法」清單中移除演算法，例如 http://www.w3.org/2000/09/xmldsig#rsa-sha1 或 http://www.w3.org/2000/09/xmldsig#dsa-sha1。

在此版本中，Keycloak 將拒絕解密使用為簽署目的產生的 realm 金鑰所加密的聲明。此變更表示從 IDP 到 SP（Keycloak 作為 SP）的所有加密通訊都將停止運作。

有兩種方法可以使其正常運作

在 Keycloak 13 中，引入了 UserLoginFailureProvider，且 UserSessionProvider 中的某些方法被移至該處。UserSessionProvider 中的方法已被棄用，現在已移除。這些方法的 Javadoc 包含相應的替代方法（請參閱 Keycloak 20 版本的 Javadoc）。

舊版管理主控台在先前的版本中已遭棄用，現在已正式移除。這也表示您使用它作為父佈景主題或從中匯入的自訂佈景主題將無法運作。強烈建議您不要部署這類佈景主題，因為擴充舊版管理主控台已不再適用，且部署這類佈景主題可能會在 Keycloak 中出現問題（至少會在記錄檔中顯示警告或錯誤）。

已修改 Keycloak 容器映像以增強安全性。因此，已移除 curl 和其他 CLI 工具，您可能曾在自訂映像中使用它們。請參閱更新的容器指南，以了解如何處理此變更。

已將 Keycloak 管理 REST 用戶端的 RESTEasy 版本更新至下一個主要版本。

Keycloak 隨附 H2 資料庫驅動程式，僅供開發之用。由於它僅適用於開發用途，因此絕不應在生產環境中使用。

在此版本中，H2 驅動程式已從 1.x 版升級至 2.x 版。這項變更可能需要在現有的 Keycloak 設定中變更 H2 JDBC URL 或遷移 H2 資料庫檔案。

此版本在 Keycloak CR 中包含以下重大變更

Keycloak Operator Lifecycle Manager 的預設通道已變更為 fast。

在 Keycloak 15 之前，我們清理了供應商和模型介面，其中我們棄用了一些方法。這些方法的 Javadoc 包含相應的替代方法（請參閱 Keycloak 19 版本的 Javadoc）。在此版本中，已移除這些方法。以下是所有已變更類別的清單。

棄用和移除方法最常見的模式如下。

在 Keycloak 18.0.0 中，登出現在與新的 OIDC 規格相容，該規格變更了 URL 參數的處理方式。但是，為了與先前的版本保持相容性，引入了相容性標記。請參閱升級指南，以取得有關回溯相容性選項的更多資訊，該選項允許您的應用程式繼續使用舊格式的 URL 參數。

雖然現在可以將 URL 參數設定為相容，但與 Keycloak 17 和更早的版本仍然存在一個不相容的問題。如果使用者未提供有效的 idTokenHint，則會顯示登出提示，而不是成功登出重新導向。因此，引入了一個新的相容性標記 suppress-logout-confirmation-screen 以抑制登出畫面。

當您啟動伺服器時，可以輸入以下命令來啟用此參數

透過此設定，您仍然可以在沒有使用者提示的情況下使用登出端點。

直到現在，在他們的 SAML 用戶端或用戶端範圍上使用 SAML javascript 通訊協定對應程式的管理員，都可以透過 Keycloak 管理主控台以及 RESTful 管理 API 將指令碼上傳至伺服器。

從現在起，此功能已停用，使用者應直接將指令碼部署至伺服器。此行為與其他以指令碼為基礎的供應商一致。如需更多詳細資訊，請參閱 JavaScript 供應商。

新的管理主控台現在是 Keycloak 的預設主控台。如果您無法開始使用新的管理主控台，可以停用新的主控台，以繼續使用舊的管理主控台，例如透過執行以下命令：

繼續使用舊管理主控台的另一種方法是將主領域 (master realm) 或任何其他領域的主題設定為 keycloak。

由於新的管理主控台與舊的管理主控台有顯著差異，它是基於 React 並使用較新版本的 PatternFly，任何自訂主題都可能需要從頭開始重新實作。要為新的管理主控台建立自訂主題，該主題應擴展 keycloak.v2 而不是 keycloak。

如果您已明確將主領域或任何其他領域的管理主控台主題設定為 keycloak，它將繼續使用舊的管理主控台。要更新到新的管理主控台，您需要將主題變更為 keycloak.v2。

舊的管理主控台將在 Keycloak 21 中移除。

在此版本之前，您會在執行 start 命令時使用 --auto-build，以告知伺服器在啟動伺服器之前，如果有任何建置選項發生變更，則有條件地執行 build。

在此版本中，--auto-build 標誌已被棄用，您不再需要使用它來表示您希望在啟動伺服器時設定建置選項。相反地，如果任何建置選項發生變更，伺服器預設總是在啟動伺服器之前執行 build。新的行為透過使其成為可選的（雖然強烈建議），來改善配置和啟動伺服器時的整體體驗，以便在啟動之前執行 build 命令以達到最佳的啟動時間和記憶體佔用量。

現在，為了達到最佳的啟動時間和記憶體佔用量，請設定 --optimized 選項來停用新的預設行為。--optimized 標誌會告知伺服器，作為啟動一部分，不需要檢查和直接執行 build。

如果您已經使用自訂映像來設定建置選項並執行最佳化的 Keycloak 容器，請確保在調用 start 命令時設定 --optimized 選項。

如需更多詳細資訊，請參閱配置指南和容器指南。

在 Keycloak 19.0.0 之前，基於 Quarkus 的 Keycloak 發行版本總是會意外地啟用以下非應用程式端點：

從 Keycloak 19.0.0 開始，這些端點已被停用，並且請求將導致 404 HTTP 狀態碼。如果您正在使用 /q/…​ 端點，請務必在升級到 Keycloak 19.0.0 時，將您的探針和監控系統變更為使用預期的健康檢查端點。

預期的健康檢查端點為：

除了停用 /q/ 端點之外，以下是針對健康檢查端點所做的其他改進：

未來將在此領域進行更多增強。如需更多資訊，請參閱健康檢查指南。

如發行說明中所述，Keycloak 現在開箱即用支援集中式日誌系統的 GELF 日誌記錄。

當您在先前版本中自行新增 GELF 相關的 Quarkus JAR 時，請確保切換到日誌記錄指南中支援的配置選項，並從 providers 資料夾中移除您的 JAR。

Keycloak 正在進行大型重構，這會影響現有程式碼。其中一些變更需要更新現有程式碼。這些變更在下面有更詳細的描述。

在此版本中，我們已棄用舊版 Keycloak Operator 的 Keycloak CR 中的 podDisruptionBudget 欄位。當 Operator 部署在 Kubernetes 1.25 版或更高版本上時，將會忽略此選用欄位。

作為因應措施，您可以在您的叢集中手動建立 Pod 中斷預算，例如

另請參閱Kubernetes 文件。

新的 Keycloak Operator 現在針對 Keycloak 部署使用 StatefulSet 而不是 Deployment。由於 Operator 在此版本中是技術預覽版，因此沒有自動遷移機制。如果您正在使用 18.0.z 的新 Operator，請務必在升級到 19.0.0 之後備份、刪除並重新建立您的 Keycloak CR。

逐步驗證是一項新功能。此功能提供 acr 用戶端範圍，其中包含一個協定對應器，該對應器應該在權杖中新增 acr 宣告。acr 宣告現在不會像此版本之前那樣自動新增，而是透過使用此用戶端範圍和協定對應器來新增。

用戶端範圍會新增為領域「預設」用戶端範圍，因此將會新增至所有新建立的用戶端。基於效能考量，在遷移期間不會自動將用戶端範圍新增至所有現有用戶端。遷移後，用戶端預設將不會有 acr 宣告。請考慮下列可能的動作

先前版本的 Keycloak 支援自動登出使用者，並透過開啟登出端點 URL (例如 http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri) 來重新導向至應用程式。雖然該實作易於使用，但它可能會對效能和安全性產生負面影響。新版本針對基於 OpenID Connect RP 起始登出規格的登出提供更好的支援。不再支援參數 redirect_uri；此外，在新版本中，使用者需要確認登出。當您包含參數 post_logout_redirect_uri 以及用於登入的 ID 權杖的參數 id_token_hint 時，可以省略確認並自動重新導向至應用程式。

現有的部署會受到下列影響

有一個回溯相容性選項，允許您的應用程式仍然使用舊格式的 redirect_uri 參數。

當您啟動伺服器時，可以輸入以下命令來啟用此參數

透過此配置，您仍然可以使用帶有 redirect_uri 參數的格式。請注意，如果省略 id_token_hint，則需要確認畫面。

先前版本的 Keycloak 支援透過管理介面（例如管理控制台和 REST API）管理 JavaScript 程式碼。從此版本開始，這已不再可行，您現在應該將您的腳本部署到伺服器，以便配置以下供應商：

有關如何將腳本部署到伺服器的更多詳細資訊，請參閱文件。請注意，要使用腳本，您仍然需要啟用 scripts 技術預覽功能。

部署腳本時，伺服器會自動建立其對應的供應商，以便您在配置驗證流程、對應器和授權政策時選擇它們。

一般來說，更新您 realm 的步驟如下：

Patternfly (PF) React 函式庫已更新，@patternfly/react-core 從 v3.153.3 更新到 v4.147.0，@patternfly/react-icons 從 v3.15.16 更新到 v 4.11.8，以及 @patternfly/react-styles 從 v3.7.14 更新到 v4.11.8。進行了一些小的 UI 更新，使帳戶控制台與 PF 設計標準保持一致。

由於 PF 中有重大變更，自訂開發的帳戶 UI 可能與這些更新不相容。大多數重大變更應該可以透過更新 PF 元件上的屬性來解決。

資源

已知有重大變更的元件

metrics-enabled 選項現在僅啟用 Keycloak 的指標。要啟用就緒性和活動性健康端點，有一個新的布林選項 health-enabled。這允許更精細地使用這些選項，例如啟用指標但不啟用內部部署用例的就緒性/活動性探測。為了保持與之前設定 metrics-enabled=true 時相同的行為，您需要在建置 Keycloak 時額外設定 health-enabled=true。

Keycloak 的預設發行版現在由 Quarkus 提供支援，這為您配置 Keycloak 和部署自訂供應商帶來了一些重大變更。如需更多資訊，請參閱Quarkus 遷移指南。

Keycloak 的 WildFly 發行版現在已被棄用，支援將於 2022 年 6 月結束。我們建議盡快遷移至 Quarkus 發行版。但是，如果您需要在一段時間內繼續使用舊版 WildFly 發行版，則需要考慮一些變更：

如果您在遷移至 Quarkus 發行版時遇到問題、缺少配置某些內容的能力，或有一般想法和回饋，請在 GitHub Discussions 中開啟討論。

自從 Keycloak 15.1.0 中發布預覽 Quarkus 發行版以來，許多事情都發生了變化。了解變更的理想方式是查看新的伺服器指南。總而言之，變更包括：

如果您使用了包含 client-scopes 條件的政策並直接編輯 JSON 文件，則需要在 JSON 文件中將「scope」欄位名稱變更為「scopes」。

Liquibase 從版本 3.5.5 更新到 4.6.2，其中包括（除其他外）多個錯誤修復，以及使用 ServiceLoader 註冊自訂擴充功能的新方式。

從先前的 Keycloak 版本遷移到 Keycloak 17.0.0 已使用所有目前支援的資料庫進行了廣泛測試，但我們想強調務必仔細遵循升級指南，特別是在升級之前備份現有的資料庫。儘管我們盡力測試了 Liquibase 升級的後果，但某些安裝可能正在使用我們不知道的特定設定。

WildFly 25 棄用了舊版的安全子系統，該子系統用於配置 TLS 等。由於變更量很大，我們無法像過去那樣提供遷移腳本。

我們建議您不要複製先前版本 Keycloak 中的組態檔，而是從 Keycloak 16 中提供的預設組態檔開始，並套用相關的變更。

可以直接複製 Keycloak 子系統的組態。

有關 Elytron 子系統的更多資訊，請參閱WildFly 文件。

對於由此造成的不便，我們深感抱歉，並理解這將使每個人升級到 Keycloak 16 變得更加困難，但我們確實沒有找到替代方法。

值得指出的一件事是切換到 Quarkus 發行版，我們計劃在 Keycloak 17 中完全支援該發行版，這將使配置和升級 Keycloak 變得更加容易。

有關 WildFly 25 的更多資訊，請參閱WildFly 25 發行說明。

Keycloak 現在會遵循標準的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 環境變數來處理傳出的 HTTP 要求。如果您定義了 HTTP_PROXY 變數，但未在 SPI 組態中指定明確的 Proxy 對應，此變更可能會導致意外使用 Proxy 伺服器。若要防止 Keycloak 使用這些環境變數，您可以明確地為所有要求建立一個無 Proxy 路由：.*;NO_PROXY。

在此版本中，我們已棄用和/或標記為不受支援 Keycloak Operator 中的某些功能。這與 Backup CRD 和運算子管理的 Postgres 資料庫有關。

先前，在 Keycloak Operator 建立 Keycloak CR 的範例中新增了不受支援的指標擴充功能。這已被移除。

「用戶端原則」功能自 Keycloak 12 起為預覽功能，並未提供適當的支援。如果您曾試用此功能，並在 Keycloak 12 或 Keycloak 13 中設定了一些用戶端原則或用戶端設定檔，則需要在新版本中重新設定您的用戶端原則和用戶端設定檔。由於這僅為預覽功能，設定的格式已大幅變更，因此我們不提供在 Keycloak 12 或 Keycloak 13 中建立的用戶端原則和用戶端設定檔的自動移轉。

當 standalone.xml 包含任何 SmallRye 模組的參考時，需要手動變更。SmallRye 模組已從底層 WildFly 發行版本中移除，如果組態參考它們，伺服器將無法啟動。因此，如果 standalone.xml 中的組態參考這些模組，則透過 migrate-standalone.cli 進行的伺服器組態移轉會在對組態進行任何變更之前失敗。在這種情況下，要執行伺服器組態移轉，您必須手動移除所有參考 SmallRye 模組的行。在預設組態中，您需要特別移除以下幾行

Keycloak 伺服器已升級為使用 Wildfly 23 作為底層容器。這不會直接涉及任何特定的 Keycloak 伺服器功能，但請注意以下與移轉相關的變更

Keycloak 伺服器已升級為使用 Wildfly 22 作為底層容器。這不會直接涉及任何特定的 Keycloak 伺服器功能，但請注意以下與移轉相關的變更

已新增對唯讀使用者屬性的支援。這包括不應由使用者或管理員在透過 REST API 或 Keycloak 使用者介面更新使用者時編輯的使用者屬性。如果您使用以下功能，這可能會很重要

請參閱威脅模型緩解章節中的詳細資訊。

如果您使用 OpenID Connect 參數 request_uri，則要求您的用戶端必須設定 Valid Request URIs。這可以透過用戶端詳細資料頁面上的管理主控台或透過管理 REST API 或用戶端註冊 API 進行設定。有效的請求 URI 需要包含允許特定用戶端使用的請求 URI 值清單。這是為了避免 SSRF 攻擊。可以像 Valid Redirect URIs 選項一樣使用萬用字元或相對路徑，但出於安全目的，我們通常建議使用盡可能具體的值。

Keycloak 伺服器已升級為使用 Wildfly 22 作為底層容器。這不會直接涉及任何特定的 Keycloak 伺服器功能，但有一些與移轉相關的變更值得一提。

Keycloak 伺服器已升級為使用 Wildfly 21 作為底層容器。這不會直接涉及任何特定的 Keycloak 伺服器功能，但請注意以下與移轉相關的變更

使用 Docker 通訊協定成功驗證後，不會建立使用者工作階段。如需詳細資訊，請參閱伺服器管理指南。

Keycloak 登入佈景主題元件已升級至 PatternFly 4。舊的 PatternFly 3 與新的同時執行，因此可以保留 PF3 元件。但是，登入佈景主題的設計進行了一些變更。請將您的自訂登入佈景主題升級為它們。可以在 keycloak/examples/themes/theme/sunrise 目錄中找到包含必要變更的範例。無需額外設定。

從這個 Keycloak 版本開始，OAuth2 用戶端憑證授權端點預設不會發出重新整理權杖。此行為符合 OAuth2 規格。此變更的副作用是，在成功完成用戶端憑證驗證後，Keycloak 伺服器端不會建立使用者工作階段，從而提高了效能並減少了記憶體消耗。建議使用用戶端憑證授權的用戶端停止使用重新整理權杖，而是在每次請求時都使用 grant_type=client_credentials 進行驗證，而不是使用 refresh_token 作為授權類型。與此相關的是，Keycloak 支援在 OAuth2 撤銷端點中撤銷存取權杖，因此如果需要，允許用戶端撤銷個別存取權杖。

為了向後相容性，可以使用舊版本的行為。當使用此設定時，在成功使用用戶端憑證授權進行驗證後，仍會發出重新整理權杖，並且也會建立使用者工作階段。可以在 Keycloak 管理主控台的用戶端詳細資料中，在具有 OpenID Connect Compatibility Modes 的區段中使用 Use Refresh Tokens For Client Credentials Grant 開關來為特定用戶端啟用此功能。

Keycloak 伺服器已升級為使用 Wildfly 20 作為底層容器。這不會直接涉及任何特定的 Keycloak 伺服器功能，但請注意以下與移轉相關的變更

在先前的 Keycloak 版本中，當 LDAP 提供者設定為「關閉匯入使用者」（Import Users OFF）時，即使變更了一些非 LDAP 對應的屬性，仍然可以更新使用者。這種情況導致混淆的行為，屬性看起來似乎已更新，但實際上並未更新。在目前版本中，如果變更了任何非 LDAP 對應的屬性，則完全不允許執行更新。

這應該不會影響大多數的部署，但在一些罕見的情況下，某些部署可能會受到影響。例如，如果您先前嘗試使用管理 REST API 更新使用者，而該使用者有一些不正確的屬性變更，則更新是可能的。在目前版本中，更新是不可能的，並且您會立即收到相關原因的通知。

UserModel 中的欄位 username、email、firstName 和 lastName 已遷移至自訂屬性，以便在即將推出的版本中為 Keycloak 新增更複雜的使用者設定檔。如果資料庫包含具有這些確切名稱的自訂屬性的使用者，則需要在升級之前遷移這些自訂屬性。此遷移不會自動發生。否則，將不再從資料庫中讀取這些屬性，並且可能會被刪除。這種情況意味著現在也可以透過 UserModel.getFirstAttribute(UserModel.USERNAME) 來存取和設定 username。其他欄位也有類似的含義。直接或間接子類化 UserModel 的 SPI 實作者應確保 setUsername 和 setSingleAttribute(UserModel.USERNAME, …​) （以及其他欄位的類似情況）之間的行為一致。如果策略評估功能的使用者在其評估中使用屬性數量，則必須調整其策略，因為每個使用者現在預設都會有四個新的屬性。

UserModel 的公開 API 並未變更。不需要對前端資源或存取使用者資料的 SPI 進行任何變更。此外，資料庫尚未變更。

Instagram IdP 現在使用新的 API，因為舊的傳統 API 已被棄用。這需要取得新的 API 憑證。有關詳細資訊，請參閱伺服器管理指南。

對於使用 Instagram IdP 的現有使用者，尤其是那些只有此驗證選項的使用者，需要特別注意。這些使用者必須在 2020 年 9 月 30 日之前使用 Instagram IdP 登入 Keycloak。在那天之後，他們必須使用不同的驗證方法（例如密碼）登入，才能手動更新他們的 Instagram 社群連結，或在 Keycloak 中建立一個新的帳戶。這是因為 Instagram 使用者 ID 在舊的和新的 API 之間不相容，但是新的 API 會暫時傳回新舊的使用者 ID 以便進行遷移。一旦使用者登入，Keycloak 會自動遷移 ID。

在先前的版本中，Keycloak 公告了兩個內省端點：token_introspection_endpoint 和 introspection_endpoint。後者是 RFC-8414 定義的端點。前者先前已棄用，現在已被移除。

不再需要在 JavaScript 轉接器中設定 promiseType，並且兩者同時可用。建議盡快更新應用程式以使用原生 Promise API (then 和 catch)，因為傳統 API (success 和 error) 將會在某個時間點移除。

9.0.1 版本修正了一個可能會在領域中建立重複頂層群組的問題。然而，先前重複群組的存在會導致升級程序失敗。如果 Keycloak 伺服器使用 H2、MariaDB、MySQL 或 PostgreSQL 資料庫，則可能會受到此問題的影響。在啟動升級之前，請檢查伺服器是否包含重複的頂層群組。例如，可以在資料庫層級執行以下 SQL 查詢來列出它們

在每個領域中，只能有一個具有相同名稱的頂層群組。在升級之前，應檢查並刪除重複項。升級中的錯誤包含訊息 Change Set META-INF/jpa-changelog-9.0.1.xml::9.0.1- KEYCLOAK-12579-add-not-null-constraint::keycloak failed.

對於登入頁面如何選擇地區設定以及何時更新使用者的地區設定，已經進行了一些改進。

有關更多詳細資訊，請參閱伺服器管理指南。

在 2038 年，int 將無法再保存自 1970 年以來的秒數值，因此我們正在努力將這些值更新為 long 值。此外，權杖表示中還存在另一個與處理 int 值相關的問題。int 在 JSON 表示中預設會導致 0，但實際上不應該包含。

有關已棄用方法和取代方法的確切詳細資訊，請參閱 JavaDocs。

舊的請求和固定主機名稱提供者已替換為新的預設主機名稱提供者。請求和固定主機名稱提供者現在已棄用，建議盡快切換到預設主機名稱提供者。

Keycloak 伺服器已升級為使用 Wildfly 18 作為底層容器。這不直接涉及任何特定的 Keycloak 伺服器功能，但是，請注意與遷移相關的這些變更

直到現在，管理員仍然可以透過 Keycloak 管理主控台以及 RESTful 管理 API 將腳本上傳到伺服器。

從現在開始，此功能預設為停用，使用者應優先選擇直接將腳本部署到伺服器。有關更多詳細資訊，請參閱JavaScript 提供者。

在先前的版本中，開發人員可以將客戶端憑證提供給 JavaScript 轉接器。從現在開始，此功能已移除，因為客戶端應用程式無法安全地保存機密。

我們針對驗證流程進行了一些重構和改進，這需要在遷移期間注意。

我們為使用者憑證的儲存增加了更大的彈性。其中，每個使用者可以擁有相同類型的多個憑證，例如多個 OTP 憑證。因此，對資料庫結構描述進行了一些變更。但是，先前版本的憑證應會自動更新為新格式，使用者仍然可以使用先前版本中設定的密碼或 OTP 憑證登入。

Keycloak 伺服器已升級為使用 Wildfly 17 作為底層容器。這不直接涉及任何特定的 Keycloak 伺服器功能，但是，請注意與遷移相關的這些變更

Keycloak 伺服器已升級為使用 Wildfly 16 作為底層容器。這不直接涉及任何特定的 Keycloak 伺服器功能，但是，請注意與遷移相關的這些變更

我們新增了一個新的 microprofile-jwt 選用客戶端範圍，以處理 MicroProfile/JWT 驗證規格中定義的宣告。這個新的客戶端範圍定義了協定對應器，將已驗證使用者的使用者名稱設定為 upn 宣告，並將領域角色設定為 groups 宣告。

我們在 OIDC 身分提供者組態中新增了一個名為「接受來自客戶端的 prompt=none 轉送」的新開關，以識別能夠處理包含 prompt=none 查詢參數的轉送請求的 IDP。

直到目前為止，當收到 prompt=none 的授權請求時，如果使用者未在 realm 中驗證，realm 會返回 login_required 錯誤，而不會檢查使用者是否已由 IDP 驗證。從現在開始，如果可以為授權請求確定預設 IDP（透過使用 kc_idp_hint 查詢參數或為 realm 設定預設 IDP），並且 IDP 已啟用「接受來自用戶端的 prompt=none 轉發」開關，則授權請求會轉發到 IDP 以檢查使用者是否已在那裡驗證。

請務必注意，此開關僅在指定預設 IDP 時才會被考慮，在這種情況下，我們知道將授權請求轉發到哪裡，而無需提示使用者選擇 IDP。如果無法確定預設 IDP，我們無法假設將使用哪個 IDP 來滿足授權請求，因此不會執行請求轉發。

Keycloak 伺服器已升級為使用 Wildfly 15 作為底層容器。這不直接涉及任何特定的 Keycloak 伺服器功能，但是，請注意與遷移相關的這些變更

Keycloak 4.8.1 版本之前的 Google 身分提供者實作依賴 Google+ API 端點進行授權和獲取使用者設定檔。從 2019 年 3 月開始，Google 將取消對 Google+ API 的支援，轉而支援新的 Google 登入驗證系統。Keycloak 身分提供者已更新為使用新的端點，因此如果正在使用此整合，請確保您升級到 Keycloak 4.8.2 或更高版本。

如果您遇到錯誤，指出在目錄中找不到應用程式識別碼，您將必須在 Google API Console 入口網站中重新註冊用戶端應用程式，以獲取新的應用程式 ID 和密碼。

您可能需要調整自訂對應器，以處理 Google+ 使用者資訊端點提供的非標準宣告，這些宣告在 Google 登入 API 中使用不同的名稱提供。請查閱 Google 文件，以獲取有關可用宣告的最新資訊。

根據 LinkedIn 的說法，所有開發人員都需要遷移到其 API 的 2.0 版和 OAuth 2.0。因此，我們已更新我們的 LinkedIn 社群代理程式。

使用此代理程式的現有部署可能會在使用 LinkedIn API 的第 2 版擷取使用者設定檔時開始遇到錯誤。此錯誤可能與用於配置代理程式的用戶端應用程式缺少權限有關，該應用程式可能未被授權存取設定檔 API 或在驗證過程中請求特定的 OAuth2 範圍。

即使是新建立的 LinkedIn 用戶端應用程式，您也需要確保該用戶端能夠請求 r_liteprofile 和 r_emailaddress OAuth2 範圍（至少），以及該用戶端應用程式可以從 https://api.linkedin.com/v2/me 端點擷取目前成員的設定檔。

由於 LinkedIn 對於存取成員資訊的隱私限制，以及目前成員設定檔 API 返回的宣告集合有限，LinkedIn 社群代理程式現在使用成員的電子郵件地址作為預設使用者名稱。這意味著在驗證期間傳送授權請求時，始終會設定 r_emailaddress。

我們新增了新的 realm 預設用戶端範圍 roles 和 web-origins。這些用戶端範圍包含協定對應器，可將使用者的角色和允許的網頁來源新增至權杖。在遷移期間，這些用戶端範圍應自動新增到所有 OpenID Connect 用戶端作為預設用戶端範圍。因此，在資料庫遷移完成後，不需要進行任何設定。

若要將原生 JavaScript promise 與 JavaScript 轉接器一起使用，現在需要在初始化選項中將 promiseType 設定為 native。

過去，如果原生 promise 可用，則會返回一個包裝器，該包裝器同時提供舊版的 Keycloak promise 和原生 promise。這會導致問題，因為錯誤處理常式並非總是在原生錯誤事件之前設定，這會導致 Uncaught (in promise) 錯誤。

Keycloak 4.5.0 版本之前的 Microsoft 身分提供者實作依賴 Live SDK 端點進行授權和獲取使用者設定檔。從 2018 年 11 月開始，Microsoft 將取消對 Live SDK API 的支援，轉而支援新的 Microsoft Graph API。Keycloak 身分提供者已更新為使用新的端點，因此如果正在使用此整合，請確保您升級到 Keycloak 4.6.0 或更高版本。

由於應用程式 ID 格式的變更，在「Live SDK 應用程式」下註冊的舊版用戶端應用程式無法使用 Microsoft Graph 端點。如果您遇到錯誤，指出在目錄中找不到應用程式識別碼，您將必須在 Microsoft 應用程式註冊入口網站中重新註冊用戶端應用程式，以獲取新的應用程式 ID。

Keycloak 伺服器已升級為使用 Wildfly 14 作為底層容器。這不直接涉及任何特定的 Keycloak 伺服器功能，但是，請注意與遷移相關的這些變更

Keycloak 伺服器已升級為使用 Wildfly 13 作為底層容器。這不直接涉及任何特定的 Keycloak 伺服器功能，但是，請注意與遷移相關的這些變更

在之前的版本中，建議使用篩選器來指定允許的主機名稱。現在可以設定固定的主機名稱，這樣可以更輕鬆地確保使用有效的主機名稱，並且還允許內部應用程式透過替代 URL（例如內部 IP 位址）調用 Keycloak。建議您在生產環境中切換到這種方法。

我們新增了對用戶端範圍的支援，這在遷移期間需要一些注意。

我們新增了對 UMA 2.0 的支援。此版本的 UMA 規範針對如何從伺服器取得權限引入了一些重要的變更。

以下是 UMA 2.0 支援所引入的主要變更。詳情請參閱授權服務指南。

OpenID Connect 會話管理規範要求 OpenID Connect 驗證回應中必須存在參數 session_state。

在過去的版本中，我們沒有這個參數，但現在 Keycloak 預設會新增此參數，這是該規範的要求。

但是，某些 OpenID Connect/OAuth2 配接器，尤其是較舊的 Keycloak 配接器，可能存在此新參數的問題。

例如，在成功驗證到用戶端應用程式後，該參數將始終存在於瀏覽器 URL 中。在這些情況下，停用將 session_state 參數新增至驗證回應可能會很有用。這可以在 Keycloak 管理主控台中針對特定用戶端完成，在用戶端詳細資訊中，位於與舊版配接器的相容性中所述的「OpenID Connect 相容性模式」區段。有一個專用的「從驗證回應中排除會話狀態」開關，可以開啟以防止將 session_state 參數新增至驗證回應。

我們新增了兩種新的密碼雜湊演算法 (pbkdf2-sha256 和 pbkdf2-sha512)。新的領域將使用 pbkdf2-sha256 雜湊演算法，並使用 27500 次雜湊疊代。由於 pbkdf2-sha256 比 pbkdf2 稍快，因此疊代次數從 20000 次增加到 27500 次。

如果密碼原則包含雜湊演算法 (未指定) 和疊代次數 (20000) 的預設值，則會升級現有領域。如果您已變更雜湊疊代次數，則需要手動變更為 pbkdf2-sha256，如果您想使用更安全的雜湊演算法。

OpenID Connect 規範要求在初始授權請求中使用帶有值 openid 的參數 scope。因此，在 Keycloak 2.1.0 中，我們變更了我們的配接器，以在重新導向至 Keycloak 的 URI 中使用 scope=openid。現在我們也變更了伺服器部分，只有在真正使用 scope=openid 的情況下，才會將 ID 權杖傳送至應用程式。如果未使用，則會略過 ID 權杖，只會將存取權杖和重新整理權杖傳送至應用程式。這也允許您故意省略 ID 權杖的產生，例如為了空間或效能目的。

直接授權 (OAuth2 資源擁有者密碼憑證授權) 和服務帳戶登入 (OAuth2 用戶端憑證授權) 現在預設也不會使用 ID 權杖。您需要明確新增 scope=openid 參數才能包含 ID 權杖。

我們正在開發對多個資料中心的支援。作為初始步驟，我們引入了驗證會話和動作權杖。驗證會話取代了先前版本中使用的用戶端會話。目前動作權杖特別用於驗證器或 requiredActionProvider 需要向使用者傳送電子郵件並要求使用者按一下電子郵件中的連結的案例。

以下是與此相關的具體變更，可能會影響您的移轉。

與此相關的第一個變更是，在 standalone.xml 或 standalone-ha.xml 中引入新的 Infinispan 快取 authenticationSessions 和 actionTokens。如果您使用我們的移轉 CLI，則無需太擔心，因為您的 standalone(-ha).xml 檔案將會自動移轉。

第二個變更是變更驗證 SPI 方法中某些簽名。如果您使用自訂 Authenticator 或 RequiredActionProvider，這可能會影響您。類別 AuthenticationFlowContext 和 RequiredActionContext 現在允許擷取驗證會話，而不是用戶端會話。

我們也新增了對黏性會話的一些初始支援。您可能想要變更您的負載平衡器/Proxy 伺服器，並在您不希望受到它的影響並希望獲得更好的效能時設定它。路由已新增至新的 AUTH_SESSION_ID Cookie。更多資訊請參閱叢集文件。

另一個變更是，token.getClientSession() 已移除。如果您使用例如用戶端起始的身分識別 Broker 連結功能，這可能會影響您。

ScriptBasedAuthenticator 將繫結名稱從 clientSession 變更為 authenticationSession，因此如果您正在使用此驗證器，則需要更新您的指令碼。

最後，我們在管理主控台中新增了一些新的逾時。例如，這允許您為管理員和使用者本身觸發的電子郵件動作指定不同的逾時。

如果您從 2.2.0 或更舊的版本移轉，並且您使用了離線權杖，則您的離線權杖在權杖標頭中沒有 KID。我們在 2.3.0 中將 KID 新增至權杖標頭，同時新增了擁有多個領域金鑰的功能，因此 Keycloak 能夠根據權杖 KID 找到正確的金鑰。

對於沒有 KID 的離線權杖，Keycloak 2.5.1 將始終使用作用中的領域金鑰來尋找權杖驗證的正確金鑰。換句話說，舊版離線權杖的移轉將會正常運作。因此，例如，您的使用者在 1.9.8 中請求了離線權杖，然後您從 1.9.8 移轉到 2.5.1，然後您的使用者仍然能夠在 2.5.1 版本中重新整理其舊的離線權杖。

但是存在限制。一旦您變更領域作用中的金鑰，使用者將無法再重新整理舊的離線權杖。因此，在所有具有離線權杖的使用者重新整理其權杖之前，您不應該變更作用中的領域金鑰。顯然，新重新整理的權杖在標頭中將具有 KID，因此在所有使用者交換其舊的離線權杖後，您可以自由變更作用中的領域金鑰。

在 standalone.xml 或 standalone-ha.xml 設定檔中的 infinispan 子系統中定義的 realms 快取，現在預設具有 10000 個記錄的逐出。這與 users 快取的預設值相同。

此外，authorization 快取現在預設不會對其進行任何逐出。

keycloak-server-spi 模組已分割為 keycloak-server-spi 和 keycloak-server-spi-private。keycloak-server-spi 中的 API 在次要版本之間不會變更，而我們保留權利，並且很可能會在次要版本之間變更 keycloak-server-spi-private 中的 API。

SAML 判斷提示和文件中的金鑰現在使用 RSA-OAEP 加密方案進行加密。如果您想使用加密的判斷提示，請確保服務提供者瞭解此加密方案。在不太可能的情況下，如果 SP 無法處理新的方案，則可以在啟動時將系統屬性 keycloak.saml.key_trans.rsa_v1.5 設定為 true，使 Keycloak 使用舊版的 RSA-v1.5 加密方案。

即使您在叢集中使用 Keycloak，在 standalone-ha.xml 中的 infinispan 子系統中定義的快取 realms 和 users 現在也始終是本機快取。存在一個單獨的快取 work，它處理叢集節點之間的失效訊息傳送，並通知整個叢集底層 realms 和 users 快取中應該失效的記錄。

所有支援分頁的管理 REST API 端點現在都將預設最大結果數設定為 100。如果您想傳回超過 100 個項目，則需要使用 ?max=<RESULTS> 明確指定。

在 2.3.0 版本中，我們新增了對公開金鑰輪換的支援。當管理員在 Keycloak 管理主控台中輪換領域金鑰時，用戶端配接器將能夠識別它，並自動從 Keycloak 下載新的公開金鑰。但是，只有當您的配接器中沒有帶有硬式編碼公開金鑰的 realm-public-key 選項時，才會進行新的金鑰的自動下載。因此，我們不再建議在配接器設定中使用 realm-public-key 選項。

請注意，此選項仍然支援，但只有在您真的想在您的介面卡設定中硬式編碼公開金鑰，且永遠不從 Keycloak 下載公開金鑰時，才可能有用。理論上，其中一個原因可能是為了避免介面卡和 Keycloak 之間有不信任網路時發生的中間人攻擊。然而，在這種情況下，更好的選擇是使用 HTTPS，這將保護介面卡和 Keycloak 之間的所有請求。

在此版本中，我們在 infinispan 子系統中新增了新的快取 keys，該快取定義在 standalone.xml 或 standalone-ha.xml 設定檔中。它也定義了一些清除和到期設定。此快取在內部用於快取伺服器信任的實體（身分提供者或使用簽署 JWT 進行驗證的客戶端）的外部公開金鑰。

JPA 和 Mongo 的 databaseSchema 屬性現在已棄用，並由 initializeEmpty 和 migrationStrategy 取代。initializeEmpty 可以設定為 true 或 false，並控制是否應初始化空的資料庫。migrationStrategy 可以設定為 update、validate 和 manual。manual 僅支援關聯式資料庫，並會寫入一個 SQL 檔案，其中包含對資料庫結構描述的必要變更。請注意，對於 Oracle 資料庫，建立的 SQL 檔案包含 Oracle SQL 用戶端理解的 SET DEFINE OFF 命令。如果指令碼由任何其他用戶端使用，請將這些行替換為您選擇的工具的等效命令，該命令會停用變數擴展，或者如果此功能不適用，則完全刪除它。

以下情況會受到影響

身分提供者不再具有將其設定為預設驗證提供者的選項。而是前往驗證，選擇 Browser 流程並設定 身分提供者重新導向器。它具有設定預設身分提供者的選項。

不再支援從 1.0.0.Final 升級。若要升級至此版本，請先升級至 1.9.8.Final，然後再升級至 2.0.0。

新領域的預設密碼雜湊間隔已增加至 20K（先前為 1）。此變更將影響使用者驗證時的效能。例如，使用舊的預設值 (1)，雜湊密碼需要不到 1 毫秒的時間，但使用新的預設值 (20K)，相同的操作可能需要 50-100 毫秒。

將管理使用者新增至 Keycloak 的指令碼已重新命名為 add-user-keycloak。

我們已移除選項 auth-server-url-for-backend-requests，因為在某些使用情況下會出現問題。更詳細地說，可以從 2 個不同的環境 (內部和外部) 存取 Keycloak 伺服器，這導致權杖驗證等問題。

如果您仍然想要使用此選項提供的網路最佳化 (避免應用程式透過負載平衡器傳送後端請求，而是將它們直接傳送到本機 Keycloak 伺服器)，您可能需要在主機設定 (DNS) 層級處理它。

我們已將佈景主題和提供者目錄從 standalone/configuration/themes 和 standalone/configuration/providers 移動到分別是 themes 和 providers。如果您已新增自訂佈景主題和提供者，則需要將它們移動到新的位置。您也需要更新 keycloak-server.json，因為它已因此而變更。

先前，如果您已將我們的 SAML 或 OIDC Keycloak 子系統介面卡安裝到 WildFly 或 JBoss EAP 中，我們會自動將 Keycloak 用戶端 jar 包含到每個應用程式中，無論您是否使用 Keycloak。現在，只有在您為該介面卡開啟 Keycloak 驗證時（透過子系統或 web.xml 中的 auth-method），才會將這些程式庫新增至您的部署。

用戶端註冊服務端點已從 {realm-name}/clients 移動到 {realm-name}/clients-registrations。

在 OpenID Connect 驗證回應中，我們過去會將工作階段狀態傳回為 session-state，這不符合規格，並且已重新命名為 session_state。

在 1.2 中，我們已棄用許多與 OpenID Connect 規格不一致的端點，這些端點現在已移除。這也適用於驗證權杖端點，該端點已由 1.8 中的新內省端點取代。

template.ftl 中的意見反應已移動，且格式略有變更。

我們的大部分模組和原始碼都已整合到兩個 Maven 模組中：keycloak-server-spi 和 keycloak-services。SPI 介面位於 server-spi 中，實作位於 keycloak-services 中。所有 JPA 相依模組都已整合到 keycloak-model-jpa 下。mongo 和 Infinispan 也是如此，分別位於模組 keycloak-model-mongo 和 keycloak-model-infinispan 下。

為了堵塞安全性攻擊向量，對於支援此向量的平台 (Tomcat 8、Undertow/WildFly)，Keycloak OIDC 和 SAML 介面卡會在登入後變更工作階段 ID。您可以關閉此行為，請檢查介面卡設定開關。

Keycloak SAML SP 用戶端介面卡現在需要向您的 IDP 註冊特定端點 /saml。

在先前的版本中，我們隨附了具有預設密碼的預設管理員使用者，現在已移除此使用者。如果您要執行 1.8 的全新安裝，則必須先建立管理員使用者。

為了新增更多符合 OAuth2 規格的內容，我們新增了用於權杖內省的新端點。可以在 /realms/{realm-name}/protocols/openid-connect/token/introspect 存取新的端點，並且它完全基於 RFC-7662。

/realms/{realm-name}/protocols/openid-connect/validate 端點現在已棄用，我們強烈建議您盡快移至新的內省端點。此變更的原因是 RFC-7662 提供更標準且安全的內省端點。

現在可以從 OpenID Connect 提供者的設定 /realms/{realm-name}/.well-known/openid-configuration 取得新的權杖內省 URL。您會在回應中找到一個具有名稱 token_introspection_endpoint 的宣告。只有 機密用戶端 才允許叫用新的端點，這些用戶端通常會作為資源伺服器，並尋找權杖中繼資料以執行本機授權檢查。

為了新增更多符合 OpenID Connect 規格的內容，我們在管理控制台的「用戶端設定」頁面中新增了旗標，您可以在其中啟用/停用各種 OpenID Connect/OAuth2 流程（標準流程、隱含流程、直接存取授權、服務帳戶）。作為此流程的一部分，我們預設為新用戶端停用 直接存取授權（對應於 OAuth2 資源擁有者密碼認證授權）。

從先前版本移轉的用戶端只有在具有 僅直接授權 旗標時，才會啟用 直接存取授權。僅直接授權 旗標已移除，因為如果您啟用「直接存取授權」並停用「標準+隱含流程」，您將獲得相同的效果。

我們也為每個領域新增了內建用戶端 admin-cli。此用戶端已啟用 直接存取授權。因此，如果您使用管理 REST API 或 Keycloak 管理用戶端，您應該更新您的設定以使用 admin-cli，而不是 security-admin-console，因為後者預設不再啟用直接存取授權。

在此版本中，我們新增了 First Broker Login 功能，讓您可以指定當新使用者透過身分提供者（或社群提供者）登入，但沒有 Keycloak 使用者連結到該社群帳戶時，應執行的具體操作。作為這項工作的一部分，我們在身分提供者中新增了 First Login Flow 選項，您可以在其中指定流程，然後在管理控制台的「驗證 (Authentication)」標籤下設定此流程。

我們也從身分提供者設定中移除了 Update Profile On First Login 選項，並將其移至 Review Profile 驗證器的設定中。因此，一旦您指定身分提供者應使用的流程（預設為 First Broker Login 流程），請前往「驗證 (Authentication)」標籤，選擇該流程，然後在 Review Profile 驗證器下設定該選項。

web.xml 中的 form-error-page 將不再適用於用戶端配接器驗證錯誤。您必須為各種 HTTP 錯誤代碼定義 error-page。如果您想攔截並處理配接器錯誤情況，請參閱文件以瞭解更多詳細資訊。

介面本身和方法簽名沒有變更。但是，行為上存在一些變更。我們在此版本中新增了 First Broker Login 流程，並且現在會在 First Broker Login 流程完成後呼叫 IdentityProviderMapper.importNewUser 方法。因此，如果您想要在「檢閱設定檔 (Review Profile)」頁面中使用任何屬性，您需要使用 preprocessFederatedIdentity 方法，而不是 importNewUser。您可以透過呼叫 BrokeredIdentityContext.setUserAttribute 來設定任何屬性，這將在「檢閱設定檔 (Review profile)」頁面上可用。

舊版本的 Keycloak 允許多次重複使用重新整理權杖。Keycloak 仍然允許這樣做，但也有一個 Revoke refresh token 選項來禁止它。該選項位於管理控制台的權杖設定中。當重新整理權杖用於獲取新的存取權杖時，也會包含一個新的重新整理權杖。啟用該選項後，下次重新整理存取權杖時應使用此新的重新整理權杖。將無法多次重複使用舊的重新整理權杖。

我們進行了一些重組並重新命名了一些套件。這主要是關於重新命名 util 類別的內部套件。您應用程式中使用的大部分重要類別（例如 AccessToken 或 KeycloakSecurityContext）以及 SPI 仍然保持不變。但是，您可能會受到影響並需要更新類別的匯入。例如，如果您正在使用多租戶和 KeycloakConfigResolver，您將會受到影響，例如 HttpFacade 類別已移至不同的套件 - 現在是 org.keycloak.adapters.spi.HttpFacade。

我們在此版本中新增了對離線權杖的支援，這表示我們現在將「離線」使用者工作階段持久化到資料庫中。如果您未使用離線權杖，則不會為您持久化任何內容，因此您不必擔心更多 DB 寫入會導致效能變差。但是，在所有情況下，您都需要更新 standalone/configuration/keycloak-server.json 並新增 userSessionPersister，如下所示

如果您希望將工作階段持久化到 Mongo 而不是傳統的 RDBMS 中，請改用提供者 mongo。

Infinispan 現在是預設且唯一的領域和使用者快取提供者。在非叢集模式下，使用本機 Infinispan 快取。我們也移除了自訂的記憶體內快取和無快取提供者。如果您在 keycloak-server.json 中將 realmCache 或 userCache 設定為 mem 或 none，請將其移除。由於 Infinispan 是唯一的提供者，因此不再需要 realmCache 和 userCache 物件，可以將其移除。

Infinispan 現在是預設且唯一的使用者工作階段提供者。在非叢集模式下，使用本機 Infinispan 快取。我們也移除了 JPA 和 Mongo 使用者工作階段提供者。如果您在 keycloak-server.json 中將 userSession 設定為 mem、jpa 或 mongo，請將其移除。由於 Infinispan 是唯一的提供者，因此不再需要 userSession 物件，可以將其移除。

對於任何想要提高使用者工作階段持久性的人來說，可以透過將使用者工作階段快取設定為多個擁有者或使用複寫快取來實現。也可以設定 Infinispan 來持久化快取，儘管這會對效能產生影響。

在預設主題中，我們現在已從註冊頁面和帳戶管理中移除了聯絡方式。管理控制台現在會列出所有使用者屬性，而不僅僅是聯絡方式的特定屬性。管理控制台還具有新增/移除使用者屬性的功能。如果您想新增聯絡方式，請參閱範例中包含的 address 主題。

過去，直接授權 API（或資源擁有者密碼憑證）預設為停用，並且存在在領域上啟用它的選項。直接授權 API 現在永遠啟用，並且已移除在領域上啟用/停用的選項。

再次有一些資料庫變更。請記得在升級之前備份您的資料庫。

UserFederationProvider 介面有一些微小的變更。您可能需要在升級到較新版本並升級一些已變更簽名的方法時同步您的實作。變更很小，但需要改進同盟的效能。

繼上次版本中所做的發佈變更之後，Keycloak 的獨立下載現在基於 WildFly 9.0.0.Final。這也會影響只能部署到 WildFly 9.0.0.Final 或 JBoss EAP 6.4.0.GA 的覆蓋。伺服器不再支援 WildFly 8.2.0.Final。

現在有 3 個針對 WildFly、JBoss EAP 和 JBoss AS7 的單獨配接器下載