2.4. 迁移配置

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

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

<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>

在红帽构建的 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

每当使用 production 模式（由 start 选项代表）时，默认需要 HTTP 配置。

您可以使用 --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>

在红帽构建的 Keycloak 中，使用 CLI 参数的等效配置如下：

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

在 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

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

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

--cache 参数的默认值是 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>

在红帽构建的 Keycloak 中，默认的 Infinispan 配置文件位于 conf/cache-ispn.xml 文件中。您可以提供自己的 Infinispan 配置文件，并使用 CLI 参数指定该文件，如下所示：

kc.sh start --cache-config-file my-cache-file.xml

唯一的改进是通过提供 CLI 选项 cache-stack （具有优先权）来覆盖缓存配置文件中定义的堆栈。考虑上面指定的 Infinispan 配置文件 my-cache-file.xml 的一部分，使用自定义 JGroups 传输堆栈，如下所示：

您可以注意到 keycloak 缓存容器的传输堆栈被设置为 tcp，但可使用 CLI 选项覆盖它，如下所示：

<jgroups>
	<stack name=”my-encrypt-udp” extends=”udp”>
		…
	</stack>
</jgroups>

<cache-container name=”keycloak”>
	<transport stack=”tcp”/>
	…
</cache-container>

kc.sh start
   --cache-config-file my-cache-file.xml
   --cache-stack my-encrypt-udp

执行上述命令后，将使用 my-encrypt-udp 传输堆栈。

在红帽构建的 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>

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

kc.sh start
    --hostname-url myFrontendUrl
    --hostname-strict-backchannel true

hostname-url 配置选项允许您设置从集群前运行的 ingress 层公开的基本 URL。您还可以通过设置 hostname-admin-url 配置选项来设置管理资源的 URL。

为了在代理后运行集群时更轻松地启用 HTTP 标头转发，红帽构建的 Keycloak 允许您根据代理上的 TLS 终止模式设置不同的代理模式：

设置 edge 或 reencrypt 可让红帽构建的 Keycloak 来识别代理设置的 HTTP Forwarded 和 X-Forwarded 114 标头。在向公共集群公开前，您需要确保代理覆盖这些标头。

truststore 用于外部 TLS 通信，如 HTTPS 请求和 LDAP 服务器。要使用信任存储，您可以将远程服务器或 CA 的证书导入到信任中。然后，您可以启动指定信任存储 SPI 的红帽构建 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>

在红帽构建的 Keycloak 中，使用 CLI 参数的等效配置将是：

kc.sh start
  --spi-truststore-file-file /path/to/myTrustStore.jks
  --spi-truststore-file-password password
  --spi-truststore-file-hostname-verification-policy WILDCARD

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>

在红帽构建的 Keycloak 中，使用 CLI 参数的等效配置将是：

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

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

鉴于您使用默认的 REALM_UNDERSCORE_KEY 密钥解析器，可以通过 ${vault.realm-name_alias} （例如，在 LDAP 用户联邦配置中）访问 secret。

红帽构建的 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

SPI 供应商的配置可通过新的配置系统获得。这是旧格式：

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

这是新格式：

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

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