2.4. 迁移配置

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

在 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

默认情况下，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>

在 Red Hat build of 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 为将服务器作为独立、独立集群和域集群运行提供了不同的操作模式。这些模式在启动脚本和配置文件中有所不同。Red Hat build of 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>

在 Red Hat build of 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 传输堆栈。

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

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

kc.sh start
    --hostname myFrontendUrl

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

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

kc.sh start --proxy-headers xforwarded

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>

红帽构建的 Keycloak 支持采用以下格式的信任存储： PEM 文件，或带有扩展 .p12 和 .pfx 的 PKCS12 文件。对于 PKCS12 文件，证书必须加密，这意味着不需要密码。需要转换 JKS 信任存储。例如：

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

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

kc.sh start
    --truststore-paths path/to/myTrustStore.p12
    --tls-hostname-verifier 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>

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

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

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

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

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

通过新的配置系统提供了 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>

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