如何在 Keycloak 中設定 MS AD FS 3.0 作為中介身分提供者

2017 年 3 月 23 日，作者：Hynek Mlnařík

這篇文章已超過一年。部落格內容可能已過時。

本文檔將引導您完成 Microsoft Active Directory Federation Services 3.0 作為 Keycloak 中介身分提供者的初始設定。

先決條件

兩台伺服器主機

已安裝 Active Directory Federation Services (AD FS) 的 Microsoft Windows Server 2012。AD 網域名稱在本篇文章中將命名為 DOMAIN.NAME。
Keycloak 伺服器。這通常可以放置在任何地方，但此處預期在單獨的主機上執行。

DNS 設定

Windows 主機名稱在本篇文章中將為 fs.domain.name。
Keycloak 主機名稱在本篇文章中將為 kc.domain.name。

設定 Keycloak 伺服器

Keycloak 伺服器已設定為 SSL/TLS 傳輸 - 這是 AD FS 與之通訊的必要條件。這包含兩個步驟

設定 Keycloak 以接收 HTTPS連線 - 步驟已在伺服器安裝指南中提供。
將 AD FS 憑證匯出到 Java 信任儲存區，以啟用傳出的 HTTPS 連線

在 AD FS 管理主控台中，前往樹狀結構中的服務 → 憑證節點，並匯出服務通訊憑證。
使用 Java keytool 工具將憑證匯入 Java 信任儲存區 (JKS 格式)。
依照伺服器安裝指南中的描述，在 Keycloak 中設定信任儲存區。

在 Keycloak 中設定身分提供者

設定中介身分提供者的基本屬性

在身分提供者中，建立新的 SAML v2.0 身分提供者。在本篇文章中，此身分提供者將以別名 adfs-idp-alias為人所知。

現在捲動到底部，將 AD FS 描述元 URL 輸入到從 URL 匯入欄位中。對於 AD FS 3.0，此 URL 為 https://fs.domain.name/FederationMetadata/2007-06/FederationMetadata.xml。按一下「匯入」後，請檢查設定。通常，您至少會啟用驗證簽章選項。

如果傳送至 AD FS 執行個體的驗證請求預期會被簽署 (通常也是這種情況)，您必須啟用想要簽署 AuthnRequests選項。重要的是，在啟用想要簽署 AuthnRequests選項後顯示的 SAML 簽章金鑰名稱欄位必須設定為 CERT_SUBJECT，因為 AD FS 預期簽署金鑰名稱提示是簽署憑證的主體。

AD FS 將在下一步設定為以 Windows 網域完整名稱格式回應名稱 ID，因此請相應地設定 NameID 原則格式欄位。

設定對應器

在以下設定 AD FS 的步驟中，AD FS 將設定為在 SAML 判斷提示中傳送電子郵件和群組資訊。為了將這些詳細資料從 AD FS 發出的 SAML 文件轉換到 Keycloak 使用者存放區，我們需要在身分提供者的「對應器」索引標籤中設定兩個對應的對應器。

名為群組：管理員的對應器類型將為 SAML 屬性到角色，並且如果屬性值為 managers，則會將名為 http://schemas.xmlsoap.org/claims/Group的屬性對應到角色 manager。

名為屬性：電子郵件的對應器類型將為屬性匯入器，並且會將名為 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress的屬性對應到名為 email的使用者屬性。

取得 AD FS 設定的資訊

現在，我們從身分提供者詳細資料中的重新導向 URI欄位中，透過將「/descriptor」新增至此欄位的 URI，判斷 AD FS 設定中將使用的 SAML 服務提供者描述元 URI。此 URI 將類似於 https://kc.domain.name:8443/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor。您可以將 URI 輸入到瀏覽器中，檢查您是否取得正確的 URI - 您應該會收到 SAML 服務提供者 XML 描述元。

在 AD FS 中設定信賴方信任

設定信賴方

在 AD FS 管理主控台中，以滑鼠右鍵按一下信任關係 → 信賴方信任，然後從選單中選取新增信賴方信任：

在精靈的開始，將上一個步驟中取得的 SAML 描述元 URL 輸入到同盟中繼資料位址欄位中，並讓 AD FS 匯入設定。繼續執行精靈，並在適當的地方調整設定。在這裡，我們僅使用預設設定。請注意，您將需要編輯宣告規則，因此在精靈最後一頁要求您執行此操作時，您可以將核取方塊保持選取狀態。

設定宣告對應

現在 SAML 通訊協定將會正確進行，AD FS 將能夠根據 Keycloak 的請求正確驗證使用者，但是要求的名稱 ID 格式尚未被識別，且 SAML 回應將不包含任何額外資訊 (如電子郵件)。因此，有必要將宣告從 AD 使用者詳細資料對應到 SAML 文件中。

我們將設定三個規則：一個用於對應使用者 ID，第二個用於對應標準使用者屬性，第三個用於使用者群組。所有規則的開始都是按一下 kc.domain.name 的編輯宣告規則視窗中的新增規則按鈕：

第一個規則會將 Windows 完整網域名稱中的使用者 ID 對應到 SAML 回應。在新增轉換宣告規則視窗中，選取轉換傳入宣告規則類型：

上述範例的目標是 Windows 帳戶名稱 ID 格式。其他名稱 ID 格式也受支援，但超出本文的範圍。請參閱例如此部落格，瞭解如何設定持續性和暫時性格式的名稱 ID。

第二個規則會將使用者電子郵件對應到 SAML 回應。在新增轉換宣告規則視窗中，選取將 LDAP 屬性以宣告傳送規則類型。您可以根據需要新增其他屬性：

如果使用者是具名群組的成員，則第三個規則會傳送群組名稱。再次從新增轉換宣告規則視窗開始，然後選取將群組成員資格以宣告傳送規則類型。然後在欄位中輸入要求的值：

如果通過驗證的使用者是 DOMAIN\Managers群組的成員，則此設定會在 SAML 判斷提示中傳送一個名為 Group、值為 managers的屬性。

疑難排解

作為第一手的工具，您應該在瀏覽器中檢查 Keycloak 和 AD FS 之間來回傳送的 SAML 訊息。SAML 解碼器可作為瀏覽器擴充功能使用 (例如，Firefox 的 SAML Tracer、Chrome 的 SAML Chrome Panel)。從擷取的通訊中，您可能會看到錯誤狀態碼，以及 SAML 判斷提示中設定對應器所需的實際屬性名稱和值。例如，如果無法辨識名稱 ID 格式，AD FS 會傳回一個包含 urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy 狀態碼的 SAML 回應。

作為第二種方法，請檢查記錄。對於 AD FS，記錄可在 事件檢視器中的應用程式及服務記錄 → AD FS → 管理員下找到。在 Keycloak 中，您可以透過 jboss-cli.sh 連線到正在執行的 Keycloak 執行個體，並輸入以下命令來啟用 SAML 處理追蹤：

/subsystem=logging/logger=org.keycloak.saml:add(level=DEBUG)

/subsystem=logging/logger=org.keycloak.broker.saml:add(level=DEBUG)

然後，您將能夠在 Keycloak 伺服器記錄中找到 SAML 訊息和與中介相關的 SAML 處理訊息。

常見問題

問：我無法登出！當我在應用程式中按一下登出時，我似乎已從 Keycloak 登出，但是當我返回應用程式時，AD FS 登入表單永遠不會顯示，而且我會以與之前相同的使用者身分重新導向驗證！

答：不要驚慌。這不是 Keycloak 的問題，而是 AD FS 驗證原則的設定。在回報問題之前，請嘗試停用 Windows 驗證。

問：在使用 Windows 2016 中的 AD FS 時，從 URL 匯入描述元後，Keycloak 記錄中出現以下錯誤：RESTEASY002010：執行失敗：javax.ws.rs.NotFoundException：RESTEASY003210：找不到完整路徑的資源：https://kc.domain.name/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor/FederationMetadata/2007-06/FederationMetadata.xml。這會造成任何損害嗎？
答：這無害。Windows 2016 版本似乎會先檢查 AD FS 類似的描述元 URL，方法是將 FederationMetadata/2007-06/FederationMetadata.xml 新增至輸入的 URL。Keycloak 中不存在此類資源，因此它會回報錯誤。不過，AD FS 在發生這種情況時似乎會使用輸入的 URL 進行匯入。另請參閱關於此問題的原始電子郵件討論。

結論

如果您遇到困難，請隨時在 Keycloak 使用者論壇郵寄清單中提出問題。

由於總有進步的空間，如果您發現任何問題或對本文有任何建議，請隨時留下評論！