Red Hat Single Sign-On 基于 JBoss EAP 应用服务器及其子项目（用于缓存）和 Hibernate（用于持久性）。本指南仅涵盖基础架构级别配置的基础知识。强烈建议您仔细阅读 JBoss EAP 及其子项目的文档。以下是文档的链接：

安装 Red Hat Single Sign-On 服务器需要满足这些先决条件：

Red Hat Single Sign-On 服务器下载 ZIP 文件包含运行 Red Hat Single Sign-On 服务器的脚本和二进制文件。您首先安装 7.6 服务器，然后安装 7.6.8 服务器补丁。

您必须订阅 JBoss EAP 7.4 和 RH-SSO 7.6 存储库，然后才能从 RPM 安装 RH-SSO。

subscription-manager repos --enable=jb-eap-7.4-for-rhel-<RHEL_VERSION>-server-rpms --enable=rhel-<RHEL_VERSION>-server-rpms

subscription-manager repos --enable=jb-eap-7.4-for-rhel-8-x86_64-rpms --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms

以下是服务器分发中的一些重要目录：

独立操作模式仅在您要运行一个且只有一个红帽单点登录服务器实例时很有用。它不适用于集群部署，所有缓存都不是分布式且仅本地的缓存。不建议在生产环境中使用独立模式，因为您将存在单点故障。如果您的独立模式服务器停机，用户将无法登录。这个模式对使用 Red Hat Single Sign-On 的功能进行测试和 play 非常有用。

$ .../bin/standalone.sh

> ...\bin\standalone.bat

$ ./bin/jboss-cli.sh --file=docs/examples/enable-elytron-se17.cli

> .\bin\jboss-cli.bat --file=docs\examples\enable-elytron-se17.cli

当您要在集群中运行 Red Hat Single Sign-On 时，会应用独立集群操作模式。这个模式要求您在要运行服务器实例的每台机器上具有 Red Hat Single Sign-On 分发的副本。该模式最初部署可能非常容易，但可能会变得非常繁琐。要进行配置更改，您可以修改每台机器上的每个分发版本。对于大型集群来说，这个模式可能会变得耗时，且容易出错。

$ .../bin/standalone.sh --server-config=standalone-ha.xml

> ...\bin\standalone.bat --server-config=standalone-ha.xml

$ ./bin/jboss-cli.sh --file=docs/examples/enable-elytron-se17.cli -Dconfig=standalone-ha.xml

> .\bin\jboss-cli.bat --file=docs\examples\enable-elytron-se17.cli "-Dconfig=standalone-ha.xml"

域模式是集中管理并发布服务器配置的方法。

以标准模式运行集群可能会很快就会成为随着集群大小增长的聚合。每次您需要进行配置更改时，您都会在集群的每个节点上执行它。域模式通过提供用于存储和发布配置的核心位置来解决这个问题。设置起来可能非常复杂，但最后很值得设置。该功能内置于红帽单点登录的 JBoss EAP 应用服务器中。

以下是在域模式下运行的一些基本概念：

在域模式中，在主节点上启动域控制器。集群的配置驻留在域控制器中。接下来，在集群的每个计算机上启动主机控制器。每个主机控制器部署配置都指定在该计算机上启动多少个红帽单点登录服务器实例。当主机控制器启动时，它会启动任意数量的 Red Hat Single Sign-On 服务器实例，就像被配置为这样做。这些服务器实例从域控制器拉取其配置。

    <profiles>
        <profile name="auth-server-standalone">
            ...
        </profile>
        <profile name="auth-server-clustered">
            ...
        </profile>

    <socket-binding-groups>
        <socket-binding-group name="standard-sockets" default-interface="public">
           ...
        </socket-binding-group>
        <socket-binding-group name="ha-sockets" default-interface="public">
           ...
        </socket-binding-group>
        <!-- load-balancer-sockets should be removed in production systems and replaced with a better software or hardware based one -->
        <socket-binding-group name="load-balancer-sockets" default-interface="public">
           ...
        </socket-binding-group>
    </socket-binding-groups>

$ domain.sh -Djboss.http.port=80

    <server-groups>
        <!-- load-balancer-group should be removed in production systems and replaced with a better software or hardware based one -->
        <server-group name="load-balancer-group" profile="load-balancer">
            <jvm name="default">
                <heap size="64m" max-size="512m"/>
            </jvm>
            <socket-binding-group ref="load-balancer-sockets"/>
        </server-group>
        <server-group name="auth-server-group" profile="auth-server-clustered">
            <jvm name="default">
                <heap size="64m" max-size="512m"/>
            </jvm>
            <socket-binding-group ref="ha-sockets"/>
        </server-group>
    </server-groups>

    <servers>
        <!-- remove or comment out next line -->
        <server name="load-balancer" group="loadbalancer-group"/>
        ...
    </servers>

    <servers>
        ...
        <server name="server-one" group="auth-server-group" auto-start="true">
             <socket-bindings port-offset="150"/>
        </server>
    </servers>

$ .../bin/domain.sh --host-config=host-master.xml

> ...\bin\domain.bat --host-config=host-master.xml

$ ./bin/jboss-cli.sh --file=docs/examples/enable-keycloak-se17-domain.cli

> .\bin\jboss-cli.bat --file=docs\examples\enable-keycloak-se17-domain.cli

在 Red Hat Single Sign-On 7.2 中作为技术预览功能引入的跨站点复制不再作为任何 Red Hat SSO 7.x 发行版本中支持的功能提供，包括最新的 RH-SSO 7.6 发行版本。红帽不推荐任何客户在其环境中实施或使用此功能，因为它不被支持。另外，对这个功能的支持例外不再被视为或接受。

将讨论跨站点复制的新解决方案，并在未来的 Red Hat build of Keycloak (RHBK)中考虑，这是引入的产品，而不是 Red Hat SSO 8。稍后会提供更详细的信息。

使用该设置的上下文中讨论每个配置设置的具体细节。但是，了解用于声明 SPI 提供程序设置的格式很有用。

Red Hat Single Sign-On 是一个高度模块化的系统，实现了极大的灵活性。超过 50 个服务提供商接口(SPI)，您可以交换出每个 SPI 的实现。SPI 的实施称为 提供程序。

SPI 声明中的所有元素都是可选的，但完整的 SPI 声明如下所示：

<spi name="myspi">
    <default-provider>myprovider</default-provider>
    <properties>
        <property name="spi-foo" value="spi-bar"/>
    </properties>
    <provider name="myprovider" enabled="true">
        <properties>
            <property name="foo" value="bar"/>
        </properties>
    </provider>
    <provider name="mysecondprovider" enabled="true">
        <properties>
            <property name="foo" value="foo"/>
        </properties>
    </provider>
</spi>

在这里，我们为 SPI myspi 定义了两个提供程序。default-provider 列为 myprovider。但是，最多是 SPI 来确定它如何处理此设置。有些 SPI 允许多个提供程序，有些则不允许。因此，default-provider 可以帮助 SPI 选择。

SPI 属性 可以用来指定 SPI 特定的配置属性。例如，用户、client 和 role SPI 允许通过 storageProviderTimeout 属性以毫秒为单位配置存储供应商超时，如下所示：

<spi name="user">
    <properties>
        <property name="storageProviderTimeout" value="10000"/>
    </properties>
</spi>

另请注意，每个供应商都定义了自己的一组配置属性。上述两个提供程序的事实具有名为 foo 的属性，只是一个统一的显示。

每个属性值的类型由提供程序来解释。但是，有一个例外。考虑 eventsStore SPI 的 jpa 供应商：

<spi name="eventsStore">
    <provider name="jpa" enabled="true">
        <properties>
            <property name="exclude-events" value="[&quot;EVENT1&quot;,
                                                    &quot;EVENT2&quot;]"/>
        </properties>
    </provider>
</spi>

我们看到该值以方括号开头和结束。这意味着该值将作为列表传递到提供程序。在本例中，系统将传递提供程序一个列表，其两个元素值为 EVENT1 和 EVENT2。要在列表中添加更多值，只需使用逗号分隔各个列表元素。不幸的是，您需要使用 " 转义引号括起 每个列表元素。

有关自定义提供程序和配置的详情，请遵循 服务器开发人员指南。

除了手动编辑配置之外，您还可以通过 jboss-cli 工具发出命令来更改配置。CLI 允许您在本地或远程配置服务器。在结合脚本时，它特别有用。

要启动 JBoss EAP CLI，您需要运行 jboss-cli。

$ .../bin/jboss-cli.sh

> ...\bin\jboss-cli.bat

这将会出现类似如下的提示：

[disconnected /]

如果您想在运行的服务器上执行命令，则首先执行 连接 命令。

[disconnected /] connect
connect
[standalone@localhost:9990 /]

您可以考虑自己，"我没有输入任何用户名或密码！"。如果在与运行独立服务器或域控制器相同的机器上运行 jboss-cli，并且您的帐户有适当的文件权限，则不必在管理用户名和密码中设置或输入。如果您对此设置不熟悉，请参阅 JBoss EAP 配置指南 以了解更多详细信息。

如果您发生在与独立服务器相同的机器上，且您希望在服务器未激活时发出命令，您可以将服务器嵌入到 CLI 中，并在禁止传入的请求的特殊模式中进行更改。为此，请先执行 embed-server 命令以及您要更改的配置文件。

[disconnected /] embed-server --server-config=standalone.xml
[standalone@embedded /]

CLI 也可以在 GUI 模式下运行。GUI 模式启动 Swing 应用程序，可让您以图形方式查看并编辑 正在运行的 服务器的完整管理模式。当您需要帮助格式化 CLI 命令并了解可用选项时，GUI 模式特别有用。GUI 还可以从本地或远程服务器检索服务器日志。

CLI 具有广泛的脚本功能。脚本只是一个文本文件，其中带有 CLI 命令。请考虑关闭主题和模板缓存的简单脚本。

/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false)
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false)

要执行脚本，您可以使用 CLI GUI 中的 Scripts 菜单，或者从命令行执行脚本，如下所示：

$ .../bin/jboss-cli.sh --file=turn-off-caching.cli

以下是一些配置任务，以及如何使用 CLI 命令执行它们。请注意，在所有示例中，我们使用通配符路径 ** 表示您应该替换或者 keycloak-server 子系统的路径。

对于独立，这只意味着：

** = /subsystem=keycloak-server

对于域模式，这意味着类似：

** = /profile=auth-server-clustered/subsystem=keycloak-server

/subsystem=keycloak-server/:write-attribute(name=web-context,value=myContext)

**/theme=defaults/:write-attribute(name=default,value=myTheme)

**/spi=mySPI/:add
**/spi=mySPI/provider=myProvider/:add(enabled=true)

**/spi=mySPI/provider=myProvider/:write-attribute(name=enabled,value=false)

**/spi=mySPI/:write-attribute(name=default-provider,value=myProvider)

**/spi=mySPI/:map-put(name=properties, key=storageProviderTimeout, value=10000)

**/spi=mySPI/:map-remove(name=properties, key=storageProviderTimeout)

**/spi=dblock/:add(default-provider=jpa)
**/spi=dblock/provider=jpa/:add(properties={lockWaitTimeout => "900"},enabled=true)

**/spi=dblock/provider=jpa/:map-put(name=properties,key=lockWaitTimeout,value=3)

**/spi=dblock/provider=jpa/:map-remove(name=properties,key=lockRecheckTime)

**/spi=eventsStore/provider=jpa/:map-put(name=properties,key=exclude-events,value=[EVENT1,EVENT2])

以下是您要执行的步骤，以获取为红帽单点登录配置的 RDBMS。

本章将在所有示例中使用 PostgresSQL。其他数据库遵循相同的安装步骤。

为您的 RDBMS 查找并下载 JDBC 驱动程序 JAR。在使用这个驱动程序前，必须将其打包为模块并将其安装到服务器中。模块定义了挂载到红帽单点登录类路径中的 JAR，这些 JAR 依赖于其他模块的依赖项。

将 JDBC 声明到您的部署配置文件中，使它在服务器引导时加载并可用。

您修改 Red Hat Single Sign-On 用来将其连接到您的新外部数据库的现有数据源配置。您可以在您注册 JDBC 驱动程序的同一配置文件和 XML 块中执行此操作。以下是设置到新数据库的连接的示例：

  <subsystem xmlns="urn:jboss:domain:datasources:6.0">
     <datasources>
       ...
       <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
           <connection-url>jdbc:postgresql://localhost/keycloak</connection-url>
           <driver>postgresql</driver>
           <pool>
               <max-pool-size>20</max-pool-size>
           </pool>
           <security>
               <user-name>William</user-name>
               <password>password</password>
           </security>
       </datasource>
        ...
     </datasources>
  </subsystem>

此组件的配置可在您的分发的 standalone.xml、standalone-ha.xml 或 domain.xml 文件中找到。这个文件的位置取决于您的 操作模式。

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.2">
    ...
    <spi name="connectionsJpa">
     <provider name="default" enabled="true">
         <properties>
             <property name="dataSource" value="java:jboss/datasources/KeycloakDS"/>
             <property name="initializeEmpty" value="false"/>
             <property name="migrationStrategy" value="manual"/>
             <property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
         </properties>
     </provider>
    </spi>
    ...
</subsystem>

可能的配置选项有：

Red Hat Single Sign-On 中的数据库 schema 在以下特殊字段中只有 Unicode 字符串的帐户：

否则，字符仅限于数据库编码中包含的字符，通常是 8 位。但是，对于某些数据库系统，可以启用 Unicode 字符的 UTF-8 编码，并在所有文本字段中使用完整的 Unicode 字符集。通常，这与使用 8 位编码的情况相比，这个字符串的最大长度会比较短。

有些数据库需要对数据库和/或 JDBC 驱动程序进行特殊设置，以便能处理 Unicode 字符。请在下面找到您的数据库的设置。请注意，如果此处列出了数据库，它仍然可以正常工作，只要它在数据库和 JDBC 驱动程序的级别上正确处理 UTF-8 编码。

从技术上讲，所有字段的 Unicode 支持的关键条件是数据库是否允许为 VARCHAR 和 CHAR 字段设置 Unicode 字符集。如果是，则 Unicode 的几率会非常容易，通常以字段长度的代价为代价。如果它只支持 NVARCHAR 和 NCHAR 字段的 Unicode 支持，则所有文本字段的 Unicode 支持不太可能，因为 Keycloak 模式使用 VARCHAR 和 CHAR 字段。

show server_encoding;

create database keycloak with encoding 'UTF8';

默认主机名供应商使用配置的 frontendUrl 作为 frontend 请求的基本 URL（来自 user-agents 的requests），并使用请求 URL 作为后端请求（从客户端重定向请求）的基础。

frontend 请求不必与 Keycloak 服务器具有相同的 context-path。这意味着，您可以在 上公开 Keycloak，例如 https://auth.example.org 或 https://example.org/keycloak，而内部它的 URL 可能是 https://10.0.0.10:8080/auth。

这样，可以把 user-agents（浏览器）通过公共域名向 Red Hat Single Sign-On 发送请求，而内部客户端则可使用内部域名或 IP 地址。

这反映在 OpenID Connect Discovery 端点中，例如，authorization_endpoint 使用 frontend URL，而 token_endpoint 使用后端 URL。在这里，一个实例的公共客户端会通过公共端点联系 Keycloak，这会导致 authorization_endpoint 和 token_endpoint 的基础是相同的。

要为 Keycloak 设置 frontendUrl，您可以将 -Dkeycloak.frontendUrl=https://auth.example.org 传递给启动，或者在 standalone.xml 中配置。请参见以下示例：

<spi name="hostname">
    <default-provider>default</default-provider>
    <provider name="default" enabled="true">
        <properties>
            <property name="frontendUrl" value="https://auth.example.com"/>
            <property name="forceBackendUrlToFrontendUrl" value="false"/>
        </properties>
    </provider>
</spi>

要使用 jboss-cli 更新 frontendUrl，请使用以下命令：

/subsystem=keycloak-server/spi=hostname/provider=default:write-attribute(name=properties.frontendUrl,value="https://auth.example.com")

如果您希望所有请求都通过公共域名，您可以强制后端请求使用前端 URL，也可以通过将 forceBackendUrlToFrontendUrl 设置为 true。

也可以覆盖单个域的默认前端 URL。这可以在管理控制台中完成。

如果您不想公开公共域中的 admin 端点和控制台，请使用属性 adminUrl 为 admin 控制台设置固定 URL，这与 frontendUrl 不同。还需要阻止外部对 /auth/admin 的访问，有关如何操作 "服务器管理指南" 的详细信息。

要开发自定义主机名提供程序，您需要实施 org.keycloak.urls.HostnameProviderProvidery 和 org.keycloak.urls.HostnameProvider。

请参阅《 服务器开发人员指南》 中的"服务提供程序接口"一节中的说明，了解如何开发自定义供应商。

默认情况下，红帽单点登录绑定到 localhost 回送地址 127.0.0.1。如果您需要网络中的身份验证服务器，这不是非常有用的默认值。通常，建议您在公共网络上部署反向代理或负载均衡器，并将流量路由到专用网络上的各个红帽单点登录服务器实例。在这两种情况下，您仍然需要设置网络接口，以绑定到 localhost 以外的其他接口。

设置绑定地址非常简单，可以在命令行中完成 Choosing a Operating Mode 章节中讨论的 standalone.sh 或 domain.sh 启动脚本。

$ standalone.sh -b 192.168.0.5

-b 交换机为任何公共接口设置 IP 绑定地址。

或者，如果您不想在命令行中设置绑定地址，您可以编辑部署的配置集配置。根据您的 操作模式，打开配置文件(standalone.xml 或 domain.xml )，并查找 interfaces XML 块。

    <interfaces>
        <interface name="management">
            <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
        </interface>
        <interface name="public">
            <inet-address value="${jboss.bind.address:127.0.0.1}"/>
        </interface>
    </interfaces>

公共接口 与创建可公开提供的套接字子系统相对应。这些子系统的一个示例是 Web 层，它是提供 Red Hat Single Sign-On 的身份验证端点的 Web 层。管理接口 对应于 JBoss EAP 的管理层所打开的套接字。具体来说，socket 允许您使用 jboss-cli.sh 命令行界面和 JBoss EAP web 控制台。

查看 公共接口 时，您会看到它具有特殊字符串 ${jboss.bind.address:127.0.0.1}。此字符串表示可以在命令行中通过设置 Java 系统属性覆盖的值 127.0.0.1，例如：

$ domain.sh -Djboss.bind.address=192.168.0.5

-b 只是此命令的简写表示法。因此，您可以直接在配置集中配置绑定地址值，或者在引导时在命令行中更改它。

为每个套接字打开的端口具有一个预定义的默认端口，可在命令行中或配置内被覆盖。要说明此配置，请预先以独立模式运行，并打开 …​/standalone/configuration/standalone.xml。???搜索 socket-binding-group。

    <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
        <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
        <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
        <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
        <socket-binding name="http" port="${jboss.http.port:8080}"/>
        <socket-binding name="https" port="${jboss.https.port:8443}"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>

socket-bindings 定义服务器将打开的套接字连接。这些绑定指定了它们使用 的接口 （绑定地址）以及他们将打开的端口号。您最感兴趣的对象有：

在域模式下运行时，套接字配置会很欺骗，因为示例 domain.xml 文件定义了多个 socket-binding-groups。???如果滚动到 server-group 定义，您可以看到每个 server-group 使用了哪些 socket-binding-group。

    <server-groups>
        <server-group name="load-balancer-group" profile="load-balancer">
            ...
            <socket-binding-group ref="load-balancer-sockets"/>
        </server-group>
        <server-group name="auth-server-group" profile="auth-server-clustered">
            ...
            <socket-binding-group ref="ha-sockets"/>
        </server-group>
    </server-groups>

这个默认行为由每个 Red Hat Single Sign-On 域的 SSL/HTTPS 模式定义。这在《 服务器管理指南》 中更为详细地讨论，但让我们为一些上下文和这些模式的简单概述。

每个域的 SSL 模式可在 Red Hat Single Sign-On 管理控制台中配置。

如果您不使用反向代理或负载均衡器来处理 HTTPS 流量，则需要为 Red Hat Single Sign-On 服务器启用 HTTPS。这涉及

$ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity 10950
    Enter keystore password: secret
    Re-enter new password: secret
    What is your first and last name?
    [Unknown]:  localhost
    What is the name of your organizational unit?
    [Unknown]:  Keycloak
    What is the name of your organization?
    [Unknown]:  Red Hat
    What is the name of your City or Locality?
    [Unknown]:  Westford
    What is the name of your State or Province?
    [Unknown]:  MA
    What is the two-letter country code for this unit?
    [Unknown]:  US
    Is CN=localhost, OU=Keycloak, O=Test, L=Westford, ST=MA, C=US correct?
    [no]:  yes

Red Hat Single Sign-On 服务器通常需要向它保护的应用程序和服务提供非浏览器 HTTP 请求。auth 服务器通过维护 HTTP 客户端连接池来管理这些传出连接。您需要在 standalone.xml、standalone-ha.xml 或 domain.xml 中配置。这个文件的位置取决于您的 操作模式。

<spi name="connectionsHttpClient">
    <provider name="default" enabled="true">
        <properties>
            <property name="connection-pool-size" value="256"/>
        </properties>
    </provider>
</spi>

可能的配置选项有：

.*\.(google|googleapis)\.com;http://www-proxy.acme.com:8080

.*\.(google|googleapis)\.com;http://user01:pas2w0rd@www-proxy.acme.com:8080

# All requests to Google APIs should use http://www-proxy.acme.com:8080 as proxy
.*\.(google|googleapis)\.com;http://www-proxy.acme.com:8080

# All requests to internal systems should use no proxy
.*\.acme\.com;NO_PROXY

# All other requests should use http://fallback:8080 as proxy
.*;http://fallback:8080

echo SETUP: Configure proxy routes for HttpClient SPI

# In case there is no connectionsHttpClient definition yet
/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:add(enabled=true)

# Configure the proxy-mappings
/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:write-attribute(name=properties.proxy-mappings,value=[".*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080",".*\\.acme\\.com;NO_PROXY",".*;http://fallback:8080"])

<spi name="connectionsHttpClient">
    <provider name="default" enabled="true">
        <properties>
            <property
            name="proxy-mappings"
            value="[&quot;.*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080&quot;,&quot;.*\\.acme\\.com;NO_PROXY&quot;,&quot;.*;http://fallback:8080&quot;]"/>
        </properties>
    </provider>
</spi>

HTTPS_PROXY=https://www-proxy.acme.com:8080
NO_PROXY=google.com,login.facebook.com

<spi name="connectionsHttpClient">
    <provider name="default" enabled="true">
        <properties>
            <property name="proxy-mappings" value=".*;NO_PROXY"/>
        </properties>
    </provider>
</spi>

$ keytool -import -alias HOSTDOMAIN -keystore truststore.jks -file host-certificate.cer

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

推荐的网络架构用于部署红帽单点登录，是在公共 IP 地址上设置 HTTP/HTTPS 负载均衡器，该地址将请求路由到红帽单点登录服务器（位于专用网络上）。这会隔离所有集群连接，并提供保护服务器的 nice 方法。

Red Hat Single Sign-On 带有利用域模式的开箱即用集群演示。如需了解更多详细信息 ，请参阅集群域示例 章节。

本节讨论在集群的 Red Hat Single Sign-On 部署前放置反向代理或负载均衡器前需要配置的一些事项。它还涵盖了配置 集群域示例 的内置负载均衡器。

下图演示了负载平衡器的使用。在本例中，负载均衡器充当三个客户端和三个红帽单点登录服务器集群之间的反向代理。

<subsystem xmlns="urn:jboss:domain:undertow:12.0">
   <buffer-cache name="default"/>
   <server name="default-server">
      <ajp-listener name="ajp" socket-binding="ajp"/>
      <http-listener name="default" socket-binding="http" redirect-socket="https"
          proxy-address-forwarding="true"/>
      ...
   </server>
   ...
</subsystem>

<subsystem xmlns="urn:jboss:domain:undertow:12.0">
     <buffer-cache name="default"/>
     <server name="default-server">
         <ajp-listener name="ajp" socket-binding="ajp"/>
         <http-listener name="default" socket-binding="http" redirect-socket="https"/>
         <host name="default-host" alias="localhost">
             ...
             <filter-ref name="proxy-peer"/>
         </host>
     </server>
        ...
     <filters>
         ...
         <filter name="proxy-peer"
                 class-name="io.undertow.server.handlers.ProxyPeerAddressHandler"
                 module="io.undertow.core" />
     </filters>
 </subsystem>

<subsystem xmlns="urn:jboss:domain:undertow:12.0">
    ...
    <http-listener name="default" socket-binding="http"
        proxy-address-forwarding="true" redirect-socket="proxy-https"/>
    ...
</subsystem>

$ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2

$ domain.sh --host-config=host-slave.xml
     -Djboss.bind.address=192.168.0.5
      -Djboss.bind.address.management=192.168.0.5
       -Djboss.domain.master.address=192.168.0.2

典型的集群部署包括负载均衡器（逆向代理）以及 2 个或更多红帽在专用网络上的 Red Hat Single Sign-On 服务器。出于性能考虑，如果负载均衡器将所有与特定浏览器会话相关的请求转发到同一个红帽单点登录后端节点，这可能很有用。

其原因在于，Red Hat Single Sign-On 在涵盖保存与当前身份验证会话和用户会话相关的数据的情况下，使用 Infinispan 分布式缓存。默认情况下，Infinispan 分布式缓存配置为一个所有者。这意味着，特定会话只保存在一个集群节点中，另一个节点需要远程查找会话（如果它们想要访问它）。

例如，如果 ID 为 123 的验证会话保存在 node1 上的 Infinispan 缓存中，而 node2 需要查找此会话，则需要通过网络将请求发送到 node1，以返回特定会话实体。

如果特定会话实体始终在本地可用，则可使用粘性会话的帮助。带有公共前端负载均衡器的集群环境中的工作流和两个后端红帽单点登录节点可能如下所示：

此时，如果负载均衡器将所有下一个请求转发到 node2，这是具有 ID 123 的身份验证会话的所有者，因此 Infinispan 可以在本地查询该会话时很有用。身份验证完成后，身份验证会话将转换为用户会话，该会话也将保存在 node2 上，因为它具有相同的 ID 123。

集群设置不强制使用粘性会话，但出于上述原因，性能很好。您需要通过 AUTH_SESSION_ID cookie 配置负载均衡器来粘性。具体操作方法取决于您的负载均衡器。

建议您在 Red Hat Single Sign-On side 中在启动时使用系统属性 jboss.node.name，其值对应于您的路由名称。例如，-Djboss.node.name=node1 将使用 node1 来识别路由。此路由将由 Infinispan 缓存使用，当节点是特定密钥的所有者时，将附加到 AUTH_SESSION_ID cookie。以下是使用这个系统属性启动命令的示例：

cd $RHSSO_NODE1
./standalone.sh -c standalone-ha.xml -Djboss.socket.binding.port-offset=100 -Djboss.node.name=node1

通常，在生产环境下，路由名称应使用与后端主机相同的名称，但这不是必须的。您可以使用不同的路由名称。例如，如果您要将 Red Hat Single Sign-On 服务器的主机名隐藏到您的专用网络中。

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.2">
  ...
    <spi name="stickySessionEncoder">
        <provider name="infinispan" enabled="true">
            <properties>
                <property name="shouldAttachRoute" value="false"/>
            </properties>
        </provider>
    </spi>

</subsystem>

默认集群支持需要 IP 多播。多播是一个网络广播协议。这个协议在引导时用来发现和加入集群。它还用于广播有关复制的消息，以及红帽单点登录使用的分布式缓存无效。

红帽单点登录的集群子系统在 JGroups 堆栈上运行。在框中，集群的绑定地址绑定到私有网络接口，使用 127.0.0.1 作为默认 IP 地址。

当集群节点隔离在专用网络上时，需要访问专用网络才能加入集群或查看集群中的通信。另外，您还可以为集群通信启用身份验证和加密。只要您的专用网络安全，就不需要启用身份验证和加密。Red Hat Single Sign-On 在这两种情况下不会向集群中发送非常敏感信息。

如果要启用集群通信的验证和加密，请参阅 JBoss EAP 配置指南中的 保护集群。https://access.redhat.com/documentation/zh-cn/red_hat_jboss_enterprise_application_platform/7.4/html-single/configuration_guide/configuring_high_availability#securing_cluster

Red Hat Single Sign-On 集群节点可以同时引导。当 Red Hat Single Sign-On 服务器实例引导它时，可能需要进行一些数据库迁移、导入或首次初始化。DB 锁定用于在集群节点同时引导时防止启动操作相互冲突。

默认情况下，此锁定的最大超时时间为 900 秒。如果某个节点在这个锁定中等待超过超时，它将无法引导。通常，您通常不需要增加/减少默认值，但只需将它在 standalone. xml、standalone -ha.xml 或 domain.xml 文件中配置它时。这个文件的位置取决于您的 操作模式。

<spi name="dblock">
    <provider name="jpa" enabled="true">
        <properties>
            <property name="lockWaitTimeout" value="900"/>
        </properties>
    </provider>
</spi>

在集群中引导 Red Hat Single Sign-On 取决于您的 操作模式

$ bin/standalone.sh --server-config=standalone-ha.xml

$ bin/domain.sh --host-config=host-master.xml
$ bin/domain.sh --host-config=host-slave.xml

您可能需要使用附加参数或系统属性。例如，绑定主机的参数 -b 或系统属性 jboss.node.name 指定路由的名称，如 Sticky Sessions 部分所述。

为红帽单点登录配置了多个不同缓存。有一个域缓存，它保存有关安全应用程序、常规安全数据和配置选项的信息。还有一个用户缓存，其中包含用户元数据。两个缓存都默认为 10000 个条目，并使用至少最近使用的驱除策略。它们也都与用于控制集群设置中驱除的对象修订缓存相关联。此缓存隐式创建，其配置的大小会两倍。同样适用于包含授权数据 的授权 缓存。密钥 缓存保存有关外部密钥的数据，不需要具有专用修订版本缓存。相反，它明确声明了 过期，因此这些密钥会定期过期，并强制定期从外部客户端或身份提供程序下载。

这些缓存的驱除策略和最大条目可以在 standalone. xml、standalone -ha.xml 或 domain.xml 中配置，具体取决于您的 操作模式。在配置文件中，有 infinispan 子系统的部分，其类似于：

<subsystem xmlns="urn:jboss:domain:infinispan:12.0">
    <cache-container name="keycloak">
        <local-cache name="realms">
            <object-memory size="10000"/>
        </local-cache>
        <local-cache name="users">
            <object-memory size="10000"/>
        </local-cache>
        ...
        <local-cache name="keys">
            <object-memory size="1000"/>
            <expiration max-idle="3600000"/>
        </local-cache>
        ...
    </cache-container>

要限制或扩展允许条目的数量，只需添加或编辑 对象 元素或特定缓存配置的 过期 元素。

此外，也有单独的缓存 会话、客户端会话、离线 会话、offlineClientSessions、loginFailures 和 actionTokens。这些缓存在集群环境中分布，默认大小不绑定。如果将它们绑定，则可能会丢失一些会话。Red Hat Single Sign-On 本身在内部清除过期的会话，以避免在不限制的情况下增加这些缓存的大小。如果因为大量会话而导致内存问题，您可以尝试：

有一个额外的复制缓存 work，它主要用于在集群节点之间发送消息；默认情况下也未绑定。但是，这个缓存不应该造成任何内存问题，因为这个缓存中的条目非常短。

有如 会话、身份验证会话、离线会话、login Failure 和一些其他缓存（更多详情 第 10.1 节 “驱除和过期” ）等缓存，在使用集群时被配置为分布式缓存。条目不会复制到每一个节点，而是选择一个或多个节点作为该数据的所有者。如果节点不是特定缓存条目的所有者，它会查询集群来获取它。这意味着，故障转移是什么，如果所有拥有数据的节点停机，则数据会永久丢失。默认情况下，Red Hat Single Sign-On 仅指定一个数据所有者。因此，如果一个节点停机，数据就会丢失。这通常意味着用户将被注销，并且必须再次登录。

您可以通过更改 distributed-cache 声明中的 owners 属性来更改复制数据的节点数量。

<subsystem xmlns="urn:jboss:domain:infinispan:12.0">
   <cache-container name="keycloak">
       <distributed-cache name="sessions" owners="2"/>
...

在这里，我们更改了它，因此至少两个节点都会复制一个特定的用户登录会话。

您可以禁用 realm 或 user cache。

您可以清除域缓存、用户缓存或外部公钥。

要安装 Red Hat Single Sign-On Operator，您可以使用：

您可以通过创建 Keycloak 自定义资源，使用 Operator 自动安装 Red Hat Single Sign-On。当您使用自定义资源安装 Red Hat Single Sign-On 时，您可以创建此处描述的组件和服务，并在下图所示显示。

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: example-sso
  labels:
    app: sso
spec:
  instances: 1
  externalAccess:
    enabled: True

$ oc describe keycloak <CR-name>

Name:         example-keycloak
Namespace:    keycloak
Labels:       app=sso
Annotations:  <none>
API Version:  keycloak.org/v1alpha1
Kind:         Keycloak
Spec:
  External Access:
    Enabled:  true
  Instances:  1
Status:
  Credential Secret:  credential-example-keycloak
  Internal URL:       https://<External URL to the deployed instance>
  Message:
  Phase:              reconciling
  Ready:              true
  Secondary Resources:
    Deployment:
      keycloak-postgresql
    Persistent Volume Claim:
      keycloak-postgresql-claim
    Prometheus Rule:
      keycloak
    Route:
      keycloak
    Secret:
      credential-example-keycloak
      keycloak-db-secret
    Service:
      keycloak-postgresql
      keycloak
      keycloak-discovery
    Service Monitor:
      keycloak
    Stateful Set:
      keycloak
  Version:
Events:

您可以使用 Operator 在 Red Hat Single Sign-On 中创建由自定义资源定义的域。您可以在 YAML 文件中定义 realm 自定义资源的属性。

apiVersion: keycloak.org/v1alpha1
kind: KeycloakRealm
metadata:
  name: test
  labels:
    app: sso
spec:
  realm:
    id: "basic"
    realm: "basic"
    enabled: True
    displayName: "Basic Realm"
  instanceSelector:
    matchLabels:
      app: sso

$ oc describe keycloak <CR-name>

Name:         example-keycloakrealm
Namespace:    keycloak
Labels:       app=sso
Annotations:  <none>
API Version:  keycloak.org/v1alpha1
Kind:         KeycloakRealm
Metadata:
  Creation Timestamp:  2019-12-03T09:46:02Z
  Finalizers:
    realm.cleanup
  Generation:        1
  Resource Version:  804596
  Self Link:         /apis/keycloak.org/v1alpha1/namespaces/keycloak/keycloakrealms/example-keycloakrealm
  UID:               b7b2f883-15b1-11ea-91e6-02cb885627a6
Spec:
  Instance Selector:
    Match Labels:
      App: sso
  Realm:
    Display Name:  Basic Realm
    Enabled:       true
    Id:            basic
    Realm:         basic
Status:
  Login URL:
  Message:
  Phase:      reconciling
  Ready:      true
Events:       <none>

其他资源

您可以使用 Operator 在 Red Hat Single Sign-On 中创建由自定义资源定义的客户端。您可以在 YAML 文件中定义域的属性。

apiVersion: keycloak.org/v1alpha1
kind: KeycloakClient
metadata:
  name: example-client
  labels:
    app: sso
spec:
  realmSelector:
     matchLabels:
      app: <matching labels for KeycloakRealm custom resource>
  client:
    # auto-generated if not supplied
    #id: 123
    clientId: client-secret
    secret: client-secret
    # ...
    # other properties of Keycloak Client

apiVersion: v1
data:
  CLIENT_ID: <base64 encoded Client ID>
  CLIENT_SECRET: <base64 encoded Client Secret>
kind: Secret

Operator 处理自定义资源后，使用以下命令查看状态：

$ oc describe keycloak <CR-name>

Name:         client-secret
Namespace:    keycloak
Labels:       app=sso
API Version:  keycloak.org/v1alpha1
Kind:         KeycloakClient
Spec:
  Client:
    Client Authenticator Type:     client-secret
    Client Id:                     client-secret
    Id:                            keycloak-client-secret
  Realm Selector:
    Match Labels:
      App:  sso
Status:
  Message:
  Phase:    reconciling
  Ready:    true
  Secondary Resources:
    Secret:
      keycloak-client-secret-client-secret
Events:  <none>

您可以使用 Operator 在 Red Hat Single Sign-On 中创建由自定义资源定义的用户。您可以在 YAML 文件中定义用户自定义资源的属性。

apiVersion: keycloak.org/v1alpha1
kind: KeycloakUser
metadata:
  name: example-user
spec:
  user:
    username: "realm_user"
    firstName: "John"
    lastName: "Doe"
    email: "user@example.com"
    enabled: True
    emailVerified: False
    credentials:
      - type: "password"
        value: "12345"
    realmRoles:
      - "offline_access"
    clientRoles:
      account:
        - "manage-account"
      realm-management:
        - "manage-users"
  realmSelector:
    matchLabels:
      app: sso

例如：

kind: Secret
apiVersion: v1
data:
  password: <base64 encoded password>
  username: <base64 encoded username>
type: Opaque

Operator 处理自定义资源后，使用以下命令查看状态：

$ oc describe keycloak <CR-name>

Name:         example-realm-user
Namespace:    keycloak
Labels:       app=sso
API Version:  keycloak.org/v1alpha1
Kind:         KeycloakUser
Spec:
  Realm Selector:
    Match Labels:
      App: sso
  User:
    Email:           realm_user@redhat.com
    Credentials:
      Type:          password
      Value:         <user password>
    Email Verified:  false
    Enabled:         true
    First Name:      John
    Last Name:       Doe
    Username:        realm_user
Status:
  Message:
  Phase:    reconciled
Events:     <none>

您可以通过创建一个 keycloak-db-secret YAML 文件并将 Keycloak CR externalDatabase 属性设置为启用，来使用 Operator 连接到外部 PostgreSQL 数据库。请注意，数值采用 Base64 编码。

apiVersion: v1
kind: Secret
metadata:
    name: keycloak-db-secret
    namespace: keycloak
stringData:
    POSTGRES_DATABASE: <Database Name>
    POSTGRES_EXTERNAL_ADDRESS: <External Database URL (resolvable by K8s)>
    POSTGRES_EXTERNAL_PORT: <External Database Port>
    POSTGRES_PASSWORD: <Database Password>
    # Required for AWS Backup functionality
    POSTGRES_SUPERUSER: "true"
    POSTGRES_USERNAME: <Database Username>
    SSLMODE: <TLS configuration for the Database connection>
type: Opaque

以下属性设置数据库的主机名或 IP 地址和端口。

其他属性的工作方式与托管或外部数据库相同。按照如下所示设置它们：

启用 SSLMODE 后，Operator 会搜索名为 keycloak-db-ssl-cert-secret 的 secret，其中包含 PostgreSQL 数据库使用的 root.crt。创建 secret 是可选的，只有在您要验证数据库的证书时使用 secret（例如 SSLMODE: verify-ca）。下面是一个示例：

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-ssl-cert-secret
  namespace: keycloak
type: Opaque
data:
  root.crt: {root.crt base64}

Operator 将创建名为 keycloak-postgresql 的 Service。该服务由 Operator 配置，以根据 POSTGRES_EXTERNAL_ADDRESS 的内容公开外部数据库。Red Hat Single Sign-On 使用此服务连接到数据库，这意味着它不直接连接到数据库，而是通过这个服务。

Keycloak 自定义资源需要更新才能启用外部数据库支持。

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  labels:
      app: sso
  name: example-keycloak
  namespace: keycloak
spec:
  externalDatabase:
    enabled: true
  instances: 1

此运算符也可用于部分管理外部红帽单点登录实例。在当前状态中，它将只能创建客户端。

要做到这一点，您需要创建 Keycloak 和 KeycloakRealm CRD 的非受管版本以用于目标和配置。

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: external-ref
  labels:
    app: external-sso
spec:
  unmanaged: true
  external:
    enabled: true
    url: https://some.external.url

为了根据这个 keycloak 进行身份验证，Operator 通过带有 凭证的 CRD 名称来推断来自 CRD 的 secret 名称。

apiVersion: v1
kind: Secret
metadata:
  name: credential-external-ref
type: Opaque
data:
  ADMIN_USERNAME: YWRtaW4=
  ADMIN_PASSWORD: cGFzcw==

apiVersion: keycloak.org/v1alpha1
kind: KeycloakRealm
metadata:
  name: external-realm
  labels:
    app: external-sso
spec:
  unmanaged: true
  realm:
    id: "basic"
    realm: "basic"
  instanceSelector:
    matchLabels:
      app: external-sso

现在，您可以照常使用客户端中的域引用，它将在外部红帽单点登录实例上创建客户端。

您可以使用 Operator 来调度由自定义资源定义的数据库的自动备份。自定义资源会触发备份作业并报告其状态。

您可以使用 Operator 创建对本地持久性卷执行一次性备份的备份作业。

apiVersion: keycloak.org/v1alpha1
kind: KeycloakBackup
metadata:
  name: test-backup

您可以使用 Operator 安装扩展功能，并适用于您的公司或组织所需的扩展。扩展或主题可以是 Red Hat Single Sign-On 都可以使用的任何内容。例如，您可以添加指标扩展。您可以在 Keycloak 自定义资源中添加扩展或主题。

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  labels:
   app: sso
spec:
  instances: 1
  extensions:
   - <url_for_extension_or_theme>
  externalAccess:
    enabled: True

您可以像任何其他扩展一样打包和部署它们。如需更多信息，请参阅 部署主题 手动条目。

Operator 下载扩展名或主题并安装它。

在创建自定义请求后，您可以使用 oc 命令编辑它或删除。

例如，要编辑名为 test-realm 的域自定义请求，请使用以下命令：

$ oc edit test-realm

此时会打开一个窗口，您可以在其中进行更改。

您可以配置 Operator 如何执行红帽单点登录升级。您可以从以下升级策略中选择。

apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  name: example-keycloak
  labels:
   app: sso
spec:
  instances: 2
  migration:
    strategy: recreate
    backups:
      enabled: True
  externalAccess:
    enabled: True