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 登录页面，但向未经身份验证的 SOAP 或 REST 客户端发送 HTTP 401 状态代码，因为它们不理解重定向到登录页面。Keycloak 基于典型的标头（如 X-Requested-With、SOAPAction 或 Accept）自动检测 SOAP 或 REST 客户端。默认值为 false。

logoutPage

这将设置注销后显示的页面。如果页面是完整的 URL，例如 http://web.example.com/logout.html，则用户将在注销后使用 HTTP 302 状态代码重定向到该页面。如果指定了没有方案部分的链接，例如 /logout.jsp，则该页面将在注销后显示，无论它是否位于 security-constraint 声明（在 web.xml 中）所定义的保护区域内，并且该页面将相对于部署上下文根解析。

keepDOMAssertion

应将此属性设置为 true，以使适配器在与请求关联的 SamlPrincipal 中以原始形式存储断言的 DOM 表示。可以使用 getAssertionDocument 方法在 principal 中检索断言文档。当重播已签署的断言时，这特别有用。返回的文档是在解析 Keycloak 服务器收到的 SAML 响应时生成的文档。此设置是 可选的，其默认值为 false（该文档不会保存在 principal 中）。

服务提供商密钥和密钥元素

如果 IdP 要求客户端应用程序（或 SP）对其所有请求进行签名，或者如果 IdP 将对断言进行加密，则您必须定义用于执行此操作的密钥。对于客户端签名的文档，您必须定义用于签署文档的私钥和公钥或证书。对于加密，您只需要定义用于解密它的私钥。

有两种方法可以描述您的密钥。它们可以存储在 Java KeyStore 中，或者您可以直接将密钥粘贴到 keycloak-saml.xml 中的 PEM 格式中。

        <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

WAR 资源路径到 KeyStore。这是在方法调用中用于 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 是一个可选元素，它允许指定 org.keycloak.adapters.saml.RoleMappingsProvider SPI 实现的 ID 和配置，该实现将由 SAML 适配器使用。

当 Keycloak 用作 IDP 时，可以使用内置角色映射器在将角色添加到 SAML 断言之前映射任何角色。但是，SAML 适配器可以用于向第三方 IDP 发送 SAML 请求，在这种情况下，可能需要将从断言中提取的角色映射到 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 文件可以包含角色和主体作为键，以及以逗号分隔的零个或多个角色列表作为值。当调用时，实现将遍历从断言中提取的角色集，并检查每个角色是否存在映射。如果角色映射到空角色，则将其丢弃。如果它映射到一组一个或多个不同的角色，则将这些角色设置在结果集中。如果未找到角色的映射，则将其按原样包含在结果集中。

处理完角色后，实现将检查从断言中提取的主体是否包含条目 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

客户端是否应该签署身份验证请求？此设置是可选的。默认值为 IDP signaturesRequired 元素值。

validateResponseSignature

客户端是否应该期望 IDP 对从身份验证请求发回的断言响应文档进行签名？此设置是可选的。默认值为 IDP signaturesRequired 元素值。

requestBinding

这是用于与 IDP 通信的 SAML 绑定类型。此设置是可选的。默认值为POST，但您也可以将其设置为REDIRECT。

responseBinding

SAML 允许客户端请求它希望身份验证响应使用的绑定类型。此值可以是POST 或REDIRECT。此设置是可选的。默认情况下，客户端不会为响应请求特定绑定类型。

assertionConsumerServiceUrl

断言消费者服务 (ACS) 的 URL，IDP 登录服务应将响应发送到该 URL。此设置是可选的。默认情况下它未设置，依赖于 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

这是 IDP 注销服务在使用 POST 绑定时的 URL。如果使用POST 绑定，此设置是必需的。

redirectBindingUrl

这是 IDP 注销服务在使用 REDIRECT 绑定时的 URL。如果使用 REDIRECT 绑定，此设置是必需的。

IDP Keys 子元素

IDP 的 Keys 子元素仅用于定义用于验证 IDP 签名的文档的证书或公钥。它的定义方式与SP 的 Keys 元素相同。但同样，您只需要定义一个证书或公钥引用。请注意，如果 IDP 和 SP 分别由 Keycloak 服务器和适配器实现，则无需指定用于签名验证的密钥，请参见下文。

可以配置 SP 从发布的证书中自动获取用于 IDP 签名验证的公钥，前提是 SP 和 IDP 均由 Keycloak 实现。这是通过删除 Keys 子元素中所有签名验证密钥的声明来实现的。如果 Keys 子元素随后保持为空，则可以完全省略它。然后，SP 会从 SAML 描述符中自动获取密钥，SAML 描述符的位置是从IDP SingleSignOnService 子元素中指定的 SAML 端点 URL 推断出来的。用于 SAML 描述符检索的 HTTP 客户端设置通常不需要额外的配置，但可以在IDP HttpClient 子元素中配置。

也可以指定多个用于签名验证的密钥。这是通过在 Keys 子元素中声明多个 Key 元素来实现的，这些元素具有设置为true 的signing 属性。这在 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

建立连接后套接字等待数据的超时时间（以毫秒为单位）。两个数据包之间空闲的最大时间。超时值为零被解释为无限超时。负值被解释为未定义（如果适用，则为系统默认值）。默认值为-1。此设置是可选的。

connectionTimeout

与远程主机建立连接的超时时间（以毫秒为单位）。超时值为零被解释为无限超时。负值被解释为未定义（如果适用，则为系统默认值）。默认值为-1。此设置是可选的。

connectionTtl

客户端的连接生存时间（以毫秒为单位）。小于或等于零的值被解释为无限值。默认值为-1。此设置是可选的。

在此页面上
编辑本指南