2.4. 迁移配置

配置红帽构建的 Keycloak 服务器的新统一方法是通过配置选项。Red Hat Single Sign-On 7.6 配置机制（如 standalone.xml、jboss-cli 等）不再适用。

每个选项可以通过以下配置源定义：

CLI 参数
环境变量
配置文件
Java KeyStore file

如果通过不同的配置源指定相同的配置选项，则使用上述列表中的第一个源。

所有配置选项都位于所有不同的配置源中，其主要区别是密钥的格式。例如，以下有四个配置数据库主机名的方法：

Expand

Source	格式
CLI 参数	--db-url-host cliValue
环境变量	KC_DB_URL_HOST=envVarValue
配置文件	db-url-host=confFileValue
Java KeyStore file	kc.db-url-host=keystoreValue

kc.sh --help 命令以及红帽构建的 Keycloak 文档提供了所有可用配置选项的完整列表，其中选项按缓存、数据库等类别分组。另外，每个区域都存在单独的章节，如配置 Keycloak 的章节。

2.4.1. 迁移数据库配置
复制链接

与 Red Hat Single Sign-On 7.6 不同，红帽构建的 Keycloak 内置支持支持的数据库，不再需要手动安装和配置数据库驱动程序。例外是 Oracle 和 Microsoft SQL Server，它仍需要手动安装驱动程序。

在配置中，请考虑现有 Red Hat Single Sign-On 7.6 安装中的 datasource 子系统，并将这些配置映射到红帽构建的 Keycloak 中数据库配置类别中提供的选项。例如，以前的配置如下所示：

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="true">
    <connection-url>jdbc:postgresql://mypostgres:5432/mydb?currentSchema=myschema</connection-url>
    <driver>postgresql</driver>
    <pool>
        <min-pool-size>5</min-pool-size>
        <max-pool-size>50</max-pool-size>
    </pool>
    <security>
        <user-name>myuser</user-name>
        <password>myuser</password>
    </security>
</datasource>

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="true">
    <connection-url>jdbc:postgresql://mypostgres:5432/mydb?currentSchema=myschema</connection-url>
    <driver>postgresql</driver>
    <pool>
        <min-pool-size>5</min-pool-size>
        <max-pool-size>50</max-pool-size>
    </pool>
    <security>
        <user-name>myuser</user-name>
        <password>myuser</password>
    </security>
</datasource>

Copy to Clipboard

Toggle word wrap

在 Red Hat build of Keycloak 中，使用 CLI 参数的等效配置将是：

kc.sh start
   --db postgres
   --db-url-host mypostgres
   --db-url-port 5432
   --db-url-database mydb
   --db-schema myschema
   --db-pool-min-size 5 --db-pool-max-size 50
   --db-username myser --db-password myuser

kc.sh start
   --db postgres
   --db-url-host mypostgres
   --db-url-port 5432
   --db-url-database mydb
   --db-schema myschema
   --db-pool-min-size 5 --db-pool-max-size 50
   --db-username myser --db-password myuser

Copy to Clipboard

Toggle word wrap

注意

考虑将数据库凭据存储在安全 KeyStore 配置源中。

2.4.3. 迁移 HTTP 和 TLS 配置
复制链接

默认情况下，HTTP 被禁用，每当使用生产模式（由 start 选项代表）时，都需要 TLS 配置。

您可以使用 --http-enabled=true 配置选项启用 HTTP，但不建议使用它，除非红帽构建的 Keycloak 服务器位于完全隔离的网络中，且没有内部或外部攻击者能够观察网络流量的风险。

Red Hat build of Keycloak 实例具有不同的上下文根(URL 路径)，因为它在 Red Hat Single Sign-On 7.6 默认附加 /auth 时使用服务器的根目录。要模拟旧行为，可以使用 --http-relative-path=/auth 配置选项。默认端口保持不变，但也可以通过 --http-port 和-- https-port 选项更改。

有两种方法可用于配置 TLS，可以通过 PEM 格式的文件或 Java 密钥存储来配置。例如，Java Keystore 的以前的配置如下所示：

<tls>
	<key-stores>
            <key-store name="applicationKS">
                 <credential-reference
		 clear-text="password"/>
		 <implementation type="JKS"/>
                 <file
   path="/path/to/application.keystore”/>
            </key-store>
     </key-stores>
     <key-managers>
        <key-manager name="applicationKM"
         key-store="applicationKS">
               <credential-reference
          clear-text="password"/>
        </key-manager>
     </key-managers>
     <server-ssl-contexts>
         <server-ssl-context name="applicationSSC"
     key-manager="applicationKM"/>
     </server-ssl-contexts>
</tls>

<tls>
	<key-stores>
            <key-store name="applicationKS">
                 <credential-reference
		 clear-text="password"/>
		 <implementation type="JKS"/>
                 <file
   path="/path/to/application.keystore”/>
            </key-store>
     </key-stores>
     <key-managers>
        <key-manager name="applicationKM"
         key-store="applicationKS">
               <credential-reference
          clear-text="password"/>
        </key-manager>
     </key-managers>
     <server-ssl-contexts>
         <server-ssl-context name="applicationSSC"
     key-manager="applicationKM"/>
     </server-ssl-contexts>
</tls>

Copy to Clipboard

Toggle word wrap

在 Red Hat build of Keycloak 中，使用 CLI 参数的等效配置如下：

kc.sh start
   --https-key-store-file /path/to/application.keystore
   --https-key-store-password password

kc.sh start
   --https-key-store-file /path/to/application.keystore
   --https-key-store-password password

Copy to Clipboard

Toggle word wrap

在 Red Hat build of Keycloak 中，您可以通过以 PEM 格式提供证书来配置 TLS，如下所示：

kc.sh start
   --https-certificate-file /path/to/certfile.pem
   --https-certificate-key-file /path/to/keyfile.pem

kc.sh start
   --https-certificate-file /path/to/certfile.pem
   --https-certificate-key-file /path/to/keyfile.pem

Copy to Clipboard

Toggle word wrap

2.4.4. 迁移集群和缓存配置
复制链接

Red Hat Single Sign-On 7.6 为将服务器作为独立、独立集群和域集群运行提供了不同的操作模式。这些模式在启动脚本和配置文件中有所不同。Red Hat build of Keycloak 提供了带有单个启动脚本的简化解决方案： kc.sh。

要将服务器作为独立或独立集群运行，请使用 kc.sh 脚本：

Expand

红帽构建的 Keycloak	Red Hat Single Sign-On 7.6
`./kc.sh start --cache=local`	`./standalone.sh`
`./kc.sh start [--cache=ispn]`	`./standalone.sh --server-config=standalone-ha.xml`

--cache 参数的默认值为 start 模式：

local - 当执行 start-dev 命令时
ISP N- 执行 start 命令时

在 Red Hat Single Sign-On 7.6 中，集群和缓存配置是通过 Infinispan 子系统完成的，而在 Red Hat build of Keycloak 中，大多数配置都是通过单独的 Infinispan 配置文件完成的。例如，以前的 Infinispan 配置如下所示：

<subsystem xmlns="urn:jboss:domain:infinispan:13.0">
<cache-container name="keycloak" marshaller="JBOSS" modules="org.keycloak.keycloak-model-infinispan">
                <local-cache name="realms">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="users">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="sessions"/>
                <local-cache name="authenticationSessions"/>
                <local-cache name="offlineSessions"/>
			...
</cache-container>
</subsystem>

<subsystem xmlns="urn:jboss:domain:infinispan:13.0">
<cache-container name="keycloak" marshaller="JBOSS" modules="org.keycloak.keycloak-model-infinispan">
                <local-cache name="realms">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="users">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="sessions"/>
                <local-cache name="authenticationSessions"/>
                <local-cache name="offlineSessions"/>
			...
</cache-container>
</subsystem>

Copy to Clipboard

Toggle word wrap

相关的配置选项作为配置选项提供。例如，使用选项 cache-embedded-realms-max-count 来配置域缓存中的最大条目数。

注意

红帽构建的 Keycloak 不支持域集群模式。

2.4.4.1. 传输堆栈
复制链接

现在，默认的传输堆栈是 jdbc-ping，它利用数据库发现其他节点，使用 TCP 作为传输，并通过 TLS 自动加密它。它可在云和非云环境中正常工作。

所有其他传输堆栈都已弃用。您应该将缓存配置迁移到 jdbc-ping。

我们建议设置 cache-embedded-network-bind-address 参数，以确保红帽构建的 Keycloak 绑定到正确的接口。在没有透明联网的环境中，设置参数 cache-embedded-network-external-port 和 cache-embedded-network-external-address，以指定如何从其他节点访问红帽构建的 Keycloak 节点。

2.4.5. 迁移主机名和代理配置
复制链接

在 Red Hat build of Keycloak 中，您现在被义务来配置 Hostname SPI，以便在重定向用户或与其客户端通信时，服务器将如何创建前端和后端 URL。

例如，如果您有一个类似于 Red Hat Single Sign-On 7.6 安装中的配置：

<spi name="hostname">
      <default-provider>default</default-provider>
      <provider name="default" enabled="true">
           <properties>
              <property name="frontendUrl" value="myFrontendUrl"/>
              <property name="forceBackendUrlToFrontendUrl" value="true"/>
           </properties>
      </provider>
</spi>

<spi name="hostname">
      <default-provider>default</default-provider>
      <provider name="default" enabled="true">
           <properties>
              <property name="frontendUrl" value="myFrontendUrl"/>
              <property name="forceBackendUrlToFrontendUrl" value="true"/>
           </properties>
      </provider>
</spi>

Copy to Clipboard

Toggle word wrap

您可以在红帽构建的 Keycloak 中将其转换为以下配置选项：

kc.sh start
    --hostname myFrontendUrl

kc.sh start
    --hostname myFrontendUrl

Copy to Clipboard

Toggle word wrap

hostname 配置选项允许您设置集群从集群前面的入口层公开到公共的基本 URL。您还可以通过设置 hostname-admin 配置选项来为管理资源设置 URL。

红帽构建的 Keycloak 允许您配置应反映哪些反向代理标头。您可以使用 Forwarded 标头或 X-ForwardedDebug 标头集合。例如：

kc.sh start --proxy-headers xforwarded

kc.sh start --proxy-headers xforwarded

Copy to Clipboard

Toggle word wrap

注意

主机名和代理配置用于确定资源 URL (redirect URI、CSS 和 JavaScript 链接、OIDC 已知的端点等)，而不是主动阻止传入的请求。没有 hostname/proxy 选项更改红帽构建的 Keycloak 服务器侦听的实际绑定地址或端口 - 这负责 HTTP/TLS 选项。在 Red Hat Single Sign-On 7.6 中，强烈建议设置主机名，但不强制设置。在 Red Hat build of Keycloak 中，现在需要使用 start 命令时，除非使用 --hostname-strict=false 选项明确禁用。

2.4.6. 迁移信任存储配置
复制链接

truststore 用于外部 TLS 通信，如 HTTPS 请求和 LDAP 服务器。要使用信任存储，您可以将远程服务器或 CA 的证书导入到信任者中。然后，您可以启动红帽构建的 Keycloak 服务器，指定系统信任存储。

例如，以前的配置如下所示：

<spi name="truststore">
    <provider name="file" enabled="true">
        <properties>
            <property name="file" value="path/to/myTrustStore.jks"/>
            <property name="password" value="password"/>
            <property name="hostname-verification-policy" value="WILDCARD"/>
        </properties>
    </provider>
</spi>

<spi name="truststore">
    <provider name="file" enabled="true">
        <properties>
            <property name="file" value="path/to/myTrustStore.jks"/>
            <property name="password" value="password"/>
            <property name="hostname-verification-policy" value="WILDCARD"/>
        </properties>
    </provider>
</spi>

Copy to Clipboard

Toggle word wrap

红帽构建的 Keycloak 支持采用以下格式的信任存储： PEM 文件，或带有扩展 .p12 和 .pfx 的 PKCS12 文件。对于 PKCS12 文件，证书必须加密，这意味着不需要密码。需要转换 JKS 信任存储。由于 Java keytool 强制最小密码长度为 6 个字符，因此 openssl 可用作创建未加密的 PKCS12 信任存储的替代选择。

流程

通过导入旧 JKS 信任存储的内容，使用 keytool 创建一个带有临时密码的 PKCS12 信任存储。

keytool -importkeystore -srckeystore path/to/myTrustStore.jks \
   -destkeystore path/to/myTrustStore.p12 \
   -srcstoretype jks \
   -deststoretype pkcs12 \
   -srcstorepass password \
   -deststorepass temp-password

keytool -importkeystore -srckeystore path/to/myTrustStore.jks \
   -destkeystore path/to/myTrustStore.p12 \
   -srcstoretype jks \
   -deststoretype pkcs12 \
   -srcstorepass password \
   -deststorepass temp-password

Copy to Clipboard

Toggle word wrap

使用 openssl 导出新 PKCS12 信任存储的内容。

openssl pkcs12 -in path/to/myTrustStore.p12 \
   -out path/to/myTrustStore.pem \
   -nodes -passin pass:temp-password

openssl pkcs12 -in path/to/myTrustStore.p12 \
   -out path/to/myTrustStore.pem \
   -nodes -passin pass:temp-password

Copy to Clipboard

Toggle word wrap

使用 openssl 将内容重新导入到新的未加密的 PKCS12 信任存储中。

openssl pkcs12 -export -in path/to/myTrustStore.pem \
   -out path/to/myUnencryptedTrustStore.p12 \
   -nokeys -passout pass:

openssl pkcs12 -export -in path/to/myTrustStore.pem \
   -out path/to/myUnencryptedTrustStore.p12 \
   -nokeys -passout pass:

Copy to Clipboard

Toggle word wrap

在本例中，生成的 CLI 参数如下：

kc.sh start
    --truststore-paths path/to/myUnencryptedTrustStore.p12
    --tls-hostname-verifier WILDCARD

kc.sh start
    --truststore-paths path/to/myUnencryptedTrustStore.p12
    --tls-hostname-verifier WILDCARD

Copy to Clipboard

Toggle word wrap

2.4.7. 迁移 vault 配置
复制链接

Keystore Vault 是 Vault SPI 的实现，对于将 secret 存储在裸机安装中非常有用。此密码库是 Red Hat Single Sign-On 7.6 中的 Elytron Credential Store 替代。

<spi name="vault">
     <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="path/to/keystore.p12"/>
             <property name="secret" value="password"/>
     </properties>
   </provider>
</spi>

<spi name="vault">
     <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="path/to/keystore.p12"/>
             <property name="secret" value="password"/>
     </properties>
   </provider>
</spi>

Copy to Clipboard

Toggle word wrap

在 Red Hat build of Keycloak 中，使用 CLI 参数的等效配置将是：

kc.sh start
   --vault keystore
   --vault-file /path/to/keystore.p12
   --vault-pass password

kc.sh start
   --vault keystore
   --vault-file /path/to/keystore.p12
   --vault-pass password

Copy to Clipboard

Toggle word wrap

然后，可以在管理控制台中的多个位置访问存储在密码库中的 secret。当涉及从现有 Elytron vault 迁移到基于 Java KeyStore 的新密码库时，不需要更改 realm 配置。如果新创建的 Java 密钥存储包含相同的机密，您的现有域配置应该可以正常工作。

假设您使用默认的 REALM_UNDERSCORE_KEY 键解析器，该机密可以被 ${vault.realm-name_alias} （例如，在 LDAP 用户联邦配置中）访问。

2.4.8. 迁移 JVM 设置
复制链接

Red Hat build of Keycloak 中的 JVM 设置方法类似于 Red Hat Single Sign-On 7.6 方法。您仍然需要设置特定的环境变量，但 /bin 文件夹不包含配置文件，如 standalone.conf。

红帽 Keycloak 的构建提供了各种默认 JVM 参数，该参数适用于大多数部署，因为它在内存分配和 CPU 开销方面提供了良好的吞吐量和效率。另外，其他默认 JVM 参数可确保平稳运行红帽构建的 Keycloak 实例，因此当您更改用例的参数时请小心。

要更改 JVM 参数或 GC 设置，您可以设置特定环境变量，这些变量指定为 Java 选项。对于这些设置的完整覆盖，请指定 JAVA_OPTS 环境变量。

当只需要附加特定 Java 属性时，您可以指定 JAVA_OPTS_APPEND 环境变量。如果没有指定 JAVA_OPTS 环境变量，则会使用默认的 Java 属性，并可在 ./kc.sh 脚本中找到。

例如，您可以指定特定的 Java 选项，如下所示：

export JAVA_OPTS_APPEND=-XX:+HeapDumpOnOutOfMemoryError
kc.sh start

export JAVA_OPTS_APPEND=-XX:+HeapDumpOnOutOfMemoryError
kc.sh start

Copy to Clipboard

Toggle word wrap

2.4.9. 迁移 SPI 供应商配置
复制链接

通过新的配置系统提供了 SPI 提供程序的配置。这是旧格式：

<spi name="<spi-id>">
    <provider name="<provider-id>" enabled="true">
        <properties>
            <property name="<property>" value="<value>"/>
        </properties>
    </provider>
</spi>

<spi name="<spi-id>">
    <provider name="<provider-id>" enabled="true">
        <properties>
            <property name="<property>" value="<value>"/>
        </properties>
    </provider>
</spi>

Copy to Clipboard

Toggle word wrap

这是新格式：

spi-<spi-id>--<provider-id>--<property>=<value>

spi-<spi-id>--<provider-id>--<property>=<value>

Copy to Clipboard

Toggle word wrap

Expand

Source	格式
CLI	./kc.sh start --spi-connections-http-client—default—connection-pool-size 10
环境变量	KC_SPI_CONNECTIONS_HTTP_CLIENTDEFAULTCONNECTION_POOL_SIZE=10
配置文件	spi-connections-http-client—default—connection-pool-size=10
Java 密钥存储文件	kc.spi-connections-http-client—default—connection-pool-size=10

2.4.10. 对配置进行故障排除
复制链接

使用这些命令进行故障排除：

kc.sh show-config - 显示从中加载特定属性的配置源及其值。您可以检查属性及其值是否已正确传播。
当出现错误时，kc .sh --verbose start - 会输出整个错误堆栈 trace。

2.4. 迁移配置

2.4.1. 迁移数据库配置
复制链接

2.4.2. 迁移额外的数据源配置
复制链接

2.4.3. 迁移 HTTP 和 TLS 配置
复制链接

2.4.4. 迁移集群和缓存配置
复制链接

2.4.4.1. 传输堆栈
复制链接

2.4.5. 迁移主机名和代理配置
复制链接

2.4.6. 迁移信任存储配置
复制链接

2.4.7. 迁移 vault 配置
复制链接

2.4.8. 迁移 JVM 设置
复制链接

2.4.9. 迁移 SPI 供应商配置
复制链接

2.4.10. 对配置进行故障排除
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4. 迁移配置

2.4.1. 迁移数据库配置复制链接链接已复制到粘贴板!

2.4.2. 迁移额外的数据源配置复制链接链接已复制到粘贴板!

2.4.3. 迁移 HTTP 和 TLS 配置复制链接链接已复制到粘贴板!

2.4.4. 迁移集群和缓存配置复制链接链接已复制到粘贴板!

2.4.4.1. 传输堆栈复制链接链接已复制到粘贴板!

2.4.5. 迁移主机名和代理配置复制链接链接已复制到粘贴板!

2.4.6. 迁移信任存储配置复制链接链接已复制到粘贴板!

2.4.7. 迁移 vault 配置复制链接链接已复制到粘贴板!

2.4.8. 迁移 JVM 设置复制链接链接已复制到粘贴板!

2.4.9. 迁移 SPI 供应商配置复制链接链接已复制到粘贴板!

2.4.10. 对配置进行故障排除复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4.1. 迁移数据库配置
复制链接

2.4.2. 迁移额外的数据源配置
复制链接

2.4.3. 迁移 HTTP 和 TLS 配置
复制链接

2.4.4. 迁移集群和缓存配置
复制链接

2.4.4.1. 传输堆栈
复制链接

2.4.5. 迁移主机名和代理配置
复制链接

2.4.6. 迁移信任存储配置
复制链接

2.4.7. 迁移 vault 配置
复制链接

2.4.8. 迁移 JVM 设置
复制链接

2.4.9. 迁移 SPI 供应商配置
复制链接

2.4.10. 对配置进行故障排除
复制链接