伺服器管理指南

語言環境選擇器提供者會根據可用的資訊建議最佳語言環境。但是，使用者通常是未知的。因此，先前經過驗證的使用者的語言環境會儲存在持久的 Cookie 中。

選擇語言環境的邏輯使用以下可用的第一項

當使用者經過驗證時，會觸發一個動作來更新前面提到的持久 Cookie 中的語言環境。如果使用者已在登入頁面上透過語言環境選擇器主動切換語言環境，則使用者的語言環境也會在此時更新。

如果您想要變更選擇語言環境的邏輯，您可以選擇建立自訂的 LocaleSelectorProvider。如需詳細資訊，請參閱伺服器開發人員指南。

如果您啟用 忘記密碼，使用者如果忘記密碼或遺失 OTP 產生器，可以重設其登入憑證。

電子郵件中傳送的文字是可設定的。如需更多資訊，請參閱伺服器開發人員指南。

當使用者點擊電子郵件連結時，Keycloak 會要求他們更新密碼，如果他們設定了 OTP 產生器，Keycloak 會要求他們重新設定 OTP 產生器。根據您組織的安全性要求，您可能不希望使用者透過電子郵件重設其 OTP 產生器。

若要變更此行為，請執行下列步驟

已登入的使用者關閉其瀏覽器會終止其工作階段，而該使用者必須再次登入。如果該使用者在登入時點擊記住我核取方塊，您可以將 Keycloak 設定為保持使用者的登入工作階段開啟。此動作會將登入 Cookie 從僅限工作階段的 Cookie 變更為持久的 Cookie。

在領域的一般設定中，您可以定義哪個 驗證內容類別參考 (ACR) 值對應到哪個 驗證等級 (LoA)。ACR 可以是任何值，而 LoA 必須是數值。acr 宣告可以在 OIDC 請求中傳送的 claims 或 acr_values 參數中請求，並且也包含在存取權杖和 ID 權杖中。對應的數字會用於驗證流程條件中。

如果特定用戶端需要使用與領域不同的值，也可以在用戶端層級指定對應。但是，最佳做法是堅持使用領域對應。

如需更多詳細資訊，請參閱逐步驗證和官方 OIDC 規格。

使用此工作流程，使用者必須使用 UPDATE_EMAIL 動作來變更自己的電子郵件地址。

此動作與單一電子郵件輸入表單相關聯。如果領域停用了電子郵件驗證，此動作將允許在沒有驗證的情況下更新電子郵件。如果領域啟用了電子郵件驗證，此動作將傳送電子郵件更新動作權杖到新的電子郵件地址，而不會變更帳戶電子郵件。只有觸發動作權杖才會完成電子郵件更新。

應用程式能夠透過將 UPDATE_EMAIL 作為AIA (應用程式起始的動作)來將其使用者傳送到電子郵件更新表單。

我們建議您定期輪換金鑰。首先，建立優先順序高於現有有效金鑰的新金鑰。您也可以建立與先前金鑰相同優先順序的新金鑰，並將先前的金鑰設為被動。

一旦新的金鑰可用，所有新的權杖和 Cookie 都將使用新的金鑰簽署。當使用者向應用程式驗證身分時，SSO Cookie 會以新的簽名更新。當 OpenID Connect 權杖更新時，新的權杖會使用新的金鑰簽署。最終，所有 Cookie 和權杖都將使用新的金鑰，過一段時間後，舊的金鑰即可移除。

刪除舊金鑰的頻率是在安全性與確保所有 Cookie 和權杖都更新之間的一種權衡。考慮每三到六個月建立新的金鑰，並在建立新金鑰後的一到兩個月刪除舊的金鑰。如果使用者在新金鑰新增到舊金鑰移除期間處於非活動狀態，則該使用者必須重新驗證身分。

輪換金鑰也適用於離線權杖。為了確保它們已更新，應用程式需要在移除舊金鑰之前重新整理權杖。

使用此程序產生金鑰配對，包括自我簽署憑證。

變更提供者的優先順序不會導致金鑰重新產生，但如果您想變更金鑰大小，您可以編輯提供者，系統會產生新的金鑰。

您可以透過從 RSA 產生的金鑰配對中擷取憑證，並在新金鑰儲存區中使用該憑證來輪換金鑰。

若要新增從其他地方取得的金鑰配對和憑證，請選取 提供者，然後從下拉選單中選擇 rsa。您可以變更優先順序，以確保新的金鑰配對成為有效的金鑰配對。

若要新增儲存在主機上的 Java 金鑰儲存區檔案中的金鑰配對和憑證，請選取 提供者，然後從下拉選單中選擇 java-keystore。您可以變更優先順序，以確保新的金鑰配對成為有效的金鑰配對。

若要載入相關聯的憑證鏈，必須將其匯入到 Java 金鑰儲存區檔案，並使用與載入金鑰配對相同的 金鑰別名。

Keycloak 會將簽署金鑰僅儲存在本機，且永遠不會與用戶端應用程式、使用者或其他實體共用。但是，如果您認為您的 realm 簽署金鑰已遭洩漏，您應該先如上所述產生新的金鑰配對，然後立即移除遭洩漏的金鑰配對。

或者，您可以從 提供者 表格中刪除提供者。

推送 not-before 原則可確保用戶端應用程式不接受遭洩漏金鑰所簽署的現有權杖。用戶端應用程式會強制從 Keycloak 下載新的金鑰配對，因此遭洩漏金鑰所簽署的權杖將失效。

Keycloak 會將使用者從 LDAP 匯入到本機 Keycloak 使用者資料庫。這個使用者資料庫的副本會根據需要或透過定期背景工作同步。密碼同步是個例外。Keycloak 絕不會匯入密碼。密碼驗證一律在 LDAP 伺服器上進行。

同步的優點是，所有 Keycloak 功能都能有效運作，因為任何需要的額外使用者資料都會儲存在本機。缺點是，每當 Keycloak 第一次查詢特定使用者時，Keycloak 都會執行對應的資料庫插入。

您可以與 LDAP 伺服器同步匯入。當 LDAP 對應器總是從 LDAP 而非資料庫讀取特定屬性時，匯入同步是不必要的。

您可以在不將使用者匯入 Keycloak 使用者資料庫的情況下使用 LDAP 與 Keycloak。LDAP 伺服器會備份 Keycloak 執行階段使用的通用使用者模型。如果 LDAP 不支援 Keycloak 功能所需的資料，該功能將無法運作。這種方法的優點是，您不會有將 LDAP 使用者副本匯入和同步到 Keycloak 使用者資料庫的資源使用量。

LDAP 設定頁面上的 匯入使用者 開關控制此儲存模式。若要匯入使用者，請將此開關切換為 開啟。

使用者和管理員可以修改使用者中繼資料，使用者透過帳戶主控台，管理員透過管理主控台。LDAP 設定頁面上的 編輯模式 設定定義了使用者的 LDAP 更新權限。

當您設定與 LDAP 存放區的安全連線 URL (例如，ldaps://myhost.com:636) 時，Keycloak 會使用 SSL 與 LDAP 伺服器通訊。在 Keycloak 伺服器端設定信任存放區，以便 Keycloak 可以信任與 LDAP 的 SSL 連線 - 請參閱設定信任存放區指南。

使用信任存放區 SPI 設定屬性已過時。它通常應保留為 Always。

如果您設定了 匯入使用者 選項，LDAP 提供者會處理將 LDAP 使用者匯入到 Keycloak 本機資料庫。當使用者第一次登入或作為使用者查詢的一部分傳回時 (例如，使用管理主控台中的搜尋欄位)，LDAP 提供者會將 LDAP 使用者匯入到 Keycloak 資料庫。在驗證期間，會驗證 LDAP 密碼。

如果您想要將所有 LDAP 使用者同步到 Keycloak 資料庫，請在 LDAP 提供者設定頁面上設定並啟用 同步設定。

存在兩種同步類型

最佳的同步方式是，當您第一次建立 LDAP 提供者時，按一下 同步所有使用者，然後設定定期同步變更的使用者。

LDAP 對應器是 LDAP 提供者觸發的 接聽器。它們提供 LDAP 整合的其他擴充點。當下列情況時，會觸發 LDAP 對應器

當您建立 LDAP 聯合提供者時，Keycloak 會自動為此提供者提供一組 對應器。使用者可以變更此組，他們也可以開發對應器或更新/刪除現有的對應器。

將基本 Keycloak 使用者屬性 (例如使用者名稱、名字、姓氏和電子郵件) 對應到對應 LDAP 屬性的使用者屬性對應器。您可以擴充這些對應器並提供您自己的其他屬性對應。管理主控台提供工具提示，以協助設定對應的對應器。

當 Keycloak 更新密碼時，Keycloak 會以純文字格式傳送密碼。此動作與更新內建 Keycloak 資料庫中的密碼不同，在 Keycloak 中，Keycloak 會在將密碼傳送到資料庫之前雜湊並加鹽處理密碼。對於 LDAP，Keycloak 依賴 LDAP 伺服器來雜湊和加鹽處理密碼。

預設情況下，LDAP 伺服器（如 MSAD、RHDS 或 FreeIPA）會雜湊並加鹽處理密碼。其他 LDAP 伺服器（如 OpenLDAP 或 ApacheDS）則會以純文字儲存密碼，除非您使用 RFC3062 中描述的 LDAPv3 密碼修改擴展操作。請在 LDAP 設定頁面啟用 LDAPv3 密碼修改擴展操作。如需更多詳細資訊，請參閱您的 LDAP 伺服器的文件。

為了在管理 LDAP 連線時提高效率，並在處理多個連線時改善效能，您可以啟用連線池。如此一來，當連線關閉時，它會返回池中供未來使用，從而降低不斷建立新連線的成本。

LDAP 連線池設定是使用以下系統屬性來設定的

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

若要設定任何這些屬性，您可以設定 JAVA_OPTS_APPEND 環境變數

將類別 org.keycloak.storage.ldap 的記錄層級提高到 TRACE 會很有幫助。使用此設定，許多記錄訊息會以 TRACE 層級傳送到伺服器記錄檔，包括所有傳送到 LDAP 伺服器的查詢記錄，以及用於傳送查詢的參數。當您在使用者論壇或 JIRA 上建立任何 LDAP 問題時，請考慮附加啟用 TRACE 記錄的伺服器記錄檔。如果記錄檔太大，比較好的替代方法是僅包含伺服器記錄檔中在造成您問題的操作期間新增到記錄檔的訊息片段。

它會顯示您的 LDAP 提供者的設定。在您提出問題或回報錯誤之前，最好包含此訊息以顯示您的 LDAP 設定。您可以選擇性地將您不想包含的一些組態變更替換為一些佔位符值。一個範例是 bindDn=some-placeholder。對於 connectionUrl，您也可以隨意替換它，但通常至少包含所使用的協定（ldap vs ldaps）會很有幫助。同樣地，包含您的 LDAP 對應器的設定詳細資訊也會很有幫助，這些詳細資訊會以類似這樣的訊息在 DEBUG 層級顯示

請注意，這些訊息只會在啟用 DEBUG 記錄時顯示。

如果即使在伺服器重新啟動後也沒有出現更多關於連線池的訊息，則可能表示連線池不適用於您的 LDAP 伺服器。

FreeIPA 容器映像可在 Quay.io 上取得。若要設定 FreeIPA 伺服器，請參閱 FreeIPA 文件。

聯盟提供者使用 D-BUS 從 SSSD 取得資料。它使用 PAM 對資料進行驗證。

Keycloak 使用 DBus-Java 專案以在低層級與 D-Bus 進行通訊，並使用 JNA 以透過作業系統可插拔驗證模組 (PAM) 進行驗證。

雖然現在 Keycloak 包含執行 SSSD 提供者所需的所有程式庫，但需要 JDK 21 版。因此，只有在主機組態正確且使用 JDK 21 執行 Keycloak 時，才會顯示 SSSD 提供者。

安裝後，設定聯合 SSSD 儲存區。

現在您可以使用 FreeIPA/IdM 使用者和認證針對 Keycloak 進行驗證。

預設情況下，Keycloak 提供基本的使用者設定檔設定，涵蓋一些最常見的使用者屬性

在 Keycloak 中，username 和 email 屬性都有特殊的處理方式，因為它們通常用於識別、驗證和連結使用者帳戶。對於這些屬性，您只能變更其設定，而不能移除它們。

正如您將在以下章節中看到的那樣，您可以自由地透過引入您自己的屬性或變更任何可用屬性的設定來變更預設設定，以使其更適合您的需求。

在 Keycloak 中，使用者是透過不同的上下文進行管理的

除了 管理 上下文之外，所有其他上下文都被視為終端使用者上下文，因為它們與使用者自助服務流程相關。

了解這些上下文對於了解您的使用者設定檔設定在管理使用者時將在何處生效非常重要。無論使用者在何種上下文下被管理，都將使用相同的使用者設定檔設定來呈現 UI 和驗證屬性值。

正如您將在以下章節中看到的那樣，您可以限制某些屬性僅在管理上下文中可用，並完全停用它們以供終端使用者使用。如果您不希望管理員存取某些使用者屬性，而只希望終端使用者存取，反之亦然。

預設情況下，Keycloak 只會識別在您的使用者設定檔設定中定義的屬性。伺服器會忽略未在此處明確定義的任何其他屬性。

透過嚴格限制可以為您的使用者設定哪些使用者屬性，以及如何驗證其值，Keycloak 可以為您的 Realm 新增另一個防禦屏障，並幫助您防止與使用者相關聯的意外屬性和值。

也就是說，使用者屬性可以分類如下

儘管預設情況下停用了不受管理的屬性，您可以使用不同的策略來設定您的 Realm，以定義伺服器如何處理它們。為此，點擊左側選單中的 Realm 設定，點擊 一般 標籤，然後從 不受管理的屬性 設定中選擇以下任何選項

這些策略讓您可以精細控制伺服器如何處理不受管理的屬性。您可以選擇完全停用或僅在透過管理上下文管理使用者時支援不受管理的屬性。

啟用不受管理的屬性時（即使是部分啟用），您也可以從使用者詳細資訊 UI 的 屬性 標籤中的管理控制台管理它們。如果策略設定為 已停用，則此標籤不可用。

作為安全建議，請盡可能遵守最嚴格的策略（例如：已停用 或 管理員可以編輯），以防止使用者在透過終端使用者上下文管理其設定檔時為其設定意外的屬性（和值）。避免設定 已啟用 策略，並優先在您的控制下，在您的使用者設定檔設定中定義所有終端使用者可以管理的屬性。

正如您將在以下章節中看到的那樣，您也可以透過選擇屬性是否應對使用者和/或管理員可見或可寫入來限制屬性的目標對象。

對於不受管理的屬性，最大長度為 2048 個字元。若要指定不同的最小或最大長度，請將不受管理的屬性變更為受管理的屬性，並新增 length 驗證器。

使用者設定檔設定是按每個 Realm 進行管理的。為此，請點擊左側選單中的 Realm 設定 連結，然後點擊 使用者設定檔 標籤。

在 屬性 子標籤中，您會看到所有受管理屬性的清單。

在 屬性群組 子標籤中，您可以管理屬性群組。屬性群組允許您關聯屬性，以便在呈現面向使用者的表單時將它們一起顯示。

在 JSON 編輯器 子標籤中，您可以檢視和編輯 JSON 設定。您可以使用此標籤來獲取您目前的設定或手動管理它。您對此標籤所做的任何變更都會反映在其他標籤中，反之亦然。

在下一節中，您將學習如何管理屬性。

在 Attributes 子索引標籤中，您可以建立、編輯和刪除受管理的屬性。

若要定義新屬性並將其與使用者設定檔建立關聯，請按一下屬性清單頂端的「建立屬性」按鈕。

設定屬性時，您可以定義以下設定

當您建立屬性時，該屬性僅在管理內容中可用，以避免意外地將屬性暴露給最終使用者。實際上，當最終使用者透過最終使用者內容管理其設定檔時，他們無法存取該屬性。您可以隨時根據您的需求變更「權限」設定。

您可以啟用對受管理屬性的驗證，以確保屬性值符合特定規則。為此，您可以在管理屬性時從「驗證」設定新增或移除驗證器。

當寫入屬性時，會隨時進行驗證，並且它們可能會擲回錯誤，當值未通過驗證時，錯誤會顯示在 UI 中。

基於安全考量，每個可由使用者編輯的屬性都應具有驗證，以限制使用者輸入的值的大小。如果未指定 length 驗證器，則 Keycloak 預設最大長度為 2048 個字元。

為了將其他資訊傳遞給前端，可以使用註解裝飾屬性，以指示如何呈現屬性。當擴充 Keycloak 主題以根據與屬性相關聯的註解動態呈現頁面時，此功能主要有用。

註解用於，例如，變更屬性的 HTML type和變更屬性的 DOM 表示，您將在以下章節中看到。

註解是與 UI 共用的索引鍵/值配對，以便它們可以變更與屬性對應的 HTML 元素的呈現方式。只要您的領域使用的主題支援註解，您就可以為屬性設定任何您想要的註解。

在 [屬性群組] 子索引標籤中，您可以建立、編輯和刪除屬性群組。屬性群組可讓您定義相關屬性的容器，以便在面向使用者的表單中一起呈現它們。

若要建立新的群組，請按一下屬性群組清單頂端的 [建立屬性群組] 按鈕。

設定群組時，您可以定義下列設定

使用者設定檔配置使用定義完善的 JSON 綱要儲存。您可以選擇直接編輯使用者設定檔配置，方法是點擊 JSON 編輯器 子索引標籤。

JSON 綱要定義如下

此綱要支援您需要的任意數量的屬性和群組。

unmanagedAttributePolicy 屬性通過設定以下值之一來定義非受管屬性策略。如需更多詳細資訊，請參閱了解受管和非受管屬性。

所有使用者設定檔內容（包括管理控制台）中的 UI 都會根據您的使用者設定檔配置動態呈現。

預設的呈現機制提供以下功能

為了確保終端使用者設定檔符合配置，管理員可以使用 VerifyProfile 必要的動作，以便在使用者驗證 Keycloak 的身分時，最終強制他們更新設定檔。

啟用後，VerifyProfile 動作將在使用者驗證身分時執行以下步驟

預設情況下會啟用 VerifyProfile 動作。若要停用此動作，請點擊左側選單中的 Authentication 連結，然後點擊 Required Actions 索引標籤。在此索引標籤上，使用 VerifyProfile 動作的 **Enabled** 開關來停用它。

如果您希望在設定屬性、屬性群組和註解時使用國際化訊息，您可以使用將轉換為訊息套件中訊息的預留位置，來設定它們的顯示名稱、描述和值。

為此，您可以使用預留位置來解析訊息金鑰，例如 ${myAttributeName}，其中 myAttributeName 是訊息套件中訊息的金鑰。如需更多詳細資訊，請參閱關於如何將訊息套件新增至自訂主題的伺服器開發人員指南。

如果使用者已經有密碼，可以在 **Reset Password** 區段中重設密碼。

您也可以請求使用者重設密碼。

或者，您可以傳送電子郵件給使用者，要求使用者重設 OTP 產生器。如果使用者已經擁有 OTP 憑證，以下程序也適用。

啟用此設定後，管理主控台的登入頁面上會顯示 註冊 連結。

您可以設定任何使用者都必須執行的動作。

您可以指定所有新使用者首次登入前必須執行的動作。這些要求適用於在 使用者 頁面上使用 新增使用者 按鈕建立的使用者，或是登入頁面上的 註冊 連結。

您可以啟用一項必要動作，讓新使用者在首次登入 Keycloak 之前必須接受條款及細則。

如果使用者因作用中的 SSO 工作階段而已經過驗證，則該使用者通常不需要主動重新驗證。但是，如果該使用者主動驗證的時間超過五分鐘，則當請求某些 AIA 時，客戶端仍然可以請求重新驗證。此指引有以下例外情況：

某些 AIA 可能需要與動作名稱一起傳送參數。例如，只有透過 AIA 才能觸發 刪除憑證 動作，並且需要與動作名稱一起傳送參數，該參數指向已移除憑證的 ID。因此，此範例的 URL 將會是 kc_action=delete_credential:ce1008ac-f811-427f-825a-c0b878d1c24b。在這種情況下，冒號字元後面的部分 (ce1008ac-f811-427f-825a-c0b878d1c24b) 包含要刪除的特定使用者憑證的 ID。刪除憑證 動作會顯示確認畫面，使用者可以在其中確認同意刪除該憑證。

若要查看所有可用的動作，請登入管理主控台，然後前往右上角，按一下 [領域資訊] → [提供者資訊] 索引標籤 → 尋找提供者 required-action。但是請注意，這可能會根據您領域中啟用了哪些動作，在 必要動作索引標籤中進一步限制。

您可以在 [必要動作] 索引標籤上啟用此功能。

您可以賦予特定使用者可刪除帳戶的角色。

一旦您擁有 delete-account 角色，您就可以刪除自己的帳戶。

您可以登出 realm 中的所有使用者。從 Action 清單中，選取 Sign out all active sessions（登出所有活動中的工作階段）。所有 SSO cookie 都會失效。Keycloak 會使用 Keycloak OIDC 用戶端配接器通知用戶端登出事件。在作用中的瀏覽器工作階段中請求驗證的用戶端必須重新登入。SAML 等用戶端類型不會收到後端通道登出請求。

複合角色與群組相似，因為它們提供相同的功能。它們之間的區別在於概念上的差異。複合角色將權限模型套用至一組服務和應用程式。使用複合角色來管理應用程式和服務。

群組著重於使用者集合及其在組織中的角色。使用群組來管理使用者。

此螢幕截圖顯示已存在一些預設群組。

Keycloak 中可供您的 OTP 產生器使用的演算法有基於時間和基於計數器兩種。

使用基於時間的一次性密碼 (TOTP)，權杖產生器會雜湊目前的時間和共用機密。伺服器會藉由比較一段時間範圍內的雜湊值與提交的值來驗證 OTP。TOTP 在短時間範圍內有效。

使用基於計數器的一次性密碼 (HOTP)，Keycloak 會使用共用計數器而非目前的時間。Keycloak 伺服器會在每次成功 OTP 登入時遞增計數器。有效的 OTP 會在成功登入後變更。

TOTP 比 HOTP 更安全，因為可匹配的 OTP 在短時間範圍內有效，而 HOTP 的 OTP 在不確定的時間內有效。HOTP 比 TOTP 更方便使用者，因為輸入 OTP 沒有時間限制。

HOTP 每次伺服器遞增計數器時都需要更新資料庫。此更新會在負載繁重時消耗驗證伺服器的效能。為了提高效率，TOTP 不會記住已使用的密碼，因此不需要執行資料庫更新。缺點是可以在有效時間間隔內重複使用 TOTP。

Keycloak 有數個內建流程。您無法修改這些流程，但您可以變更流程的需求以符合您的需求。

在設計流程時，會應用重要的功能和安全性考量。

若要建立流程，請執行以下步驟：

建立新流程時，您必須先建立一個頂層流程，並具有以下選項：

當 Keycloak 建立流程後，Keycloak 會顯示 新增步驟 和 新增子流程 按鈕。

有三個因素決定流程和子流程的行為：

執行有多種動作，從發送重設電子郵件到驗證 OTP。使用 新增步驟 按鈕新增執行。

身份驗證執行可以選擇性地設定參考值。身份驗證方法參考 (AMR) 協定對應器可以使用此值來填入 OIDC 存取和 ID 權杖中的 amr 宣告（有關 AMR 宣告的更多資訊，請參閱 RFC-8176）。當為用戶端設定 身份驗證方法參考 (AMR) 協定對應器時，它會使用使用者在身份驗證流程中成功完成的任何驗證器執行的參考值，來填入 amr 宣告。

有兩種執行類型，自動執行 和 互動式執行。自動執行 類似於 Cookie 執行，並且會在流程中自動執行其動作。互動式執行 會暫停流程以獲取輸入。成功執行的執行會將其狀態設定為 success。若要完成流程，它至少需要一個狀態為 success 的執行。

您可以使用 新增子流程 按鈕，將子流程新增至頂層流程。新增子流程 按鈕會顯示 建立執行流程 頁面。此頁面類似於 建立頂層表單 頁面。不同之處在於 流程類型 可以是 basic（預設）或 form。form 類型會建構一個子流程，為使用者產生一個表單，類似於內建的 註冊 流程。子流程是否成功取決於其執行如何評估，包括其包含的子流程。有關子流程如何運作的深入說明，請參閱 執行需求章節。

流程中的所有元素在其旁邊都有 刪除 選項。某些執行具有 ⚙️ 選單項目（齒輪圖示）來設定執行。也可以使用 新增步驟 和 新增子流程 連結，將執行和子流程新增至子流程。

由於執行的順序很重要，您可以透過拖曳其名稱來上下移動執行和子流程。

為了說明流程的建立，本節將描述如何建立進階瀏覽器登入流程。此流程的目的是讓使用者可以選擇使用 WebAuthn 以無密碼方式登入，或是使用密碼和 OTP 進行雙因素驗證。

在此階段，表單需要使用者名稱，但不需要密碼。我們必須啟用密碼驗證，以避免安全性風險。

最後，變更繫結。

輸入使用者名稱後，流程的運作方式如下：

如果使用者已記錄 WebAuthn 無密碼憑證，他們可以使用這些憑證直接登入。這是無密碼登入。使用者也可以選取 帶有 OTP 的密碼，因為 WebAuthn 無密碼 執行和 帶有 OTP 的密碼 流程設定為 替代。如果它們設定為 必要，使用者必須輸入 WebAuthn、密碼和 OTP。

如果使用者選取帶有 WebAuthn 無密碼 身份驗證的 嘗試其他方式 連結，使用者可以在 密碼 和 密鑰（WebAuthn 無密碼）之間選擇。當選取密碼時，使用者需要繼續並使用指派的 OTP 登入。如果使用者沒有 WebAuthn 憑證，則必須輸入密碼，然後輸入 OTP。如果使用者沒有 OTP 憑證，系統會要求他們記錄一個。

本節描述如何使用逐步升級機制建立進階瀏覽器登入流程。逐步升級身份驗證的目的是根據使用者的特定身份驗證等級，允許存取用戶端或資源。

現在，您為第一個身份驗證等級設定流程。

現在，您要設定第二個驗證層級的流程。

最後，變更繫結。

若要使用逐步機制，您需要在驗證請求中指定要求的驗證層級 (LoA)。claims 參數用於此目的

claims 參數以 JSON 表示法指定

Keycloak JavaScript 介面卡支援輕鬆建構此 JSON 並在登入請求中傳送。如需更多詳細資訊，請參閱「保護應用程式」章節中的「Keycloak JavaScript 介面卡」。

您也可以使用較簡單的參數 acr_values，而不是 claims 參數來請求特定的層級，但這些層級並非必要。這在 OIDC 規格中有提到。

您也可以為特定的用戶端設定預設層級，當參數 acr_values 或帶有 acr 宣告的參數 claims 不存在時，會使用此層級。如需更多詳細資訊，請參閱 用戶端 ACR 設定)。

如需更多詳細資訊，請參閱 官方 OIDC 規格。

流程邏輯

先前設定的驗證流程的邏輯如下
如果用戶端請求較高的驗證層級，也就是驗證層級 2 (LoA 2)，使用者必須執行完整的雙因素驗證：使用者名稱/密碼 + OTP。但是，如果使用者在 Keycloak 中已經有工作階段，該工作階段是使用使用者名稱和密碼 (LoA 1) 登入的，則只會要求使用者提供第二個驗證因素 (OTP)。

條件中的「最長存留時間」選項會決定後續驗證層級的有效時間 (秒數)。此設定有助於判斷使用者是否會在後續驗證期間再次被要求提供驗證因素。如果 claims 或 acr_values 參數要求特定層級 X，且使用者已經使用層級 X 進行驗證，但已過期 (例如，最長存留時間設定為 300，且使用者在 310 秒之前進行驗證)，則會要求使用者再次使用該特定層級重新驗證。但是，如果該層級尚未過期，則會自動將使用者視為已使用該層級驗證。

將「最長存留時間」設定為值 0 表示，該特定層級僅對此單次驗證有效。因此，每次重新驗證要求該層級時，都需要再次使用該層級進行驗證。這對於應用程式中需要較高安全性的操作 (例如，發送付款) 非常有用，並且始終需要使用特定層級進行驗證。

如果沒有透過參數明確要求層級，則 Keycloak 將要求使用驗證流程中找到的第一個 LoA 條件進行驗證，例如先前範例中的使用者名稱/密碼。當使用者已經使用該層級進行驗證且該層級已過期時，不會要求使用者重新驗證，但權杖中的 acr 值將為 0。此結果被視為完全基於 OIDC Core 1.0 規格第 2 節中提到的 長期存在的瀏覽器 Cookie 的驗證。

範例情境

權杖中的 ACR 宣告

ACR 宣告會由 acr 用戶端範圍中定義的 acr loa level 通訊協定對應程式新增至權杖。此用戶端範圍是網域預設用戶端範圍，因此將新增至網域中所有新建立的用戶端。

如果您不希望權杖內有 acr 宣告，或您需要新增它的某些自訂邏輯，您可以從用戶端中移除用戶端範圍。

請注意，當登入請求起始帶有 claims 參數的請求，要求 acr 作為 essential 宣告時，Keycloak 始終會傳回指定的層級之一。如果無法傳回指定的層級之一 (例如，如果要求的層級未知，或大於驗證流程中設定的條件)，則 Keycloak 會擲回錯誤。

通常，當使用者從用戶端應用程式重新導向至 Keycloak 時，會觸發 browser 流程。如果啟用網域註冊，且使用者在登入畫面上點擊「註冊」，此流程可能會允許使用者註冊。此外，如果為網域啟用忘記密碼，使用者可以在登入畫面上點擊「忘記密碼」，這會觸發「重設認證」流程，讓使用者在電子郵件地址確認後重設認證。

有時，讓用戶端應用程式將使用者直接重新導向至「註冊」畫面或「重設認證」流程會很有用。產生的動作將與使用者在正常登入畫面上點擊「註冊」或「忘記密碼」時的動作相符。可以透過以下方式執行自動重新導向至註冊或重設認證畫面

設定 Kerberos 伺服器的步驟取決於作業系統 (OS) 和 Kerberos 廠商。請參閱 Windows Active Directory、MIT Kerberos 和您的作業系統文件，以取得有關設定和組態 Kerberos 伺服器的說明。

在設定期間，請執行以下步驟

然後，新增 HTTP 主體並使用以下命令將其金鑰匯出到金鑰表檔案

確保執行 Keycloak 的主機可以存取金鑰表檔案 /tmp/http.keytab。

在您的電腦上安裝 Kerberos 用戶端。

用戶端機器必須安裝 Kerberos 用戶端，並按照上述說明設定 krb5.conf。用戶端機器也必須在其瀏覽器中啟用 SPNEGO 登入支援。如果您使用 Firefox 瀏覽器，請參閱為 Kerberos 設定 Firefox。

.mydomain.org URI 必須在 network.negotiate-auth.trusted-uris 組態選項中。

在 Windows 網域中，用戶端不需要調整其組態。Internet Explorer 和 Edge 已經可以參與 SPNEGO 驗證。

Kerberos 支援憑證委派。應用程式可能需要存取 Kerberos 票證，以便它們可以重複使用該票證與受 Kerberos 保護的其他服務互動。由於 Keycloak 伺服器處理了 SPNEGO 協定，您必須將 GSS 憑證傳播到 OpenID Connect 權杖宣告或 SAML 斷言屬性中的應用程式。Keycloak 從 Keycloak 伺服器將此傳輸到您的應用程式。若要將此宣告插入權杖或斷言中，每個應用程式都必須啟用內建的協定對應器 gss delegation credential。此對應器在應用程式用戶端頁面的對應器索引標籤中提供。如需更多詳細資訊，請參閱協定對應器章節。

應用程式必須在將其用於對其他服務進行 GSS 呼叫之前，反序列化從 Keycloak 收到的宣告。當您從存取權杖將憑證反序列化為 GSSCredential 物件時，請使用傳遞給 GSSManager.createContext 方法的這個憑證建立 GSSContext。例如

在 Kerberos 協定中，realm 是一組 Kerberos 主體。這些主體的定義存在於 Kerberos 資料庫中，該資料庫通常是 LDAP 伺服器。

Kerberos 協定允許跨領域信任。例如，如果存在 2 個 Kerberos 領域 A 和 B，則跨領域信任將允許領域 A 的使用者存取領域 B 的資源。領域 B 信任領域 A。

Keycloak 伺服器支援跨領域信任。若要實作此功能，請執行下列動作

尋找使用者是根據 LDAP 儲存提供者選項 Kerberos 主體屬性。當使用類似 userPrincipalName 的值設定此選項時，則在使用者 john@A 的 SPNEGO 驗證之後，Keycloak 將嘗試尋找屬性 userPrincipalName 等於 john@A 的 LDAP 使用者。如果 Kerberos 主體屬性 為空，則 Keycloak 將根據其 Kerberos 主體的前置詞（省略領域）來尋找 LDAP 使用者。例如，Kerberos 主體使用者 john@A 必須在 LDAP 中以使用者名稱 john 提供，因此通常在 LDAP DN 下，例如 uid=john,ou=People,dc=example,dc=com。如果您希望領域 A 和 B 的使用者進行驗證，請確保 LDAP 可以找到來自領域 A 和 B 的使用者。

允許多個 Kerberos 領域的使用者進行驗證，因為每個使用者都會具有 KERBEROS_PRINCIPAL 屬性，該屬性會參考用於驗證的 Kerberos 主體，並且該屬性會用於進一步尋找此使用者。為了避免當 Kerberos 領域 A 和 B 中都有使用者 john 時發生衝突，Keycloak 使用者的使用者名稱可能包含小寫的 Kerberos 領域。例如，使用者名稱將是 john@a。萬一領域與設定的 Kerberos 領域 匹配時，產生的使用者名稱中可能會省略領域後綴。例如，只要在 Kerberos 提供者上設定的 Kerberos 領域 為 A，則 Kerberos 主體 john@A 的使用者名稱將為 john。

如果您有問題，請啟用其他記錄以偵錯問題

支援的憑證身分來源

WebAuthn 支援 2FA 的設定程序如下