Keycloak SAML Galleon 功能套件詳細配置

用於 `keycloak-saml.xml` 配置檔的元素詳細列表

本指南包含 Keycloak SAML Galleon 功能套件使用的 `keycloak-saml.xml` 配置檔的元素詳細列表。

SP 元素

以下是 SP 元素屬性的說明

<SP entityID="sp"
    sslPolicy="ssl"
    nameIDPolicyFormat="format"
    forceAuthentication="true"
    isPassive="false"
    keepDOMAssertion="true"
    autodetectBearerOnly="false">
...
</SP>
entityID

這是此客戶端的識別碼。IdP 需要此值來判斷與其通訊的客戶端是誰。此設定為必要。

sslPolicy

這是介面卡將強制執行的 SSL 政策。有效值為：ALL、EXTERNAL 和 NONE。對於 ALL，所有請求都必須透過 HTTPS 傳入。對於 EXTERNAL，只有非私有 IP 位址必須透過 HTTPS 傳輸。對於 NONE，不需要任何請求透過 HTTPS 傳輸。此設定為選用。預設值為 EXTERNAL。

nameIDPolicyFormat

SAML 客戶端可以請求特定的 NameID 主體格式。如果您想要特定格式，請填入此值。它必須是標準 SAML 格式識別碼：urn:oasis:names:tc:SAML:2.0:nameid-format:transient。此設定為選用。預設情況下，不會請求任何特殊格式。

forceAuthentication

SAML 客戶端可以要求使用者重新驗證，即使他們已經在 IdP 登入。將此設定為 true 以啟用。此設定為選用。預設值為 false。

isPassive

SAML 客戶端可以要求永遠不要要求使用者驗證，即使他們沒有在 IdP 登入。如果您想要這樣，請將此設定為 true。請勿與 forceAuthentication 一起使用，因為它們是相反的。此設定為選用。預設值為 false。

turnOffChangeSessionIdOnLogin

在某些平台上，預設會在成功登入時變更工作階段 ID，以防止安全攻擊。將此變更為 true 以停用此功能。建議您不要關閉它。預設值為 false。

autodetectBearerOnly

如果您的應用程式同時提供 Web 應用程式和 Web 服務（例如 SOAP 或 REST），則應將此設定為 *true*。它可讓您將未驗證的 Web 應用程式使用者重新導向至 Keycloak 登入頁面，但將 HTTP 401 狀態碼傳送給未驗證的 SOAP 或 REST 客戶端，因為他們不會理解重新導向至登入頁面。Keycloak 會根據典型的標頭（例如 X-Requested-With、SOAPAction 或 Accept）自動偵測 SOAP 或 REST 客戶端。預設值為 *false*。

logoutPage

這會設定登出後要顯示的頁面。如果該頁面是完整的 URL，例如 http://web.example.com/logout.html，則使用者會在登出後使用 HTTP 302 狀態碼重新導向至該頁面。如果指定沒有架構部分的連結，例如 /logout.jsp，則會在登出後顯示該頁面，無論它是否根據 web.xml 中的 security-constraint 宣告位於受保護的區域，且該頁面會相對於部署內容根目錄進行解析。

keepDOMAssertion

應將此屬性設定為 *true*，以使介面卡將斷言的 DOM 表示形式以原始形式儲存在與請求相關聯的 SamlPrincipal 中。可以使用主體中的 getAssertionDocument 方法擷取斷言文件。當重新播放簽署的斷言時，這特別有用。傳回的文件是解析 Keycloak 伺服器接收到的 SAML 回應所產生的文件。此設定為選用，其預設值為 *false* (文件不會儲存在主體內)。

服務提供者金鑰和金鑰元素

如果 IdP 要求客戶端應用程式 (或 SP) 簽署其所有請求，和/或如果 IdP 將加密斷言，則您必須定義用於執行此操作的金鑰。對於客戶端簽署的文件，您必須定義用於簽署文件的私鑰和公鑰或憑證。對於加密，您只需要定義用於解密的私鑰即可。

有兩種方式描述您的金鑰。它們可以儲存在 Java KeyStore 中，或者您可以直接以 PEM 格式將金鑰複製/貼到 keycloak-saml.xml 中。

        <Keys>
            <Key signing="true" >
               ...
            </Key>
        </Keys>

Key 元素有兩個選用屬性 signing 和 encryption。當設定為 true 時，這些屬性會告訴介面卡金鑰的用途。如果兩個屬性都設定為 true，則金鑰將用於簽署文件和解密加密的斷言。您必須至少將其中一個屬性設定為 true。

KeyStore 元素

在 Key 元素中，您可以從 Java Keystore 載入金鑰和憑證。這在 KeyStore 元素中宣告。

        <Keys>
            <Key signing="true" >
                <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                    <PrivateKey alias="myPrivate" password="test123"/>
                    <Certificate alias="myCertAlias"/>
                </KeyStore>
            </Key>
        </Keys>

以下是使用 KeyStore 元素定義的 XML 配置屬性。

file

金鑰儲存的檔案路徑。此選項為選用。必須設定檔案或資源屬性。

resource

KeyStore 的 WAR 資源路徑。這是 ServletContext.getResourceAsStream() 方法呼叫中使用的路徑。此選項為選用。必須設定檔案或資源屬性。

password

KeyStore 的密碼。此選項為必要。

如果您定義 SP 將用於簽署文件的金鑰，您也必須在 Java KeyStore 中指定對私鑰和憑證的參考。上述範例中的 PrivateKey 和 Certificate 元素定義了一個指向金鑰儲存中金鑰或憑證的 alias。金鑰儲存需要額外的密碼才能存取私鑰。在 PrivateKey 元素中，您必須在 password 屬性中定義此密碼。

金鑰 PEMS

在 Key 元素中，您可以使用子元素 PrivateKeyPem、PublicKeyPem 和 CertificatePem 直接宣告金鑰和憑證。這些元素中包含的值必須符合 PEM 金鑰格式。如果您使用 openssl 或類似的命令列工具產生金鑰，您通常會使用此選項。

<Keys>
   <Key signing="true">
      <PrivateKeyPem>
         2341251234AB31234==231BB998311222423522334
      </PrivateKeyPem>
      <CertificatePem>
         211111341251234AB31234==231BB998311222423522334
      </CertificatePem>
   </Key>
</Keys>

SP PrincipalNameMapping 元素

此元素是選用的。當您建立從 HttpServletRequest.getUserPrincipal() 等方法取得的 Java Principal 物件時，您可以定義 Principal.getName() 方法傳回的名稱。

<SP ...>
  <PrincipalNameMapping policy="FROM_NAME_ID"/>
</SP>

<SP ...>
  <PrincipalNameMapping policy="FROM_ATTRIBUTE" attribute="email" />
</SP>

policy 屬性定義用於填入此值的政策。此屬性的可能值為

FROM_NAME_ID

此政策只會使用 SAML 主體值。這是預設設定

FROM_ATTRIBUTE

這會從伺服器收到的 SAML 斷言中宣告的其中一個屬性中提取值。您需要在 attribute XML 屬性中指定要使用的 SAML 斷言屬性的名稱。

RoleIdentifiers 元素

RoleIdentifiers 元素定義從使用者收到的斷言中，應將哪些 SAML 屬性用作使用者 Jakarta EE 安全內容中的角色識別碼。

<RoleIdentifiers>
     <Attribute name="Role"/>
     <Attribute name="member"/>
     <Attribute name="memberOf"/>
</RoleIdentifiers>

預設情況下，Role 屬性值會轉換為 Jakarta EE 角色。某些 IdP 會使用 member 或 memberOf 屬性斷言傳送角色。您可以定義一個或多個 Attribute 元素，以指定必須轉換為角色的 SAML 屬性。

RoleMappingsProvider 元素

RoleMappingsProvider 是一個選用元素，可讓您指定要由 SAML 介面卡使用的 org.keycloak.adapters.saml.RoleMappingsProvider SPI 實作的 ID 和配置。

當 Keycloak 用作 IDP 時，可以使用內建的角色對應器在將任何角色新增至 SAML 斷言之前對其進行對應。但是，SAML 介面卡可用於將 SAML 請求傳送至第三方 IDP，在這種情況下，可能需要將從斷言中擷取的角色對應到 SP 所需的不同角色集。RoleMappingsProvider SPI 可讓您配置可插入的角色對應器，這些對應器可用於執行必要的對應。

提供者的配置如下所示

...
<RoleIdentifiers>
    ...
</RoleIdentifiers>
<RoleMappingsProvider id="properties-based-role-mapper">
    <Property name="properties.resource.location" value="/WEB-INF/role-mappings.properties"/>
</RoleMappingsProvider>
<IDP>
    ...
</IDP>

id 屬性會識別要使用的已安裝提供者中的哪一個。Property 子元素可以多次使用，以指定提供者的配置屬性。

基於屬性的角色對應提供者

Keycloak 包含一個 RoleMappingsProvider 實作，該實作使用 properties 檔案執行角色對應。此提供者的 ID 為 properties-based-role-mapper，並由 org.keycloak.adapters.saml.PropertiesBasedRoleMapper 類別實作。

此提供者依賴兩個配置屬性，可用於指定要使用的 properties 檔案的位置。首先，它會檢查是否已指定 properties.file.location 屬性，並使用已配置的值來尋找檔案系統中的 properties 檔案。如果找不到已配置的檔案，提供者會擲回 RuntimeException。以下程式碼片段顯示使用 properties.file.configuration 選項從檔案系統中的 /opt/mappers/ 目錄載入 roles.properties 檔案的提供者範例

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.file.location" value="/opt/mappers/roles.properties"/>
    </RoleMappingsProvider>

如果未設定 properties.file.location 配置，提供者會檢查 properties.resource.location 屬性，並使用已配置的值從 WAR 資源載入 properties 檔案。如果此配置屬性也不存在，提供者會嘗試從 /WEB-INF/role-mappings.properties 預設載入檔案。如果無法從資源載入檔案，則提供者會擲回 RuntimeException。以下程式碼片段顯示使用 properties.resource.location 從應用程式的 /WEB-INF/conf/ 目錄載入 roles.properties 檔案的提供者範例

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.resource.location" value="/WEB-INF/conf/roles.properties"/>
    </RoleMappingsProvider>

properties 檔案可以將角色 (roles) 和主體 (principals) 作為鍵 (keys)，並以逗號分隔的角色清單（零個或多個）作為值 (values)。當被調用時，實作會迭代從斷言中提取的角色集合，並針對每個角色檢查是否存在映射。如果角色映射到空角色，則會被捨棄。如果它映射到一組一個或多個不同的角色，則這些角色會被設定在結果集中。如果找不到角色的映射，則會將該角色原樣包含在結果集中。

一旦角色被處理完畢，實作會檢查從斷言中提取的主體是否在 properties 檔案中包含條目。如果存在主體的映射，則任何列為值的角色都會被新增到結果集中。這允許將額外的角色分配給主體。

舉例來說，假設提供者已配置了以下 properties 檔案：

roleA=roleX,roleY
roleB=

kc_user=roleZ

如果從斷言中提取的主體是 kc_user，且具有角色 roleA、roleB 和 roleC，則分配給主體的最終角色集合將會是 roleC、roleX、roleY 和 roleZ，因為 roleA 被映射到 roleX 和 roleY，roleB 被映射到空角色 - 因此被捨棄，roleC 原樣使用，最後，額外的角色被新增到 kc_user 主體 (roleZ)。

注意：若要在角色名稱中使用空格進行映射，請使用空格的 Unicode 替代符。例如，傳入的 'role A' 會顯示為：

role\u0020A=roleX,roleY

新增您自己的角色映射提供者

若要新增自訂角色映射提供者，只需實作 org.keycloak.adapters.saml.RoleMappingsProvider SPI。如需更多詳細資訊，請參閱伺服器開發人員指南中的「SAML 角色映射 SPI」章節。

IDP 元素

IDP 元素中的所有內容都描述了 SP (服務供應商) 與之通訊的身份提供者 (身份驗證伺服器) 的設定。

<IDP entityID="idp"
     signaturesRequired="true"
     signatureAlgorithm="RSA_SHA1"
     signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
...
</IDP>

以下是您可以在 IDP 元素宣告中指定的屬性配置選項。

entityID

這是 IDP 的發行者 ID。此設定為必要。

signaturesRequired

如果設定為 true，客戶端介面卡會簽署它傳送給 IDP 的每個文件。此外，客戶端會期望 IDP 會簽署任何傳送給它的文件。此開關會設定所有請求和回應類型的預設值，但您稍後會看到您對此有一些細微的控制。此設定是可選，預設值為 false。

signatureAlgorithm

這是 IDP 期望簽署的文件使用的簽章演算法。允許的值為：RSA_SHA1、RSA_SHA256、RSA_SHA512 和 DSA_SHA1。此設定是可選，預設值為 RSA_SHA256。請注意，基於 SHA1 的演算法已被棄用，將來可能會被移除。我們建議使用比 *_SHA1 更安全的演算法。此外，使用 *_SHA1 演算法時，如果 SAML 伺服器 (通常是 Keycloak) 在 Java 17 或更高版本上執行，則驗證簽章將無法運作。

signatureCanonicalizationMethod

這是 IDP 期望簽署的文件使用的簽章正規化方法。此設定是可選。預設值為 http://www.w3.org/2001/10/xml-exc-c14n#，適用於大多數 IDP。

metadataUrl

用於檢索 IDP 元資料的 URL，目前僅用於定期擷取簽署和加密金鑰，這允許在 IDP 上循環使用這些金鑰，而無需在 SP 端進行手動變更。

IDP AllowedClockSkew 子元素

AllowedClockSkew 可選子元素定義了 IDP 和 SP 之間允許的時鐘偏差。預設值為 0。

<AllowedClockSkew unit="MILLISECONDS">3500</AllowedClockSkew>
unit

可以定義附加到此元素值的時間單位。允許的值為 MICROSECONDS、MILLISECONDS、MINUTES、NANOSECONDS 和 SECONDS。這是可選。預設值為 SECONDS。

IDP SingleSignOnService 子元素

SingleSignOnService 子元素定義了 IDP 的登入 SAML 端點。當客戶端介面卡想要登入時，它會根據此元素中的設定，將請求傳送至 IDP。

<SingleSignOnService signRequest="true"
                     validateResponseSignature="true"
                     requestBinding="post"
                     bindingUrl="url"/>

以下是您可以在此元素上定義的配置屬性：

signRequest

客戶端是否應該簽署 authn 請求？此設定是可選。預設值為 IDP signaturesRequired 元素的值。

validateResponseSignature

客戶端是否應該期望 IDP 簽署從 authn 請求傳回的斷言回應文件？此設定是可選。預設值為 IDP signaturesRequired 元素的值。

requestBinding

這是用於與 IDP 通訊的 SAML 綁定類型。此設定是可選。預設值為 POST，但您也可以將其設定為 REDIRECT。

responseBinding

SAML 允許客戶端請求它希望 authn 回應使用的綁定類型。此值可以是 POST 或 REDIRECT。此設定是可選。預設情況下，客戶端不會請求特定的回應綁定類型。

assertionConsumerServiceUrl

斷言消費者服務 (ACS) 的 URL，IDP 登入服務應將回應傳送至此處。此設定是可選。預設情況下為未設定，依賴 IDP 中的配置。設定時，必須以 /saml 結尾，例如 http://sp.domain.com/my/endpoint/for/saml。此屬性的值會傳送在 SAML AuthnRequest 訊息的 AssertionConsumerServiceURL 屬性中。此屬性通常會與 responseBinding 屬性一起使用。

bindingUrl

這是客戶端將請求傳送至 IDP 登入服務的 URL。此設定為必要。

IDP SingleLogoutService 子元素

SingleLogoutService 子元素定義了 IDP 的登出 SAML 端點。當客戶端介面卡想要登出時，它會根據此元素中的設定，將請求傳送至 IDP。

<SingleLogoutService validateRequestSignature="true"
                     validateResponseSignature="true"
                     signRequest="true"
                     signResponse="true"
                     requestBinding="redirect"
                     responseBinding="post"
                     postBindingUrl="posturl"
                     redirectBindingUrl="redirecturl">
signRequest

客戶端是否應該簽署它傳送至 IDP 的登出請求？此設定是可選。預設值為 IDP signaturesRequired 元素的值。

signResponse

客戶端是否應該簽署它傳送至 IDP 請求的登出回應？此設定是可選。預設值為 IDP signaturesRequired 元素的值。

validateRequestSignature

客戶端是否應該期望 IDP 傳送簽署的登出請求文件？此設定是可選。預設值為 IDP signaturesRequired 元素的值。

validateResponseSignature

客戶端是否應該期望 IDP 傳送簽署的登出回應文件？此設定是可選。預設值為 IDP signaturesRequired 元素的值。

requestBinding

這是用於將 SAML 請求傳送至 IDP 的 SAML 綁定類型。此設定是可選。預設值為 POST，但您也可以將其設定為 REDIRECT。

responseBinding

這是用於將 SAML 回應傳送至 IDP 的 SAML 綁定類型。此值可以是 POST 或 REDIRECT。此設定是可選。預設值為 POST，但您也可以將其設定為 REDIRECT。

postBindingUrl

這是使用 POST 綁定時 IDP 登出服務的 URL。如果使用 POST 綁定，則此設定為必要。

redirectBindingUrl

這是使用 REDIRECT 綁定時 IDP 登出服務的 URL。如果使用 REDIRECT 綁定，則此設定為必要。

IDP Keys 子元素

IDP 的 Keys 子元素僅用於定義用來驗證 IDP 簽署的文件的憑證或公鑰。其定義方式與SP 的 Keys 元素相同。但是，您只需要定義一個憑證或公鑰參考。請注意，如果 IDP 和 SP 分別由 Keycloak 伺服器和介面卡實現，則無需指定金鑰進行簽章驗證，請參閱下文。

如果 SP 和 IDP 都由 Keycloak 實現，則可以將 SP 配置為自動從發佈的憑證中取得用於 IDP 簽章驗證的公鑰。這可以透過移除 Keys 子元素中所有簽章驗證金鑰的宣告來完成。如果 Keys 子元素仍然為空，則可以完全省略它。金鑰隨後會由 SP 自動從 SAML 描述符中取得，其位置來自IDP SingleSignOnService 子元素中指定的 SAML 端點 URL。用於 SAML 描述符檢索的 HTTP 客戶端的設定通常不需要額外的配置，但可以在IDP HttpClient 子元素中進行配置。

也可以指定多個金鑰進行簽章驗證。這可以透過在 Keys 子元素中宣告多個 signing 屬性設定為 true 的 Key 元素來完成。例如，在 IDP 簽章金鑰輪換的情況下，這很有用：通常會有一個過渡期，在此期間，新的 SAML 協定訊息和斷言會使用新的金鑰簽署，但仍應接受之前金鑰簽署的訊息和斷言。

無法將 Keycloak 配置為自動取得用於簽章驗證的金鑰，並定義其他靜態簽章驗證金鑰。

       <IDP entityID="idp">
            ...
            <Keys>
                <Key signing="true">
                    <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                        <Certificate alias="demo"/>
                    </KeyStore>
                </Key>
            </Keys>
        </IDP>

IDP HttpClient 子元素

HttpClient 可選子元素定義了 HTTP 客戶端的屬性，該客戶端用於在啟用時，透過 IDP 的 SAML 描述符自動取得包含用於 IDP 簽章驗證的公鑰的憑證。

<HttpClient connectionPoolSize="10"
            disableTrustManager="false"
            allowAnyHostname="false"
            clientKeystore="classpath:keystore.jks"
            clientKeystorePassword="pwd"
            truststore="classpath:truststore.jks"
            truststorePassword="pwd"
            proxyUrl="http://proxy/"
            socketTimeout="5000"
            connectionTimeout="6000"
            connectionTtl="500" />
connectionPoolSize

此配置選項定義了應該池化到 Keycloak 伺服器的連線數量。這是可選。預設值為 10。

disableTrustManager

如果 Keycloak 伺服器需要 HTTPS，並且此配置選項設定為 true，則您不必指定信任儲存區。此設定僅應在開發期間使用，並且絕不應在生產環境中使用，因為它會停用 SSL 憑證的驗證。這是可選。預設值為 false。

allowAnyHostname

如果 Keycloak 伺服器需要 HTTPS，並且此配置選項設定為 true，則會透過信任儲存區驗證 Keycloak 伺服器的憑證，但不會執行主機名稱驗證。此設定僅應在開發期間使用，並且絕不應在生產環境中使用，因為它會部分停用 SSL 憑證的驗證。此設定在測試環境中可能很有用。這是可選。預設值為 false。

truststore

此值是信任儲存區檔案的檔案路徑。如果您在路徑前加上 classpath:，則會改為從部署的類別路徑取得信任儲存區。用於發送到 Keycloak 伺服器的 HTTPS 通訊。發出 HTTPS 請求的客戶端需要一種方法來驗證與之通訊的伺服器主機。這就是信任儲存區的作用。金鑰儲存區包含一個或多個受信任的主機憑證或憑證授權單位。您可以透過提取 Keycloak 伺服器 SSL 金鑰儲存區的公用憑證來建立此信任儲存區。這是必要的，除非 disableTrustManager 為 true。

truststorePassword

信任儲存區的密碼。如果設定了 truststore 並且信任儲存區需要密碼，則此為必要。

clientKeystore

這是金鑰儲存檔案的路徑。這個金鑰儲存包含當介面卡對 Keycloak 伺服器發出 HTTPS 請求時，用於雙向 SSL 的客戶端憑證。這是選用的。

clientKeystorePassword

客戶端金鑰儲存以及客戶端金鑰的密碼。如果設定了 clientKeystore，則此為必要的。

proxyUrl

用於 HTTP 連線的 HTTP 代理伺服器 URL。這是選用的。

socketTimeout

在建立連線後，等待 socket 資料的逾時時間（以毫秒為單位）。兩個資料封包之間的最大非活動時間。逾時值為零表示無限逾時。負值表示未定義（如果適用，則為系統預設值）。預設值為 -1。這是選用的。

connectionTimeout

與遠端主機建立連線的逾時時間（以毫秒為單位）。逾時值為零表示無限逾時。負值表示未定義（如果適用，則為系統預設值）。預設值為 -1。這是選用的。

connectionTtl

客戶端的連線存活時間（以毫秒為單位）。小於或等於零的值表示無限值。預設值為 -1。這是選用的。

在此頁面上
編輯本指南