Keycloak.X 发行版介绍

2020 年 12 月 16 日 由 Keycloak 团队

世界变化迅速，IT 一直是引擎的重要组成部分。 随着企业开始将其基础设施迁移到云，安全性成为使这一旅程取得成功的关键因素。

我们很自豪地宣布，Keycloak 现在运行在 Quarkus 之上，Quarkus 是一个使用最优秀 Java 库和标准的 Kubernetes 和云原生堆栈，为我们的用户提供以易用性、可扩展性和针对混合云优化的云友好发行版。

此新发行版格式也称为 Keycloak.X，提供

为什么选择 Quarkus？

Keycloak 本质上是一个 Java 应用程序，目前运行在 Wildfly (JEE) 应用程序服务器之上。 到目前为止，这就是我们一直发布 Keycloak 服务器供一般使用的方式。

虽然 Wildfly 可能是最优化、易用且性能最好的 JEE 应用程序服务器，但我们现在对以更云原生方式运行的要求推动了我们前进，而 Quarkus 作为 Java 和容器优先堆栈，为 Keycloak 带来了所有使 Quarkus 成为在混合云中运行的完美选择的功能，重点关注 Kubernetes 和 Openshift 等平台。

有关 Quarkus 的更多信息，请查看他们的网站 https://quarkus.io/。

专注于易用性

在 Quarkus 上，Keycloak 是一个普通的 Java 应用程序，与 Wildfly 发行版相比，堆栈要简单得多。

使用新发行版，用户在配置和启动服务器以及执行其他常见操作时应期待更好的体验。

丰富的命令行界面的引入使安装和使用 Keycloak 变得更加容易。

更小

发行版更简单，只有几个目录，发行版的总大小几乎是当前基于 WildFly 发行版的一半。

通过利用 Quarkus，Keycloak 显着减少了服务器启动时间、内存占用 (低 RSS) 以及通过 Vert.x 提高了运行时性能。

所有这些方面在混合云部署中都很重要，其中资源使用应该优化以提供最佳运行时环境以及降低成本。

容器优先和云原生发行版

结合 Keycloak 运算符，将 Keycloak 部署到混合云应该更容易。

启动一个简单的容器也是如此。

开发人员体验

Quarkus 为开发人员提供了丰富的生态系统，并与众多不同库进行了集成。

灵活性可能是 Keycloak 的主要特征之一，而使用 Quarkus，我们希望为开发人员提供更好的体验。

安装

从 http://keycloak.java.net.cn/downloads 下载并解压缩 Keycloak.X 发行版 zip 或 tar.gz 文件。

目录结构

bin 目录是所有二进制文件所在的位置，主要是新的 Keycloak CLI 和一些其他实用程序。

conf 目录顾名思义，是存放配置文件的地方。 您可能正在使用此目录中的 keycloak.properties 文件来配置服务器，也可能没有使用。 您将在稍后详细介绍配置时看到更多信息。

providers 目录是您应该部署包含自定义提供程序或主题 jar 的 JAR 文件的地方。

命令行界面

我们的主要要求之一是在首次使用服务器时以及服务器在生产环境中运行的长期运行中改善用户体验。

人们通常对服务器执行的常见操作更容易执行，并且通过提供良好的默认值并要求最少的选项集来运行服务器，配置应该更简单。

Keycloak CLI 是一个工具，您现在应该使用它来启动和更改服务器的配置。 与任何其他 CLI 一样，它是自述的，并且围绕其使用有良好的文档。

通过运行

kc.sh --help

您现在可以查看您可以执行的不同操作，例如启动服务器或导出领域，以及查看您可以为每个支持的命令设置的不同配置选项。

我们一直在寻找 CLI 的改进。 请随时与我们联系，提出您认为可能有帮助的任何建议。

启动服务器

如前所述，默认配置对服务器的启动方式施加了一些条件。

成功启动服务器的主要条件之一是配置 HTTPS。

但是，出于开发目的，Keycloak 可以以开发模式启动。

目前，此模式基本上是一个配置配置文件，允许您在没有 HTTPS 的情况下使用本地缓存运行服务器。

kc.sh start-dev

执行上述命令后，服务器应该在 http://127.0.0.1:8080/ 上可用。

将来，此模式还将在某些领域配置策略方面放宽，否则这些策略在生产环境中运行时将不被允许。 例如，在您的客户端中使用通配符作为有效的重定向 URI。

配置服务器

考虑到 IAM 解决方案的重要性以及错误配置对部署总体安全性的影响，Keycloak 现在以尽可能少的配置进行分发，并牢记安全优先的策略。

其理念是在施加一些对配置应如何在生产环境中运行之前进行设置的关键约束的同时，提供运行服务器的最低限度配置选项。

这是我们正在改进的主要领域之一，并且我们一直在努力改进，其中应通过少量配置选项或良好的默认值来避免样板配置。

现在可以使用属性文件、环境变量或作为 Keycloak CLI 的参数来设置不同的配置选项。

您可以通过运行 help 命令轻松查看可用的配置选项。

有关配置的更多详细信息，请查看 配置设计 文档。

配置类别

配置选项分为两类

  • 可以在启动服务器时运行时设置的那些

  • 只能通过 config 命令配置服务器时设置的那些

例如，如果要将 HTTP 端口更改为 8180，可以使用

kc.sh --http-port=8180

但是，要更改数据库，您需要先运行 config 命令，然后再启动服务器

kc.sh config --db=postgres --db-username=******* --db-password=*******
Kc.sh # then start the server

基本上，您在配置服务器时可以设置的任何配置选项也可以在启动服务器时设置，但反之则不成立，数据库配置就是这种情况的示例。

检查 help 选项以查看可以为每个可用命令设置哪些属性。

HTTPS

在现实世界中，您将配置有效的密钥对和证书，但您可以使用以下命令生成自签名证书以了解如何设置 HTTPS。

只需确保在发行版的根目录中执行以下命令

keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore

上述命令应该在 conf 目录中创建一个 server.keystore 文件。 默认情况下，如果未设置任何密钥库，Keycloak 将从该密钥库加载密钥和证书。

之后，您可以按如下方式运行服务器

kc.sh

数据库

数据库配置要简单得多。 您只需使用几个简单的命令行参数即可更改数据库

kc.sh config --db=postgres && kc.sh --db-username=**** --db-password=****

对于每个数据库，我们都为 JDBC URL、驱动程序、数据库名称和方言提供了良好的默认值。 因此，如果您对默认值感到满意，则无需提供这些选项。

在上面的示例中，服务器连接到运行在 localhost 上的 PostgreSQL 服务，其中数据库名称为 keycloak。

当然，在生产环境中，您通常需要自定义 JDBC URL 和其他参数，因此您可以按如下方式启动服务器

kc.sh --db-url=jdbc:postgresql://<host>/<database> \
      --db-username=****** \
      --db-password=******

或者仍然依赖于默认的 JDBC URL 并设置主机和数据库，如下所示

kc.sh -Dkc.db.url.host=<host> \
      -Dkc.db.url.database=<database>
      --db-username=******
      --db-password=******

集群

目前，我们仍在使用 Infinispan 和 JGroups 进行集群和 HA 部署。

但是，配置现在使用 Infinispan 的本机配置，而不是像 Wildfly Infinispan 子系统那样使用抽象。 这应该在配置、支持以及文档方面提供更大的灵活性。

配置也已简化，您应该获得服务器部署在不同平台上的良好默认值。

默认情况下，集群已启用，您可以使用默认配置构建 Keycloak 集群。

默认配置位于 conf 目录中，文件名是 cluster-default.xml。

在同一个目录中，您还有一个 cluster-local.xml 文件，它将所有缓存配置为本地缓存，没有集群。 要使用此配置，请运行以下命令

kc.sh --cluster=local

您只需在 conf 目录中创建一个以 cluster- 为前缀的文件即可定义您自己的缓存配置，就像我们与发行版一起提供的 cluster-local.xml 和 cluster-default 文件一样。

我们还为特定平台（例如 Kubernetes 和 EC2）提供了一些良好的默认值。 例如，要在 Kubernetes 中运行集群，您可以运行以下命令

kc.sh -Djgroups.dns.query=<jgroups-ping-service>.<namespace>.<cluster-domain-suffix> --cluster-stack=kubernetes

这些平台的默认配置基于 Infinispan 提供的默认值。

在上面的示例中，Kubernetes 的默认配置将基于 UDP 进行节点通信，并基于 DNS_PING 进行节点发现。 您可以从 Infinispan 文档中获取用于自定义默认配置的任何参数。

自定义提供程序和主题

自定义提供程序和主题的 JAR 文件应放在 providers 目录中。

但是，为了从安装自定义提供程序时的优化中获益，您应该先运行 config 命令，然后再启动服务器

kc.sh config
kc.sh # then start the server

基本上，在配置服务器时会解析 SPI 实现，因此在启动过程中可以节省启动时间和内存。 运行 config 命令安装自定义提供程序后，它们将被静态链接到服务器。

在容器中运行

要使用 Docker 运行 Keycloak，您可以使用以下命令

docker run --name keycloak -p 8080:8080  \
    -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
    quay.io/keycloak/keycloak-x \
    start-dev

如预期的那样，容器将在开发模式下运行。

您可以通过传递任何命令行参数来像使用 Keycloak.X 发行版一样运行服务器。

要使用您希望持久保存到服务器映像中的任何其他配置来配置容器，您可以使用 --auto-config 选项，如下所示

docker run --name keycloak -p 8080:8080 \
    -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
    quay.io/keycloak/keycloak-x \
    --auto-config \
    --db=postgres -Dkc.db.url.host=$DB_HOST --db-username=keycloak --db-password=change_me --http-enabled=true

上述命令应该足以使用监听在给定 DB_HOST 上的 PostgreSQL 数据库运行服务器。 创建容器后，后续重启将不再执行配置阶段，而只是使用先前定义的配置启动服务器。

但是，建议始终基于此映像创建您自己的映像。 这样做，您就可以执行更多自定义操作，例如部署自定义提供程序或主题，并通过消除配置步骤来缩短启动时间。

有关更多详细信息和示例，请参阅 https://github.com/keycloak/keycloak-containers/tree/master/server-x。

基准测试

以下是在 Quarkus 和 Wildfly 上运行的 Keycloak 之间进行非常简单比较的一些数字。

这两个发行版都使用 OpenJDK 11 和 PostgreSQL 数据库运行，数字是每个发行版连续 10 次运行的平均值。

测试场景包括首次运行服务器以及数据库已初始化时的运行。

发行版

启动时间(秒)

内存占用(RSS/MB)

第一次

第二次+

第一次

第二次+

Wildfly

12.1

8.1

646

512

Quarkus

7.6

3.1

428

320

数据本身就说明了一切，人们应该期待这些数字在每个 Keycloak.X 版本中都会有所改进。

然而，这不仅关乎减少 MB，还关乎如何优化内存使用。通过使用 64MB 堆运行这两个服务器，您应该会注意到，在 Wildfly 上运行时，会有很多垃圾回收，最终可能会导致服务器无法启动。而使用 Keycloak.X 运行相同大小的堆时，您可以启动服务器。当然，根据您的用例，使用这种堆大小并不现实，但它可以让您大致了解未来的情况。

关于性能，在这个第一个版本中，我们主要关注启动时间和内存消耗。运行时性能仍在开发中，由于 Keycloak.X 运行在 Vert.X 之上，因此结果很有希望。

总的来说，我们才刚刚开始。一旦 Keycloak 在 Quarkus 上拥有原生发行版，我们就可以期待更快的启动时间、更小的内存消耗以及总体上更好的性能，而所需的资源更少。

路线图

这仅仅是我们为使用 Keycloak 的用户提供更云友好的体验之旅的开始。

Keycloak.X 是一个预览发行版，我们正在不断改进它，并借助社区的力量，直到它成为我们的主要发行版。我们感谢您在这一旅程中的任何反馈。

有很多重要的工作正在进行，这些工作补充了 Keycloak.X 发行版，例如

  • 零停机升级

  • 原生镜像支持

  • 改进开发者体验

  • 更多文档

我们希望您能支持并提供反馈，以不断改进您使用 Keycloak 的体验。

感谢社区

这是社区共同努力的结果，因此我们想重点感谢所有贡献者。

特别感谢

以及所有帮助编写 配置设计文档 的人。

参考