服务器安装和配置指南

Red Hat Single Sign-On 7.2

用于 Red Hat Single Sign-On 7.2

Red Hat Customer Content Services

摘要

本指南包含安装和配置 Red Hat Single Sign-On 7.2 的信息

第 1 章 指南概述

本指南的目的是完成第一次引导 Red Hat Single Sign-On 服务器前需要完成的步骤。如果您只想测试驱动器驱动器 Red Hat Single Sign-On,它只会耗尽其自身的嵌入式和本地数据库。对于要在生产中运行的实际部署,您需要确定如何在运行时管理服务器配置(standalone 或 domain mode),为 Red Hat Single Sign-On 存储配置共享数据库,设置加密和 HTTPS,最后设置 Red Hat Single Sign-On 在集群中运行。本指南介绍了任何预引导决策和设置的各个方面,您必须在部署服务器之前完成。

特别注意的是 Red Hat Single Sign-On 派生自 JBoss EAP Application Server。配置 Red Hat Single Sign-On 的许多方面会围绕 JBoss EAP 配置元素而解决。通常,如果想要详细介绍,本指南会将您定向到手册之外的文档。

第 2 章 安装

您可以通过下载 ZIP 文件和解压缩或使用 RPM 来安装 Red Hat Single Sign-On。本章回顾了系统要求以及目录结构。

2.1. 系统要求

以下是运行 Red Hat Single Sign-On 身份验证服务器的要求:

  • 可以在运行 Java 的任何操作系统上运行
  • Java 8 JDK
  • zip 或 gzip 和 tar
  • 至少 512M RAM
  • 至少 1G 的磁盘空间
  • 共享外部数据库,如 Postgres、MySql、Oracle 等。如果要在集群中运行,Red Hat Single Sign-On 需要外部共享数据库。如需更多信息,请参阅本指南的 数据库配置 部分。
  • 如果要在集群中运行,在您的机器上支持网络多播。Red Hat Single Sign-On 可以在没有多播的情况下进行集群,但这需要大量配置更改。如需更多信息 请参阅本指南的集群部分。
  • 在 Linux 上,建议使用 /dev/urandom 作为随机数据源,以防止因为缺少可用的熵而导致 Red Hat Single Sign-On 挂起,除非安全策略强制使用 /dev/random。要在 Oracle JDK 8 和 OpenJDK 8 上达到此目的,请在启动时将 java.security.egd 系统属性设置为 file:/dev/urandom

2.2. 从 ZIP 文件安装 RH-SSO

Red Hat Single Sign-On 服务器包含在一个分发文件中:rh-sso-7.2.7.GA.zip.gz。

rh-sso-7.2.7.GA.zip.gz 存档是仅服务器分发。它只包含运行 Red Hat Single Sign-On Server 的脚本和二进制文件。

要解包这些文件,请运行 unzipgunzip 工具。

2.3. 从 RPM 安装 RH-SSO

注意

使用 Red Hat Enterprise Linux 7,术语频道被替换为存储库。在这些说明中,只使用存储库术语。

您必须订阅 JBoss EAP 7.1 和 RH-SSO 7.2 存储库,然后才能从 RPM 安装 RH-SSO。

注意

您无法继续接收到 EAP RPM 的升级,但停止接收 RH-SSO 的更新。

2.3.1. 订阅 JBoss EAP 7.1 存储库

先决条件

  1. 使用 Red Hat Subscription Manager 验证您的 Red Hat Enterprise Linux 系统已注册到您的帐户。如需更多信息,请参阅 Red Hat Subscription Management 文档
  2. 如果您已经订阅了另一个 JBoss EAP 存储库,您必须首先取消订阅该存储库。

使用 Red Hat Subscription Manager,使用以下命令订阅 JBoss EAP 7.1 存储库。根据您的 Red Hat Enterprise Linux 版本,将 <RHEL_VERSION> 替换为 6 或 7。

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

2.3.2. 订阅 RH-SSO 7.2 存储库并安装 RH-SSO 7.2

先决条件

  1. 使用 Red Hat Subscription Manager 验证您的 Red Hat Enterprise Linux 系统已注册到您的帐户。如需更多信息,请参阅 Red Hat Subscription Management 文档
  2. 确保您已订阅了 JBoss EAP 7.1 存储库。如需更多信息,请参阅订阅 JBoss EAP 7.1 存储库

要订阅 RH-SSO 7.2 存储库并安装 RH-SSO 7.2,请完成以下步骤:

  1. 使用 Red Hat Subscription Manager,使用以下命令订阅 RH-SSO 7.2 存储库。根据您的 Red Hat Enterprise Linux 版本,将 <RHEL_VERSION> 替换为 6 或 7。

    subscription-manager repos --enable=rh-sso-7.2-for-rhel-<RHEL-VERSION>-server-rpms
  2. 使用以下命令,从您订阅的 RH-SSO 7.2 存储库安装 RH-SSO:

    yum groupinstall rh-sso7

您的安装已完成。RPM 安装的默认 RH-SSO_HOME 路径为 /opt/rh/rh-sso7/root/usr/share/keycloak。

2.4. 分发目录结构

本章介绍了服务器分发的目录结构。

分发目录结构

distribution

我们来检查某些目录的目的:

bin/
它包含引导服务器或在服务器上执行某些其他管理操作的各种脚本。
domain/
它包含在 域模式下运行 Red Hat Single Sign-On 时的配置文件和工作目录。
modules/
这些是服务器使用的所有 Java 库。
standalone/
它包含 以独立模式运行 Red Hat Single Sign-On 时的配置文件和工作目录。
themes/
此目录包含所有 html、样式表、Javascript 文件和镜像,用于显示服务器显示的任何 UI 屏幕。您可以在此处修改现有主题或创建自己的主题。有关此 内容的更多信息,请参阅服务器开发人员指南

第 3 章 选择操作模式

在生产环境中部署 Red Hat Single Sign-On 之前,您需要决定您要使用的工作模式。是否在集群中运行 Red Hat Single Sign-On?您是否想要通过集中的方式管理服务器配置?您选择的操作模式会影响您配置数据库、配置缓存甚至如何引导服务器。

提示

Red Hat Single Sign-On 基于 JBoss EAP Application Server 构建。本指南仅了解在特定模式中部署的基础知识。如果您需要有关此特定信息,最好是 JBoss EAP 配置指南

3.1. 独立模式

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

3.1.1. 独立启动脚本

在独立模式中运行服务器时,您需要运行特定的脚本来根据您的操作系统引导服务器。这些脚本位于服务器分发的 bin/ 目录中。

独立启动脚本

standalone boot files

引导服务器:

Linux/Unix

$ .../bin/standalone.sh

Windows

> ...\bin\standalone.bat

3.1.2. 独立配置

本指南批量指导您如何配置 Red Hat Single Sign-On 的基础架构级别方面。这些方面是在特定于 Red Hat Single Sign-On 的一个应用程序服务器的配置文件中进行配置的。在独立操作模式中,此文件在 …​/standalone/configuration/standalone.xml 中。此文件还用于配置特定于 Red Hat Single Sign-On 组件的非基础架构级别操作。

独立配置文件

standalone config file

警告

在服务器运行时,您对此文件所做的任何更改都不会生效,甚至可能被服务器覆盖。取而代之,请使用命令行脚本或 JBoss EAP 的 Web 控制台。如需更多信息,请参阅 JBoss EAP 配置指南

3.2. 独立集群模式

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

3.2.1. 独立集群配置

发行版主要有一个预配置的应用服务器配置文件,可在集群内运行。它具有所有特定的基础架构设置,用于网络、数据库、缓存和发现。此文件位于 …​/standalone/configuration/standalone-ha.xml 中。此配置中缺少一些内容。您无法在没有配置共享数据库连接的情况下在集群中运行 Red Hat Single Sign-On。您还需要在集群前面部署某种类型的负载均衡器。本指南 的集群 和数据库 部分将指导您完成这些事项。

独立 HA 配置

standalone ha config file

警告

在服务器运行时,您对此文件所做的任何更改都不会生效,甚至可能被服务器覆盖。而是使用命令行脚本或 JBoss EAP 的 Web 控制台。如需更多信息,请参阅 JBoss EAP 配置指南

3.2.2. 独立集群启动脚本

您可以使用相同的引导脚本来启动 Red Hat Single Sign-On,如独立模式下操作。区别在于,您传递了一个额外的标记以指向 HA 配置文件。

独立集群启动脚本

standalone boot files

引导服务器:

Linux/Unix

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

Windows

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

3.3. 域集群模式

域模式是集中管理和发布服务器的配置的一种方式。

以标准模式运行集群可能会快速变为聚合,因为集群大小会增大。每次需要更改配置更改时,您都必须在集群的每个节点中执行它。域模式通过提供存储和发布配置的中心来解决此问题。设置可能非常复杂,但在最后需要它。此功能内置在 Red Hat Single Sign-On 派生的 JBoss EAP 应用服务器中。

注意

本指南将介绍域模式的基本知识。应从 JBoss EAP 配置指南 中获取集群中如何设置域模式的详细步骤。

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

域控制器
域控制器是一种负责存储、管理和发布集群中每个节点的常规配置的进程。此过程是从哪些节点获取其配置的核心点。
主机控制器
主机控制器负责管理特定计算机上的服务器实例。您可以将其配置为运行一个或多个服务器实例。域控制器也可以与每台机器上的主机控制器交互,以管理集群。为减少正在运行的进程的数量,域控制器在其上运行的计算机上也充当主机控制器。
域配置文件
域配置文件是一组指定的配置,供服务器用于从中启动。域控制器可以定义由不同服务器使用的多个域配置文件。
服务器组
服务器组是服务器的集合。它们作为一个进行管理和配置。您可以为服务器组分配域配置文件,并且该组中的每个服务都将使用该域配置文件作为其配置。

在域模式中,主控节点上启动域控制器。集群的配置驻留在域控制器中。接下来,在集群中的每个机器上启动主机控制器。每个主机控制器部署配置指定在该计算机上启动多少个 Red Hat Single Sign-On 服务器实例。当主机控制器启动时,它会启动尽可能多的 Red Hat Single Sign-On 服务器实例。这些服务器实例从域控制器拉取其配置。

3.3.1. 域配置

本指南中的各种其他章节将指导您配置数据库、HTTP 网络连接、缓存和其他基础架构相关事项等各个方面。虽然独立模式使用 standalone.xml 文件来配置这些内容,但域模式使用 …​/domain/configuration/domain.xml 配置文件。这是定义 Red Hat Single Sign-On 服务器的域配置文件和服务器组的位置。

domain.xml

domain file

警告

您在域控制器运行时对此文件所做的任何更改都不会生效,甚至可能被服务器覆盖。而是使用命令行脚本或 JBoss EAP 的 Web 控制台。如需更多信息,请参阅 JBoss EAP 配置指南

让我们来看看这个 domain.xml 文件的一些方面。auth-server-standaloneauth-server-clustered 配置集 XML 块是您要做出大量配置决策的位置。您要在此处配置诸如网络连接、缓存和数据库连接等内容。

auth-server 配置集

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

auth-server-standalone 配置集是一个非集群的设置。auth-server-clustered 配置集是集群设置。

如果您进一步向下滚动,您将看到定义了各种 socket-binding-groups

socket-binding-groups

    <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 softare or hardare based one -->
        <socket-binding-group name="load-balancer-sockets" default-interface="public">
           ...
        </socket-binding-group>
    </socket-binding-groups>

此配置定义了与每个 Red Hat Single Sign-On 服务器实例一起打开的各种连接器的默认端口映射。包含 ${…​} 的任何值都是可在命令行中使用 -D 开关覆盖的值,即.

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

Red Hat Single Sign-On 的服务器组的定义位于 server-groups XML 块中。它指定使用的域配置文件(默认),以及主机控制器引导实例时 Java 虚拟机的一些默认引导参数。它还将 socket-binding-group 绑定到服务器组。

服务器组

    <server-groups>
        <!-- load-balancer-group should be removed in production systems and replaced with a better softare or hardare 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>

3.3.2. 主机控制器配置

Red Hat Single Sign-On 附带两个主机控制器配置文件,它们位于 …​/domain/configuration/ 目录中: host-master.xmlhost-slave.xmlhost-master.xml 配置为引导域控制器、负载均衡器和一个 Red Hat Single Sign-On 服务器实例。host-slave.xml 配置为与域控制器通信并引导一个 Red Hat Single Sign-On 服务器实例。

注意

负载均衡器不是所需的服务。它已存在,以便您可以在开发机器上轻松测试驱动集群。虽然在生产环境中可用,但如果您有您要使用的不同硬件或软件负载均衡器,您可以选择替换它。

主机控制器配置

host files

要禁用负载均衡器服务器实例,请编辑 host-master.xml 并注释掉或删除 "load-balancer" 条目。

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

关于此文件的另一个值得注意的是,身份验证服务器实例的声明。它有一个 port-offset 设置。domain.xml socket-binding-group 或服务器组中定义的任何网络端口都会向其中添加 port-offset 值。在这个示例域设置中,我们这样做,因此负载均衡器服务器打开的端口不会与启动的身份验证服务器实例冲突。

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

3.3.3. 服务器实例工作目录

主机文件中定义的每个 Red Hat Single Sign-On 服务器实例都会在 …​/domain/servers/{SERVER NAME} 下创建一个工作目录。可以有一些其他配置,以及服务器实例需要或创建任何临时、日志或数据文件。这些服务器目录的结构最终像任何其他 JBoss EAP 引导服务器一样。

工作目录

domain server dir

3.3.4. 域启动脚本

在域模式下运行服务器时,您需要运行特定的脚本来根据您的操作系统引导服务器。这些脚本位于服务器分发的 bin/ 目录中。

域启动脚本

domain boot files

引导服务器:

Linux/Unix

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

Windows

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

运行引导脚本时,您需要传递要通过 --host-config 参数使用的主机控制配置文件。

3.3.5. 集群域示例

您可以使用开箱即用的 domain.xml 配置测试驱动器集群。这个示例域旨在在一台机器上运行并引导:

  • 域控制器
  • HTTP 负载均衡器
  • 2 Red Hat Single Sign-On 服务器实例

要在两台机器上模拟运行集群,您将运行 domain.sh 脚本两次来启动两个单独的主机控制器。第一个是 master 主机控制器,它将启动域控制器、HTTP 负载均衡器和一个 Red Hat Single Sign-On 身份验证服务器实例。第二个是从属主机控制器,仅启动身份验证服务器实例。

3.3.5.1. 设置到域控制器的连接

在引导前,您必须配置 slave 主机控制器,以便它可以安全地与域控制器通信。如果不执行此操作,则从主机将无法从域控制器获取集中式配置。要设置安全连接,您必须创建一个服务器 admin 用户和在主设备和从设备之间共享的机密。您可以通过运行 …​/bin/add-user.sh 脚本来完成此操作。

当您运行脚本时,选择 Management User 并回答 yes,当它询问新用户是否将用于一个 AS 进程连接到另一个进程时,请回答 yes。这将生成一个 secret,您需要剪切并粘贴到 …​/domain/configuration/host-slave.xml 文件中。

添加 App Server Admin

$ add-user.sh
 What type of user do you wish to add?
  a) Management User (mgmt-users.properties)
  b) Application User (application-users.properties)
 (a): a
 Enter the details of the new user to add.
 Using realm 'ManagementRealm' as discovered from the existing property files.
 Username : admin
 Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file.
  - The password should not be one of the following restricted values {root, admin, administrator}
  - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
  - The password should be different from the username
 Password :
 Re-enter Password :
 What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]:
 About to add user 'admin' for realm 'ManagementRealm'
 Is this correct yes/no? yes
 Added user 'admin' to file '/.../standalone/configuration/mgmt-users.properties'
 Added user 'admin' to file '/.../domain/configuration/mgmt-users.properties'
 Added user 'admin' with groups to file '/.../standalone/configuration/mgmt-groups.properties'
 Added user 'admin' with groups to file '/.../domain/configuration/mgmt-groups.properties'
 Is this new user going to be used for one AS process to connect to another AS process?
 e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
 yes/no? yes
 To represent the user add the following to the server-identities definition <secret value="bWdtdDEyMyE=" />

注意

add-user.sh 不将用户添加到 Red Hat Single Sign-On 服务器,而是添加到底层 JBoss Enterprise Application Platform 中。以上脚本中使用和生成的凭证仅用于示例目的。请使用系统上生成的。

现在,将 secret 值剪切并粘贴到 …​/domain/configuration/host-slave.xml 文件中,如下所示:

     <management>
         <security-realms>
             <security-realm name="ManagementRealm">
                 <server-identities>
                     <secret value="bWdtdDEyMyE="/>
                 </server-identities>

3.3.5.2. 运行启动脚本

由于我们在一台开发机器上模拟两个节点集群,因此您将运行 启动脚本两次:

引导 master

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

引导从设备

$ domain.sh --host-config=host-slave.xml

要试用,请打开浏览器并访问 http://localhost:8080/auth

3.4. 跨数据中心复制模式

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

讨论了跨站点复制的新解决方案,并特别考虑红帽构建的 Keycloak (RHBK)的未来发行版本,这是将要引入的产品,而不是 Red Hat SSO 8。很快将提供更多详细信息。

第 4 章 管理子系统配置

Red Hat Single Sign-On 的低级别配置是通过编辑您发行版中的 standalone.xmlstandalone-ha.xmldomain.xml 文件来完成的。此文件的位置取决于您的 操作模式

虽然您可以在此处配置无限设置,但本节将专注于 keycloak-server 子系统的配置。无论您使用哪个配置文件,keycloak-server 子系统的配置都相同。

keycloak-server 子系统通常声明在文件末尾,如下所示:

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
   <web-context>auth</web-context>
   ...
</subsystem>

请注意,此子系统中的任何更改都不会生效,直到服务器重启为止。

4.1. 配置 SPI 供应商

每个配置设置的具体内容会在其他上下文中通过此设置进行讨论。但是,了解用于声明 SPI 提供程序上的设置的格式会很有用。

Red Hat Single Sign-On 是一个高度模块化的系统,具有很大的灵活性。有 50 多个服务提供商接口(SPI),您可以交换每个 SPI 的实现。SPI 的实现称为 提供程序

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

<spi name="myspi">
    <default-provider>myprovider</default-provider>
    <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 定义了两个 供应商default-provider 列为 myprovider。但是,最多是 SPI 来确定它如何处理此设置。有些 SPI 允许多个供应商,有些供应商不允许。因此 default-provider 可以帮助 SPI 选择。

另请注意,每个提供程序定义了自己的一组配置属性。以上两个提供程序都有一个名为 foo 的属性,只是一个共同的。

每个属性值的类型由供应商解释。但是,有一个例外。考虑 eventStore API 的 jpa 供应商:

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

我们看到该值以方括号开头和结束。这意味着该值将作为列表传递给提供程序。在本例中,系统将提供程序传递有两个元素值 EVENT1EVENT2 的列表。要向列表添加更多值,请仅使用逗号分隔每个 list 元素。不幸的是,您需要使用" 来转义各个列表元素周围的引号。

4.2. 启动 JBoss EAP CLI

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

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

Linux/Unix

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

Windows

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

这将使您进入类似如下的提示:

提示

[disconnected /]

如果要在正在运行的服务器上执行命令,您首先要执行 connect 命令。

连接

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

您可以考虑自己,"我不在任何用户名或密码中输入!"如果您在与正在运行的独立服务器或域控制器相同的机器上运行 jboss-cli,并且您的帐户有适当的文件权限,则不必在 admin 用户名和密码中设置或输入。如需了解如何使事情更加安全(如果使用该设置),请参阅 JBoss EAP 配置指南

4.3. CLI 嵌入式模式

如果这样做与单机服务器位于同一个机器上,并且您希望在服务器未激活时发出命令,您可以将服务器嵌入到 CLI 中,并在禁止传入的请求的特殊模式下进行更改。要做到这一点,首先使用您要更改的配置文件执行 embed 命令。

embed

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

4.4. CLI GUI 模式

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

在 GUI 模式中启动

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

注意:要连接到远程服务器,您也要传递 --connect 选项。详情请查看 --help 选项。

启动 GUI 模式后,您可能想要向下滚动以查找节点 subsystem=keycloak-server。如果右键点击节点,然后单击 Explore subsystem=keycloak-server,您将获得一个新标签页,其中仅显示 keycloak-server 子系统。

cli gui

4.5. CLI 脚本

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

turn-off-caching.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

4.6. CLI Recipes

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

对于独立,这只是:

** = /subsystem=keycloak-server

对于域模式,这意味着如下:

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

4.6.1. 更改服务器的 Web 上下文

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

4.6.2. 设置全局默认主题

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

4.6.3. 添加新 SPI 和供应商

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

4.6.4. 禁用供应商

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

4.6.5. 更改 SPI 的默认供应商

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

4.6.6. 配置 dblock SPI

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

4.6.7. 为供应商添加或更改单个属性值

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

4.6.8. 从供应商中删除单个属性

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

4.6.9. 对类型 List的 provider 属性设置值

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

第 5 章 配置集

Red Hat Single Sign-On 有两个配置集:产品和预览。产品配置集默认为启用,它会禁用一些技术预览功能。要启用功能,您可以切换到 preview 配置集或启用单个功能。

启用 preview 配置集启动服务器:

bin/standalone.sh|bat -Dkeycloak.profile=preview

您可以通过在域模式中为 server-one 创建文件 standalone/configuration/profile.properties (或 domain/servers/server-one/configuration/profile.properties )来永久设置。在文件中添加以下内容:

profile=preview

可以启用和禁用的功能有:

Name描述默认启用

授权

授权服务

docker

Docker Registry 协议

模拟

管理员能够模拟用户

script

使用 JavaScript 编写自定义验证器

要启用特定的功能,请使用以下内容启动服务器:

bin/standalone.sh|bat -Dkeycloak.profile.feature.<feature name>=enabled

例如,启用 Docker 使用 -Dkeycloak.profile.feature.docker=enabled

要禁用特定的功能,请使用以下内容启动服务器:

bin/standalone.sh|bat -Dkeycloak.profile.feature.<feature name>=disabled

例如,禁用 Impersonation use -Dkeycloak.profile.feature.impersonation=disabled

您可以通过添加以下内容在 profile.properties 文件中永久设置:

feature.impersonation=disabled

要在不启用完整预览配置集的情况下启用特定功能,您可以使用以下方法启动服务器:

bin/standalone.sh|bat -Dkeycloak.profile.feature.<feature name>=enabled`

例如,要启用授权服务,请使用 -Dkeycloak.profile.feature.authorization=enabled

您可以通过添加以下内容在 profile.properties 文件中永久设置:

feature.authorization=enabled

第 6 章 关系的数据库设置

Red Hat Single Sign-On 附带自己的嵌入式基于 Java 的关系数据库,称为 H2。这是 Red Hat Single Sign-On 将用来持久保留数据的默认数据库,实际上仅存在,以便您可以开箱即用地运行身份验证服务器。我们强烈建议您将其替换为更多生产就绪的外部数据库。在高并发情况下,H2 数据库无法非常可行,且不能在集群中使用。本章的目的是向您展示如何将 Red Hat Single Sign-On 连接到更成熟的数据库。

Red Hat Single Sign-On 使用两种层次技术来持久保留其关系数据。底层技术是 JDBC。JDBC 是一个 Java API,用于连接 RDBMS。每个数据库类型都有不同的 JDBC 驱动程序,这些驱动程序由您的数据库供应商提供。本章讨论了如何配置 Red Hat Single Sign-On 以使用这些特定供应商的驱动程序之一。

用于持久性的顶级技术是 Hibernate JPA。这是关系映射 API 的对象,用于将 Java 对象映射到关系数据。Red Hat Single Sign-On 的大多数部署都不会涉及 Hibernate 的配置方面,但我们将讨论当您遇到的意外情况时如何完成。

注意

JBoss EAP 配置指南中的 数据源配置一章中更加全面地介绍 数据源配置。

6.1. RDBMS 设置清单

以下是获取为 Red Hat Single Sign-On 配置 RDBMS 所需的步骤。

  1. 为您的数据库找到并下载 JDBC 驱动程序
  2. 将驱动程序 JAR 打包成模块,并将此模块安装到服务器中
  3. 在服务器的配置中声明 JDBC 驱动程序
  4. 修改数据源配置以使用数据库的 JDBC 驱动程序
  5. 修改数据源配置,以定义与数据库的连接参数

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

6.2. 打包 JDBC 驱动程序

查找并下载用于您的 RDBMS 的 JDBC 驱动程序 JAR。在使用这个驱动程序前,您必须将它打包到模块中,并将其安装到服务器中。模块定义加载到 Red Hat Single Sign-On 类路径中的 JAR,以及那些 JAR 在其他模块上具有的依赖项。它们易于设置。

在 Red Hat Single Sign-On 发行版本的 …​/modules/ 目录中,您需要创建一个目录结构来保存您的模块定义。其惯例使用 JDBC 驱动程序的 Java 软件包名称作为目录结构的名称。对于 PostgreSQL,创建目录 org/postgresql/main。将数据库驱动程序 JAR 复制到这个目录中,并在其中创建一个空的 module.xml 文件。

模块目录

db module

完成后,打开 module.xml 文件并创建以下 XML:

模块 XML

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">

    <resources>
        <resource-root path="postgresql-9.4.1212.jar"/>
    </resources>

    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

模块名称应与模块的目录结构匹配。因此,org/postgresql 映射到 org.postgresqlresource-root path 属性应指定驱动程序的 JAR 文件名。其余仅是任何 JDBC 驱动程序 JAR 存在的正常依赖项。

6.3. 声明和加载 JDBC 驱动程序

接下来,您需要做的是,将新打包的 JDBC 驱动程序声明成您的部署配置文件,使它加载并在服务器启动时可用。执行此操作的位置取决于您的 操作模式。如果您要以标准模式部署,请编辑 …​/standalone/configuration/standalone.xml。如果您要以标准集群模式部署,请编辑 …​/standalone/configuration/standalone-ha.xml。如果您要以域模式部署,请编辑 …​/domain/configuration/domain.xml。在域模式中,您需要确保编辑您要使用的配置集: auth-server-standaloneauth-server-clustered

在配置集中,搜索 datasources 子系统中的 驱动程序 XML 块。您应该会看到为 H2 JDBC 驱动程序声明的预定义驱动程序。这是您将为外部数据库声明 JDBC 驱动程序的位置。

JDBC 驱动程序

  <subsystem xmlns="urn:jboss:domain:datasources:4.0">
     <datasources>
       ...
       <drivers>
          <driver name="h2" module="com.h2database.h2">
              <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
          </driver>
       </drivers>
     </datasources>
  </subsystem>

驱动程序 XML 块中,您需要声明额外的 JDBC 驱动程序。它需要一个 名称,您可以选择该名称作为您想要的任何内容。您可以指定指向您之前为驱动程序 JAR 创建 的模块 软件包的模块属性。最后,您必须指定驱动程序的 Java 类。以下是在本章前面定义的模块示例中安装 PostgreSQL 驱动程序的示例。

声明您的 JDBC 驱动程序

  <subsystem xmlns="urn:jboss:domain:datasources:4.0">
     <datasources>
       ...
       <drivers>
          <driver name="postgresql" module="org.postgresql">
              <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
          </driver>
          <driver name="h2" module="com.h2database.h2">
              <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
          </driver>
       </drivers>
     </datasources>
  </subsystem>

6.4. 修改 Red Hat Single Sign-On 数据源

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

声明您的 JDBC 驱动程序

  <subsystem xmlns="urn:jboss:domain:datasources:4.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>

KeycloakDS 搜索数据源定义。首先需要修改 connection-url。您的供应商 JDBC 实施的文档应指定此连接 URL 值的格式。

接下来定义您要使用的 驱动程序。这是您在本章上一节中声明的 JDBC 驱动程序的逻辑名称。

每次您要执行事务时,都必须打开与数据库的新连接。为了补偿,数据源实施会维护一个开放连接池。max-pool-size 指定它将池的最大连接数。您可能希望根据系统的负载更改此值。

最后,在使用 PostgreSQL 时,您需要定义连接到数据库所需的数据库用户名和密码。您可能会担心在示例中是明文。有方法模糊处理,但这超出了本指南的范围。

注意

有关数据源功能的更多信息,请参阅 JBoss EAP 配置指南中的数据源配置章节https://access.redhat.com/documentation/zh-cn/red_hat_jboss_enterprise_application_platform/7.1/html-single/configuration_guide/#datasource_management

6.5. 数据库配置

此组件的配置可在您的发行版本中的 standalone.xmlstandalone-ha.xmldomain.xml 文件中找到。此文件的位置取决于您的 操作模式

数据库配置

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
    ...
    <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>

可能的配置选项有:

dataSource
dataSource 的 JNDI 名称
jta
指定数据源是否能够 JTA 的布尔值属性
driverDialect
数据库划分的值。在大多数情况下,您不需要将此属性指定为 dialect 将由 Hibernate 自动探测到。
initializeEmpty
如果为空,则初始化数据库。如果设置为 false,则必须手动初始化数据库。如果要手动将数据库设置 migrationStrategy 改为 manual,这会使用 SQL 命令创建文件来初始化数据库。默认值为 true。
migrationStrategy
用于迁移数据库的策略。有效值为 updatemanualvalidate。update 将自动迁移数据库架构。手动将使用 SQL 命令将所需的更改导出到文件,您可以手动对数据库执行。验证将简单检查数据库是最新的。
migrationExport
编写手动数据库初始化/迁移文件的路径。
showSql
指定 Hibernate 是否应在控制台中显示所有 SQL 命令(默认为false)。这非常详细!
formatSql
指定 Hibernate 是否应该格式化 SQL 命令(默认为 true)
globalStatsInterval
将记录 Hibernate 有关已执行 DB 查询和其他事务的全局统计信息。统计数据始终以指定间隔(以秒为单位)报告到服务器日志,并在每次报告后清除。
schema
指定要使用的数据库架构

6.6. 数据库的 Unicode 注意事项

Red Hat Single Sign-On 中的数据库模式仅在以下特殊字段中考虑 Unicode 字符串:

  • realms:显示名称、HTML 显示名称
  • 联邦供应商:显示名称
  • Users: username, given name, last name, attribute name and values
  • groups: name, attribute name 和 values
  • roles: name
  • 对象的描述

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

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

从技术上讲,对于 Unicode 支持所有字段的关键条件是数据库是否允许为 VARCHARCHAR 字段设置 Unicode 字符。如果是,则 Unicode 将存在的高可能性,通常以字段长度为代价。如果它只在 NVARCHARNCHAR 字段中支持 Unicode,则对所有文本字段的 Unicode 支持不太可能,因为 Keycloak 模式会广泛使用 VARCHARCHAR 字段。

6.6.1. Oracle 数据库

Unicode 字符可以被正确处理,提供了数据库在 VARCHARCHAR 字段中支持(例如,使用 AL32UTF8 字符集作为数据库字符集)创建的 Unicode 字符。JDBC 驱动程序不需要特殊设置。

如果数据库字符集不是 Unicode,则在特殊字段中使用 Unicode 字符,则需要配置 JDBC 驱动程序,并将连接属性 oracle.jdbc.defaultNChar 设置为 true。这可能是明智的,但并非严格必要,也要将 oracle.jdbc.convert.convertNcharLiterals 连接属性设为 true。这些属性可以设置为系统属性或连接属性。请注意,设置 oracle.jdbc.defaultNChar 可能会对性能造成负面影响。详情请查看 Oracle JDBC 驱动程序配置文档。

6.6.2. Microsoft SQL Server 数据库

Unicode 字符仅针对特殊字段正确处理。不需要特殊设置 JDBC 驱动程序或数据库。

6.6.3. IBM DB2 数据库

Unicode 字符为所有字段正确处理,长度缩减适用于非特殊字段。不需要特殊设置 JDBC 驱动程序或数据库。

6.6.4. MySQL 数据库

Unicode 字符可以被正确处理,提供了数据库是使用 CREATE DATABASE 命令的 VARCHARCHAR 字段中的 Unicode 支持创建的(例如,使用 utf8 字符集作为 MySQL 5.5 中设置的默认数据库字符)。请注意,utf8mb4 字符集无法正常工作,因为不同的存储要求被设置为 utf8 字符集 [1]).请注意,在这种情况下,非特殊字段的长度限制不适用,因为列创建为指定数量的字符数,而不是字节。如果数据库默认字符集不允许存储 Unicode,则只有特殊字段允许存储 Unicode 值。

在 JDBC 驱动程序设置一侧,需要将连接属性 characterEncoding=UTF-8 添加到 JDBC 连接设置中。

6.6.5. PostgreSQL 数据库

当数据库字符设置为 UTF8 时,支持 Unicode。在这种情况下,任何字段中都可以使用 Unicode 字符,非特殊字段没有减少字段长度。不需要特殊设置 JDBC 驱动程序。

第 7 章 网络设置

Red Hat Single Sign-On 可以开箱即用,但有一些网络限制。对于一个,所有网络端点都绑定到 localhost,因此 auth 服务器实际上仅在一台本地计算机上可用。对于基于 HTTP 的连接,不使用默认端口,如 80 和 443。HTTPS/SSL 没有配置开箱即用,如果没有它,Red Hat Single Sign-On 有很多安全漏洞。最后,Red Hat Single Sign-On 可能需要向外部服务器进行安全 SSL 和 HTTPS 连接,因此需要设置信任存储,以便正确验证端点。本章讨论了所有这些内容。

7.1. 绑定地址

默认情况下,Red Hat Single Sign-On 绑定到 localhost 回送地址 127.0.0.1。如果您想在网络上可用的身份验证服务器,则这不是非常有用的默认值。通常,我们建议您在公共网络上部署反向代理或负载均衡器,并将流量路由到私有网络上的单个 Red Hat Single Sign-On 服务器实例。在这两种情况下,您仍然需要设置网络接口,以绑定到 localhost 以外的其他接口。

设置绑定地址非常简单,可以在命令行中使用 standalone.shdomain.sh boot 脚本(在 Choosing an Operating Mode 章节中讨论) 在命令行中完成。

$ standalone.sh -b 192.168.0.5

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

或者,如果您不希望在命令行中设置绑定地址,您可以编辑部署的配置集配置。打开 profile 配置文件(standalone.xmldomain.xml,具体取决于您的 操作模式),并查找 接口 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>

公共接口 对应于创建公开可用的套接字的子系统。其中其中一个子系统的示例是提供 Red Hat Single Sign-On 身份验证端点的 Web 层。管理接口 对应于 JBoss EAP 管理层打开的套接字。特别是允许您使用 jboss-cli.sh 命令行界面和 JBoss EAP Web 控制台的套接字。

在查看 公共接口 中,您会看到它具有特殊字符串 ${jboss.bind.address:127.0.0.1}。此字符串表示值 127.0.0.1,可通过设置 Java 系统属性(例如:

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

-b 只是此命令的一个简写表示法。因此,您可以直接在配置集配置中更改 bind address 值,或者在引导时在命令行中更改它。

注意

设置 接口 定义时,还有更多可用选项。有关更多信息,请参阅 JBoss EAP 配置指南中的 网络接口

7.2. 套接字端口绑定

为每个套接字打开的端口都有一个预定义的默认值,可以在命令行或配置中覆盖。为了说明此配置,我们预先 以独立模式运行,并打开 …​/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 定义将由服务器打开的套接字连接。这些绑定指定了它们 使用的接口 (绑定地址),以及它们将打开的端口号。您最感兴趣的是:

http
定义用于 Red Hat Single Sign-On HTTP 连接的端口
https
定义用于 Red Hat Single Sign-On HTTPS 连接的端口
ajp
此套接字绑定定义用于 AJP 协议的端口。当您将 Apache HTTPD 服务器用作负载平衡器时,Apache HTTPD 服务器会结合使用此协议。
management-http
定义 JBoss EAP CLI 和 Web 控制台使用的 HTTP 连接。

当在 模式下运行时,套接字配置会稍微复杂,因为示例 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>

注意

设置 socket-binding-group 定义时,还有更多可用选项。有关更多信息,请参阅 JBoss EAP 配置指南中的 套接字绑定组

7.3. 设置 HTTPS/SSL

警告

默认情况下,Red Hat Single Sign-On 没有设置为处理 SSL/HTTPS。强烈建议您在 Red Hat Single Sign-On 服务器本身或 Red Hat Single Sign-On 服务器前在反向代理中启用 SSL。

这个默认行为由每个 Red Hat Single Sign-On 域的 SSL/HTTPS 模式定义。服务器管理指南中的 更为详细地讨论,但让我们提供了一些上下文以及这些模式的简要概述。

外部请求
Red Hat Single Sign-On 可以在没有 SSL 的情况下运行,只要您坚持使用私有 IP 地址(如 localhost,127.0.0.1,10.0.x.x,192.168.x.x, 和 172.16.x.x )。如果您没有在服务器上配置 SSL/HTTPS,或者您试图通过 HTTP 从非专用 IP 地址访问 Red Hat Single Sign-On,则会出现错误。
none
Red Hat Single Sign-On 不需要 SSL。您应该真正在开发过程中使用。
所有请求
Red Hat Single Sign-On 需要 SSL 用于所有 IP 地址。

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

7.3.1. 为 Red Hat Single Sign-On 服务器启用 SSL/HTTPS

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

  1. 获取或生成包含 SSL/HTTP 流量的私钥和证书的密钥存储
  2. 配置 Red Hat Single Sign-On 服务器以使用此密钥对和证书。

7.3.1.1. 创建证书和 Java 密钥存储

为了允许 HTTPS 连接,您需要获取自签名或第三方签名的证书,并将其导入到 Java 密钥存储中,然后才能在您将 Red Hat Single Sign-On 服务器部署到 web 容器中启用 HTTPS。

7.3.1.1.1. 自签名证书

在开发中,您可能没有第三方签名的证书来测试 Red Hat Single Sign-On 部署,因此您需要使用与 Java JDK 附带的 keytool 程序生成自签名证书。

$ 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

您应该回答 您的名字和姓氏是什么? 问题是您要安装该服务器的计算机的 DNS 名称。出于测试目的,应使用 localhost。执行此命令后,keycloak.jks 文件将生成在您执行 keytool 命令相同的目录中。

如果您希望第三方签名的证书,但没有一个证书,您可以在 cacert.org 获取一个空闲证书。但是,在执行此操作之前,必须先进行一些设置。

首先要做的是生成一个证书请求:

$ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq

其中 yourdomain 是为其生成此证书的 DNS 名称。keytool 生成请求:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y
ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY
Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1
29RvyeUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as
H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw
Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35
2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i
n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf
PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ
9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X
MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S
vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8=
-----END NEW CERTIFICATE REQUEST-----

将此 ca 请求发送到您的 CA。CA 将发出您签名的证书并将其发送给您。在导入新证书前,您必须获取并导入 CA 的 root 证书。您可以从 CA 下载证书(例如:root.crt)并导入,如下所示:

$ keytool -import -keystore keycloak.jks -file root.crt -alias root

最后一步是将生成的新 CA 证书导入到密钥存储中:

$ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer

7.3.1.2. 配置红帽单点登录以使用密钥存储

现在,您已有一个带有适当证书的 Java 密钥存储,您需要配置 Red Hat Single Sign-On 安装以使用它。第一步是将密钥存储文件移到部署的 configuration/ 目录中,并编辑 standalone.xmlstandalone-ha.xmldomain.xml 文件,以使用密钥存储并启用 HTTPS。(请参阅 操作模式)。

在独立或域配置文件中,搜索 security-realms 元素并添加:

<security-realm name="UndertowRealm">
    <server-identities>
        <ssl>
            <keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="secret" />
        </ssl>
    </server-identities>
</security-realm>

找到元素 服务器 name="default-server" (它是 子系统 xmlns="urn:jboss:domain:undertow:4.0"的子元素,并添加:

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
   <buffer-cache name="default"/>
   <server name="default-server">
      <https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
   ...
</subsystem>

7.4. 传出 HTTP 请求

Red Hat Single Sign-On 服务器通常需要对安全的应用程序和服务进行非浏览器 HTTP 请求。auth 服务器通过维护 HTTP 客户端连接池来管理这些传出连接。在 standalone.xmlstandalone-ha.xmldomain.xml 中需要配置一些内容。此文件的位置取决于您的 操作模式

HTTP 客户端配置示例

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

可能的配置选项有:

establish-connection-timeout-millis
建立套接字连接的超时。
socket-timeout-millis
如果传出请求没有收到这段时间的数据,请超时连接。
connection-pool-size
池中可以有多少个连接(默认为 128)。
max-pooled-per-route
可以为每个主机池多少个连接(默认为 64)。
connection-ttl-millis
以毫秒为单位进行的最大连接时间。默认不设置。
max-connection-idle-time-millis
连接在连接池中可能闲置的最长时间(默认为900 秒)。将启动 Apache HTTP 客户端的后台清理线程。设置为1 可禁用此检查和后台线程。
disable-cookies
默认情况下为 true。当设置为 true 时,这将禁用任何 Cookie 缓存。
client-keystore
这是 Java 密钥存储文件的文件路径。此密钥存储包含双向 SSL 的客户端证书。
client-keystore-password
客户端密钥存储的密码。如果设置了 client-keystore,则这是 REQUIRED
client-key-password
客户端密钥的密码。如果设置了 client-keystore,则这是 REQUIRED
proxy-mappings
Dennotes 出站 HTTP 请求的代理配置。如需了解更多详细信息,请参阅有关 Proxy Mappings for Outgoing HTTP Requests 部分。

7.4.1. 传出 HTTP 请求的代理映射

Red Hat Single Sign-On 发送的传出 HTTP 请求可以选择使用基于以逗号分隔的 proxy-mapping 的代理服务器。proxy-mapping 以 hostnamePattern;proxyUri 的形式表示基于 regex 的主机名模式和 proxy-uri 的组合,如:

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

要确定传出 HTTP 请求的代理,目标主机名与配置的主机名模式匹配。第一个匹配模式决定了要使用的 proxy-uri。如果没有为给定主机名配置任何配置的模式匹配,则不会使用代理。

proxy-uri 的特殊值 NO_PROXY 可用于指示不应将代理用于与关联的主机名模式匹配的主机。可以在 proxy-mappings 的末尾指定一个 catch-all 模式,为所有传出请求定义默认代理。

以下示例演示了 proxy-mapping 配置。

# 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

这可以通过以下 jboss-cli 命令进行配置。请注意,您需要正确转义 regex-pattern,如下所示。

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"])

jboss-cli 命令生成以下子系统配置:请注意,需要对 " 字符 " 进行编码。

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

7.4.2. 传出 HTTPS 请求 Truststore

当 Red Hat Single Sign-On 在远程 HTTPS 端点上调用时,必须验证远程服务器的证书,以确保它连接到可信服务器。这是为了防止中间人攻击所必需的。这些远程服务器的证书或签署这些证书的 CA 必须放在信任存储中。此信任存储由 Red Hat Single Sign-On 服务器管理。

在安全地连接到身份代理、LDAP 身份提供程序、发送电子邮件和与客户端应用程序的后端通道通信时,使用 truststore。

警告

默认情况下,不会配置信任存储提供程序,任何 https 连接都回退到标准的 java 信任存储配置,如 Java 的 JSSE 参考指南 中所述。如果没有信任,则这些传出 HTTPS 请求将失败。

您可以使用 keytool 创建新的信任存储文件,或向现有主机添加可信主机证书:

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

truststore 在您分发的 standalone.xmlstandalone-ha.xmldomain.xml 文件中配置。此文件的位置取决于您的 操作模式。您可以使用以下模板添加信任存储配置:

<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"/>
            <property name="disabled" value="false"/>
        </properties>
    </provider>
</spi>

此设置可能的配置选项有:

file
Java 密钥存储文件的路径。HTTPS 请求需要一种方法来验证它们要与之通信的服务器的主机。这是信任者的作用。密钥存储包含一个或多个可信主机证书或证书颁发机构。此 truststore 文件应该只包含您的安全主机的公共证书。如果禁用,则这是 REQUIRED
password
truststore 的密码。如果禁用,则这是 REQUIRED
hostname-verification-policy
默认 WILDCARD。对于 HTTPS 请求,这会验证服务器证书的主机名。ANY 表示主机名不会被验证。WILDCARD Allows wildcard in subdomain name i.e. Iffoo.com.STRICT CN 必须完全匹配主机名。
disabled
如果为 true (默认值),则忽略信任存储配置,证书检查将回退到 JSSE 配置,如下所述。如果设置为 false,则必须为信任存储 配置文件和密码

第 8 章 集群

本节论述了将 Red Hat Single Sign-On 配置为在集群中运行。设置集群时需要执行很多操作,特别是:

本指南前面讨论了一种操作模式和配置共享数据库。在本章中,我们将讨论设置负载均衡器并提供专用网络。我们还将讨论在引导集群中的主机时需要注意的一些问题。

注意

可以在没有 IP 多播的情况下集群 Red Hat Single Sign-On,但本主题超出了本指南的范围。有关更多信息,请参阅 JBoss EAP 配置指南中的 JGroups 章节。

8.2. 集群示例

Red Hat Single Sign-On 附带一个 box 集群演示,它利用域模式。详情请查看集群域示例 章节。

8.3. 设置负载均衡器或代理

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

8.3.1. 识别客户端 IP 地址

Red Hat Single Sign-On 中的一些功能依赖于连接到身份验证服务器的 HTTP 客户端的远程地址是客户端机器的实际 IP 地址。示例包括:

  • 事件日志 - 使用错误的源 IP 地址记录失败的登录尝试
  • SSL 必需 - 如果需要 SSL 设置为 external (默认值),则所有外部请求都需要 SSL
  • 身份验证流 - 使用 IP 地址的自定义身份验证流,如 show OTP 仅适用于外部请求
  • 动态客户端注册

当您在 Red Hat Single Sign-On 身份验证服务器前面有一个反向代理或 loadbalancer 时,这可能会造成问题。常见的设置是,您有一个 frontend 代理位于公共网络上,该代理负载平衡并将请求转发到专用网络中的后端 Red Hat Single Sign-On 服务器实例。在这种情况下,您必须执行一些额外的配置,以便实际的客户端 IP 地址被 Red Hat Single Sign-On 服务器实例转发到和处理。具体来说:

  • 将您的反向代理或负载均衡器配置为正确设置 X-Forwarded-ForX-Forwarded-Proto HTTP 标头。
  • 将您的反向代理或负载均衡器配置为保留原始的 'Host' HTTP 标头。
  • 配置身份验证服务器,从 X-Forwarded-For 标头 读取客户端的 IP 地址。

配置代理以生成 X-Forwarded-ForX-Forwarded-Proto HTTP 标头,并保留原始主机 HTTP 标头超出了本指南的范围。采取额外的措施来确保代理设置了 X-Forwared-For 标头。如果您的代理没有正确配置,则 恶意 客户端可以自行设置此标头,并欺骗 Red Hat Single Sign-On 认为客户端正在从不同的 IP 地址连接。如果您正在执行 IP 地址的黑色或白名单,这非常重要。

除了代理本身外,您需要在 Red Hat Single Sign-On 端配置一些操作。如果您的代理通过 HTTP 协议转发请求,则需要配置 Red Hat Single Sign-On,以从 X-Forwarded-For 标头而不是从网络数据包中提取客户端的 IP 地址。为此,请打开配置文件配置文件(standalone.xmlstandalone-ha.xmldomain.xml,具体取决于您的 操作模式),并查找 urn:jboss:domain:undertow:4.0 XML 块。

X-Forwarded-For HTTP 配置

<subsystem xmlns="urn:jboss:domain:undertow:4.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>

proxy-address-forwarding 属性添加到 http-listener 元素。将值设为 true

如果您的代理使用 AJP 协议而不是 HTTP 来转发请求(即 Apache HTTPD + mod-cluster),那么您必须配置一些不同的内容。您需要添加一个过滤器来从 AJP 数据包中提取此信息,而不是修改 http-listener

X-Forwarded-For AJP 配置

<subsystem xmlns="urn:jboss:domain:undertow:4.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>

8.3.2. 使用 Reverse 代理启用 HTTPS/SSL

假设您的反向代理没有为 SSL 使用端口 8443,您还需要配置将哪些端口 HTTPS 流量重定向到其中。

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

redirect-socket 属性添加到 http-listener 元素。该值应该是 proxy-https,它指向您还需要定义的套接字绑定。

然后,在 socket-binding - group 元素中添加一个新的 socket-binding 元素:

<socket-binding-group name="standard-sockets" default-interface="public"
    port-offset="${jboss.socket.binding.port-offset:0}">
    ...
    <socket-binding name="proxy-https" port="443"/>
    ...
</socket-binding-group>

8.3.3. 验证配置

您可以通过反向代理打开路径 /auth/realms/master/.well-known/openid-configuration 来验证反向代理或负载均衡器配置。例如,如果反向代理地址是 https://acme.com/,则打开 URL https://acme.com/auth/realms/master/.well-known/openid-configuration。这将显示一个 JSON 文档,其中列出了 Red Hat Single Sign-On 的多个端点。确保端点以反向代理或负载均衡器的地址(scheme、domain 和 port)开头。通过这样做,您可以确保 Red Hat Single Sign-On 使用正确的端点。

您还应验证 Red Hat Single Sign-On 是否看到请求的正确源 IP 地址。检查您可以尝试使用无效的用户名和/或密码登录管理控制台。这应该会在服务器日志中显示警告信息,如下所示:

08:14:21,287 WARN  XNIO-1 task-45 [org.keycloak.events] type=LOGIN_ERROR, realmId=master, clientId=security-admin-console, userId=8f20d7ba-4974-4811-a695-242c8fbd1bf8, ipAddress=X.X.X.X, error=invalid_user_credentials, auth_method=openid-connect, auth_type=code, redirect_uri=http://localhost:8080/auth/admin/master/console/?redirect_fragment=%2Frealms%2Fmaster%2Fevents-settings, code_id=a3d48b67-a439-4546-b992-e93311d6493e, username=admin

检查 ipAddress 的值是您尝试使用登录的机器的 IP 地址,而不是反向代理或负载均衡器的 IP 地址。

8.3.4. 使用 Built-In Load Balancer

本节介绍配置在群集 域示例 中讨论的内置负载均衡器。

集群域示例 仅设计为在一台计算机上运行。要在另一主机上启动从设备,您需要:

  1. 编辑 domain.xml 文件以指向您的新主机从设备
  2. 复制服务器分发。您不需要 domain.xmlhost.xmlhost-master.xml 文件。不需要 standalone/ 目录。
  3. 编辑 host-slave.xml 文件,以在命令行中更改使用或覆盖它们的绑定地址

8.3.4.1. 使用 Load Balancer 注册新主机

我们首先在 domain.xml 中使用负载均衡器配置注册新主机 slave。打开此文件,再前往 load-balancer 配置文件中的 undertow 配置。在 reverse-proxy XML 块中添加名为 remote- host 3 的新主机定义。

domain.xml reverse-proxy config

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
  ...
  <handlers>
      <reverse-proxy name="lb-handler">
         <host name="host1" outbound-socket-binding="remote-host1" scheme="ajp" path="/" instance-id="myroute1"/>
         <host name="host2" outbound-socket-binding="remote-host2" scheme="ajp" path="/" instance-id="myroute2"/>
         <host name="remote-host3" outbound-socket-binding="remote-host3" scheme="ajp" path="/" instance-id="myroute3"/>
      </reverse-proxy>
  </handlers>
  ...
</subsystem>

output-socket-binding 是指向稍后在 domain.xml 文件中配置的 socket-binding 的逻辑名称。instance-id 属性还必须对新主机唯一,因为 Cookie 用于在负载平衡时启用粘性会话。

接下来,向下滚动到 load-balancer-sockets socket-binding-group,再为 remote-host3 添加 outbound-socket-binding。这个新绑定需要指向新主机的主机和端口。

domain.xml outbound-socket-binding

<socket-binding-group name="load-balancer-sockets" default-interface="public">
    ...
    <outbound-socket-binding name="remote-host1">
        <remote-destination host="localhost" port="8159"/>
    </outbound-socket-binding>
    <outbound-socket-binding name="remote-host2">
        <remote-destination host="localhost" port="8259"/>
    </outbound-socket-binding>
    <outbound-socket-binding name="remote-host3">
        <remote-destination host="192.168.0.5" port="8259"/>
    </outbound-socket-binding>
</socket-binding-group>

8.3.4.2. Master 绑定地址

接下来,您需要更改 master 主机 的公共 和管理 绑定地址。按照 Bind Addresses 章节中所述编辑 domain.xml 文件,或者在命令行中指定这些绑定地址,如下所示:

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

8.3.4.3. 主机 Slave Bind Addresses

接下来,您必须更改 公共管理 和域控制器绑定地址(jboss.domain.master-address)。编辑 host-slave.xml 文件,或在命令行中指定它们,如下所示:

$ 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

与主机从 IP 地址相关的 jboss.bind.addressjboss.bind.addres.management 的值。jboss.domain.master.address 的值必须是域控制器的 IP 地址,这是 master 主机的管理地址。

8.3.5. 配置其他 Load Balancer

有关如何使用其他基于软件的 负载平衡器的信息,请参阅 JBoss EAP 配置指南中的 负载平衡 部分。

8.4. 粘性会话

典型的集群部署由专用网络上的负载均衡器(反向代理)和 2 个或更多 Red Hat Single Sign-On 服务器组成。出于性能的需要,如果负载均衡器将与特定浏览器会话相关的所有请求转发到同一 Red Hat Single Sign-On 后端节点,这可能很有用。

原因在于,Red Hat Single Sign-On 使用 infinispan 分布式缓存,在覆盖下保存与当前身份验证会话和用户会话相关的数据。Infinispan 分布式缓存默认配置有一个所有者。这意味着,特定的会话只保存在一个集群节点上,而其他节点需要远程查找会话(如果想要访问它)。

例如,如果带有 ID 为 123 的验证会话保存在 node1 上的 infinispan 缓存中,那么 node2 需要通过网络向 node1 发送请求,以返回特定的会话实体。

如果特定的会话实体始终在本地可用,这可以通过粘性会话的帮助来完成。集群环境中的工作流带有公共前端负载均衡器和两个后端 Red Hat Single Sign-On 节点,如下所示:

  • 用户发送初始请求以查看 Red Hat Single Sign-On 登录屏幕
  • 此请求由 frontend 负载均衡器提供,该负载均衡器将其转发到一些随机节点(例如 node1)。严格说,节点不需要随机,但可以根据某些其他条件(客户端 IP 地址等)进行选择。它都取决于底层负载均衡器的实施和配置(反向代理)。
  • Red Hat Single Sign-On 创建带有随机 ID (如 123)的验证会话,并将其保存到 Infinispan 缓存。
  • Infinispan 分布式缓存根据会话 ID 的哈希值分配会话的主要所有者。有关此问题的更多详细信息,请参阅 Infinispan 文档。假设 infinispan 分配 node2 是此会话的所有者。
  • Red Hat Single Sign-On 创建 cookie AUTH_SESSION_ID,格式为 < session-id>.<owner-node-id >。在我们的示例中,它将为 123.node2
  • 使用红帽单点登录登录屏幕和浏览器中的 AUTH_SESSION_ID cookie 返回用户的响应

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

集群设置的粘性会话不是强制的,但由于上述原因,最好是性能。您需要通过 AUTH_SESSION_ID cookie 将 loadbalancer 配置为粘性。具体操作取决于您的负载均衡器。

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

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

8.4.1. 禁用添加路由

有些负载均衡器可以配置为自行添加路由信息,而不依赖于后端 Red Hat Single Sign-On 节点。但是,如上所述,建议通过 Red Hat Single Sign-On 添加路由。这是因为,当以性能提高时,因为 Red Hat Single Sign-On 知道作为特定会话所有者的实体,并可路由到该节点,这不一定是本地节点。

如果需要,可以通过将以下内容添加到 Red Hat Single Sign-On 的 RHSSO_HOME/standalone/configuration/standalone-ha.xml 文件中,禁用在 Red Hat Single Sign-On 子系统配置中的 AUTH_SESSION_ID cookie 中添加路由信息:

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

</subsystem>

8.4.2. 使用 mod_cluster 的集群设置示例

在这个示例中,我们将使用 Mod Cluster 作为负载均衡器。mod 集群的主要功能之一是,负载均衡器端没有大量配置。相反,它需要支持后端节点。后端节点通过名为 MCMP 的专用协议与负载均衡器通信,它们通知 loadbalancer 关于各种事件(如节点加入或离开集群,新的应用程序已被部署等)。

示例设置将包含一个 JBoss EAP 7.1 负载平衡器节点和两个 Red Hat Single Sign-On 节点。

集群示例需要在计算机的回环网络接口上启用 MULTICAST。这可以通过在 root 特权下运行以下命令(在 linux 中):

route add -net 224.0.0.0 netmask 240.0.0.0 dev lo
ifconfig lo multicast

8.4.2.1. Load Balancer 配置

在某一位置解压缩 JBoss EAP 7.1 服务器。假设位置是 EAP_LB

编辑 EAP_LB/standalone/configuration/standalone.xml 文件。在 undertow 子系统中,将 mod_cluster 配置添加到过滤器下,如下所示:

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
 ...
 <filters>
  ...
  <mod-cluster name="modcluster" advertise-socket-binding="modcluster"
      advertise-frequency="${modcluster.advertise-frequency:2000}"
      management-socket-binding="http" enable-http2="true"/>
 </filters>

default -host 下过滤-ref,如下所示:

<host name="default-host" alias="localhost">
    ...
    <filter-ref name="modcluster"/>
</host>

然后,在 socket-binding-group 下添加这个组:

<socket-binding name="modcluster" port="0"
    multicast-address="${jboss.modcluster.multicast.address:224.0.1.105}"
    multicast-port="23364"/>

保存文件并运行服务器:

cd $WILDFLY_LB/bin
./standalone.sh

8.4.2.2. 后端节点配置

将 Red Hat Single Sign-On 服务器发行版本解压缩到某个位置。假设位置是 RHSSO_NODE1

编辑 RHSSO_NODE1/standalone/configuration/standalone-ha.xml,并根据共享数据库配置数据源。如需了解更多详细信息 ,请参阅数据库章节

在 undertow 子系统中,将 session-config 添加到 servlet-container 元素下:

<servlet-container name="default">
    <session-cookie name="AUTH_SESSION_ID" http-only="true" />
    ...
</servlet-container>
警告

仅将 session-config 与 mod_cluster 负载平衡器一起使用。在其他情况下,直接在负载均衡器中通过 AUTH_SESSION_ID cookie 配置粘性会话。

然后,您可以配置 proxy-address-forwarding,如 chapter Load Balancer 所述。请注意,mod_cluster 默认使用 AJP 连接器,因此您需要配置一个。

这一切都配置为 mod_cluster。

可以根据当前服务器的主机名自动探测到 Red Hat Single Sign-On 的节点名称。但是,为了更精细的控制,建议使用系统属性 jboss.node.name 来直接指定节点名称。当您测试同一物理服务器上的 2 个后端节点时,这特别有用。因此,您可以运行类似如下的启动命令:

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

以同样的方式配置第二个后端服务器,并使用不同的端口偏移和节点名称运行。

cd $RHSSO_NODE2
./standalone.sh -c standalone-ha.xml -Djboss.socket.binding.port-offset=200 -Djboss.node.name=node2

访问 http://localhost:8080/auth 中的服务器。只能从本地地址和没有负载均衡器(proxy)访问创建 admin 用户,因此您首先需要直接在 http://localhost:8180/auth 上访问后端节点以创建 admin 用户。

警告

使用 mod_cluster 时,您应该始终通过负载均衡器访问集群,而不是直接通过后端节点访问集群。

8.5. 多播网络设置

开箱即用的集群支持需要 IP 多播。多播是网络广播协议。此协议在引导时用于发现和加入集群。它还用于广播复制和 Red Hat Single Sign-On 使用的分布式缓存无效消息。

Red Hat Single Sign-On 的集群子系统在 JGroups 堆栈上运行。开箱即用,集群的绑定地址绑定到带有 127.0.0.1 作为默认 IP 地址的私有网络接口。您必须编辑 Bind Address 章节中讨论的 standalone-ha.xmldomain.xml 部分。

专用网络配置

    <interfaces>
        ...
        <interface name="private">
            <inet-address value="${jboss.bind.address.private:127.0.0.1}"/>
        </interface>
    </interfaces>
    <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
        ...
        <socket-binding name="jgroups-mping" interface="private" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
        <socket-binding name="jgroups-tcp" interface="private" port="7600"/>
        <socket-binding name="jgroups-tcp-fd" interface="private" port="57600"/>
        <socket-binding name="jgroups-udp" interface="private" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
        <socket-binding name="jgroups-udp-fd" interface="private" port="54200"/>
        <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
        ...
    </socket-binding-group>

您需要配置的内容是 jboss.bind.address.privatejboss.default.multicast.address,以及集群堆栈上服务的端口。

注意

可以在没有 IP 多播的情况下集群 Red Hat Single Sign-On,但本主题超出了本指南的范围。有关更多信息,请参阅 JBoss EAP 配置指南中的 JGroups

8.6. 保护集群通信

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

如果要为集群通信启用身份验证和加密,请参阅 JBoss EAP 配置指南中的保护集群

8.7. 序列化集群启动

Red Hat Single Sign-On 集群节点允许引导并发。当 Red Hat Single Sign-On 服务器实例引导时,可能需要进行一些数据库迁移、导入或首次初始化。DB 锁定用于防止在集群节点同时引导时与另一个操作冲突。

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

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

8.8. 引导集群

在集群中引导 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

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

8.9. 故障排除

请注意,当运行集群时,您应该会在两个集群节点的日志中看到类似如下的消息:

INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (Incoming-10,shared=udp)
ISPN000094: Received new cluster view: [node1/keycloak|1] (2) [node1/keycloak, node2/keycloak]

如果您只看到提到的一个节点,您的集群主机可能无法连接在一起。

通常,最好在私有网络上具有集群节点,而无需防火墙以用于它们之间的通信。防火墙只能对您的网络的公共访问点启用。如果出于某种原因,您仍需要在集群节点上启用防火墙,则需要打开一些端口。默认值为 UDP 端口 55200 和多播端口 45688,多播地址为 230.0.0.4。请注意,如果您想要为 JGroups 堆栈启用诊断等其他功能,您可能需要打开更多端口。Red Hat Single Sign-On 将大多数集群工作委托给 Infinispan/JGroups。有关更多信息,请参阅 JBoss EAP 配置指南中的 JGroups

第 9 章 服务器缓存配置

Red Hat Single Sign-On 有两种类型的缓存。一种缓存位于数据库前面,以降低 DB 的负载,并通过在内存中保留数据来提高总体响应时间。realm、client、role 和 user 元数据保存在这种类型的缓存中。这个缓存是本地缓存。即使位于具有更多 Red Hat Single Sign-On 服务器的集群中,本地缓存也不会使用复制。相反,它们只会在本地保留副本,如果条目更新了一个 invalidation 消息,则消息会发送到集群的其余部分,该条目将被驱除。有单独的复制缓存 工作,该任务是将失效消息发送到整个集群,其中哪些条目应从本地缓存驱除。这可大大减少网络流量,使效率更高,并避免通过线路传输敏感元数据。

第二类型的缓存处理管理用户会话、离线令牌,并跟踪登录失败,以便服务器可以检测密码临时和其他攻击。这些缓存中保存的数据只是临时的,但可能在集群中复制。

本章讨论了这两个集群非集群部署用于这些缓存的一些配置选项。

注意

有关这些缓存的更多高级配置,请参阅 JBoss EAP 配置指南中的 Infinispan 部分。

9.1. 驱除和过期

为红帽单点登录配置了多个不同的缓存。有一个域缓存,其中包含有关安全应用程序、通用安全数据和配置选项的信息。另外,还有一个包含用户元数据的用户缓存。两者都会默认缓存到最多 10000 个条目,并使用最早使用的驱除策略。它们也与控制集群设置中驱除的对象修订缓存相关联。这个缓存是隐式创建的,且配置的大小已两倍。用户会话、离线令牌和登录失败也存在单独的缓存。这些缓存也没有绑定大小。

这些缓存的驱除策略和最大条目可以在 standalone. xml、standalone -ha.xmldomain.xml 中配置,具体取决于您的 操作模式

非集群

<subsystem xmlns="urn:jboss:domain:infinispan:4.0">
    <cache-container name="keycloak" jndi-name="infinispan/Keycloak">
        <local-cache name="realms">
            <eviction max-entries="10000" strategy="LRU"/>
        </local-cache>
        <local-cache name="users">
            <eviction max-entries="10000" strategy="LRU"/>
        </local-cache>
        <local-cache name="sessions"/>
        <local-cache name="offlineSessions"/>
        <local-cache name="loginFailures"/>
        <local-cache name="work"/>
        <local-cache name="authorization">
           <eviction strategy="LRU" max-entries="100"/>
        </local-cache>
        <local-cache name="keys">
            <eviction strategy="LRU" max-entries="1000"/>
            <expiration max-idle="3600000"/>
        </local-cache>
    </cache-container>

集群的

<subsystem xmlns="urn:jboss:domain:infinispan:4.0">
    <cache-container name="keycloak" jndi-name="infinispan/Keycloak">
        <transport lock-timeout="60000"/>
        <local-cache name="realms">
            <eviction max-entries="10000" strategy="LRU"/>
        </local-cache>
        <local-cache name="users">
            <eviction max-entries="10000" strategy="LRU"/>
        </local-cache>
        <distributed-cache name="sessions" mode="SYNC" owners="1"/>
        <distributed-cache name="offlineSessions" mode="SYNC" owners="1"/>
        <distributed-cache name="loginFailures" mode="SYNC" owners="1"/>
        <distributed-cache name="authorization" mode="SYNC" owners="1"/>
        <replicated-cache name="work" mode="SYNC"/>
        <local-cache name="keys">
            <eviction max-entries="1000" strategy="LRU"/>
            <expiration max-idle="3600000"/>
        </local-cache>
    </cache-container>

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

9.2. 复制和故障切换

会话authenticationSessionsofflineSessionsloginFailures 缓存是唯一可能执行复制的缓存。条目不会复制到每个节点,而是选择一个或多个节点作为该数据的所有者。如果节点不是特定缓存条目的所有者,它会查询集群来获取它。这意味着,如果拥有数据的所有节点都停机,则数据将永久丢失。默认情况下,Red Hat Single Sign-On 只为数据指定一个所有者。因此,如果一个节点停止那个数据,则该节点会丢失。这通常意味着用户将被注销,必须再次登录。

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

owners

<subsystem xmlns="urn:jboss:domain:infinispan:4.0">
   <cache-container name="keycloak" jndi-name="infinispan/Keycloak">
       <distributed-cache name="sessions" mode="SYNC" owners="2"/>
...

此处我们更改了它,因此至少两个节点将复制一个特定的用户登录会话。

提示

建议的所有者数量实际上取决于您的部署。如果没有小心,如果在节点停机时用户注销,则一个所有者就足够了,您将避免复制。

9.3. 禁用缓存

要禁用 realm 或用户缓存,您必须编辑发行版中的 standalone.xmlstandalone-ha.xmldomain.xml 文件。此文件的位置取决于您的 操作模式。首先,配置是什么样子。

    <spi name="userCache">
        <provider name="default" enabled="true"/>
    </spi>

    <spi name="realmCache">
        <provider name="default" enabled="true"/>
    </spi>

要禁用缓存,将您要禁用的缓存的 enabled 属性设置为 false。您必须重新引导服务器才能使此更改生效。

9.4. 在运行时清除缓存

要清除 realm 或 user 缓存,请转至 Red Hat Single Sign-On admin console Realm Settings→Cache Config 页面。在此页面中,您可以清除域缓存、用户缓存或外部公钥的缓存。

注意

将为所有域清除缓存!

法律通告

Copyright © 2018 Red Hat, Inc.
根据 Apache 许可证(版本 2.0)授权(License");除非遵守许可证,您可能不能使用此文件。您可以在以下位置获取许可证副本
除非适用法律或同意编写,许可证下的软件将由"AS IS"BASIS 分发,WITHOUT WARRANTIES 或 CONDITIONS OF ANY KIND,可以是表达或表示的。有关许可证下的权限和限制的具体语言,请参阅许可证。