配置 Keycloak

了解如何配置和启动 Keycloak

本指南介绍 Keycloak 的配置方法，以及如何启动并应用首选配置。它包含针对优化 Keycloak 以实现更快启动和更低内存占用量而制定的配置指南。

配置 Keycloak 的数据源

Keycloak 从以下四个数据源加载配置，这些数据源按应用顺序排列。

  1. 命令行参数

  2. 环境变量

  3. 在 conf/keycloak.conf 文件中定义的选项，或在用户创建的配置文件中定义的选项。

  4. 在用户创建的 Java 密钥库文件中定义的敏感选项。

如果一个选项在多个数据源中设置，则列表中排在最前面的数据源决定该选项的值。例如，通过命令行参数设置的选项值比同一选项的环境变量具有更高的优先级。

示例：配置 db-url-host 参数

以下示例演示了如何在四个配置数据源中设置 db-url 值

数据源 格式

命令行参数

--db-url=cliValue

环境变量

KC_DB_URL=envVarValue

配置文件

db-url=confFileValue

Java 密钥库文件

kc.db-url=keystoreValue

根据应用的优先级，在启动时使用的值为 cliValue，因为命令行具有最高优先级。

如果未使用 --db-url=cliValue，则应用的值将为 KC_DB_URL=envVarValue。如果命令行或环境变量均未应用该值，则将使用 db-url=confFileValue。如果未应用上述任何值，则将使用 kc.db-url=keystoreValue，因为它在所有可用的配置数据源中优先级最低。

配置格式

该配置使用统一的每个数据源格式，简化了从一个配置数据源到另一个配置数据源的键值对转换。请注意，这些格式也适用于 spi 选项。

命令行参数格式

命令行值使用 --<带连字符的键>=<值> 格式。对于某些值，还存在 -<缩写>=<值> 简写形式。

环境变量格式

环境变量值使用大写的 KC_<带下划线的键>=<值> 格式。

配置文件格式

放入配置文件中的值使用 <带连字符的键>=<值> 格式。

密钥库配置文件格式

放入密钥库配置文件中的值使用 kc.<带连字符的键> 格式。<值> 然后是存储在密钥库中的密码。

在每个配置指南的末尾，请查找相关选项标题，其中定义了适用的配置格式。有关所有配置选项，请参阅 所有配置。选择适用于您的用例的配置数据源和格式。

示例 - 基于配置数据源的替代格式

以下示例显示了三个配置数据源的 db-url-host 配置格式

命令行参数
bin/kc.[sh|bat] start --db-url-host=mykeycloakdb
环境变量
export KC_DB_URL_HOST=mykeycloakdb
conf/keycloak.conf
db-url-host=mykeycloakdb

命令行参数格式

Keycloak 附带许多用于配置的命令行参数。要查看可用的配置格式，请输入以下命令

bin/kc.[sh|bat] start --help

或者，请参阅 所有配置 以查看所有服务器选项。

环境变量格式

您可以使用占位符从 keycloak.conf 文件中的环境变量解析特定于环境的值，方法是使用 ${ENV_VAR} 语法

db-url-host=${MY_DB_HOST}

如果无法解析环境变量，您可以指定一个回退值。在 mydb 之前使用 :（冒号），如下所示

db-url-host=${MY_DB_HOST:mydb}

包含特定配置文件的格式

默认情况下，服务器始终从 conf/keycloak.conf 文件中获取配置选项。对于新安装，此文件仅包含作为在生产环境中运行时想要设置的内容的想法的已注释设置。

您还可以通过输入以下命令来指定一个显式的配置文件位置，方法是使用 [-cf|--config-file] 选项

bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start

设置该选项后，Keycloak 将从指定的文件而不是 conf/keycloak.conf 中读取配置。

使用 Java 密钥库文件设置敏感选项

借助密钥库配置数据源，您可以使用 [--config-keystore] 和 [--config-keystore-password] 选项直接从 Java 密钥库中加载属性。或者，您可以使用 [--config-keystore-type] 选项指定密钥库类型。默认情况下，密钥库类型为 PKCS12。

密钥库中的机密需要使用 PBE（基于密码的加密）密钥算法存储，其中密钥是从密钥库密码中派生的。您可以使用以下 keytool 命令生成此类密钥库

keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v

执行完该命令后，系统将提示您输入要存储的密码，这表示上述 kc.db-password 属性的值。

创建密钥库后，您可以使用以下参数启动服务器

bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=keystorepass --config-keystore-type=PKCS12

原始 Quarkus 属性格式

在大多数情况下，可用的配置选项应该足以配置服务器。但是，对于 Keycloak 配置中缺少的特定行为或功能，您可以使用底层 Quarkus 框架中的属性。

如果可能，请避免直接使用 Quarkus 属性，因为它们不受 Keycloak 支持。如果您的需求至关重要，请先考虑打开一个 增强请求。这样做有助于我们改进 Keycloak 的配置，以满足您的需求。

如果无法提交增强请求，您可以使用原始 Quarkus 属性配置服务器

  1. 在 conf 目录中创建一个 quarkus.properties 文件。

  2. 在该文件中定义所需的属性。

    您只能使用在 子集 中定义的 Quarkus 扩展的 Quarkus 文档。此外，请注意 Quarkus 属性的这些差异

    • Quarkus 文档 中 Quarkus 属性的锁图标表示构建时属性。您运行 build 命令来应用此属性。有关构建命令的详细信息，请参阅后面关于优化 Keycloak 的部分。

    • Quarkus 指南中没有锁图标的属性表示 Quarkus 和 Keycloak 的运行时属性。

  3. 使用 [-cf|--config-file] 命令行参数来包含该文件。

同样，您也可以将 Quarkus 属性存储在 Java 密钥库中。

请注意，某些 Quarkus 属性已在 Keycloak 配置中映射，例如 quarkus.http.port 和类似的基本属性。如果 Keycloak 使用了该属性，则在 quarkus.properties 中定义该属性键将无效。Keycloak 配置值优先于 Quarkus 属性值。

在值中使用特殊字符

Keycloak 依赖于 Quarkus 和 MicroProfile 来处理配置值。请注意，支持值表达式。例如，${some_key} 评估为 some_key 的值。

要禁用表达式求值，\ 字符充当转义字符。特别是，当 $ 字符出现以定义表达式或重复时，必须使用它来转义 $ 字符的使用。例如，如果要配置值 my$$password，请使用 my\$\$password 而不是 my$$password。请注意，当使用大多数 unix shell 或在属性文件中出现时，\ 字符需要额外的转义或引用。例如，bash 单引号保留单个反斜杠 --db-password='my\$\$password'。此外，对于 bash 双引号，您需要额外的反斜杠 --db-password="my\\$\\$password"。同样，在属性文件中，反斜杠字符也必须转义：kc.db-password=my\\$\\$password

启动 Keycloak

您可以在 开发模式 或 生产模式 下启动 Keycloak。每种模式都为目标环境提供了不同的默认值。

在开发模式下启动 Keycloak

首次尝试 Keycloak 时使用开发模式，以便快速启动并运行。此模式为开发人员提供了便捷的默认值，例如用于开发新的 Keycloak 主题。

要在开发模式下启动，请输入以下命令

bin/kc.[sh|bat] start-dev
默认值

开发模式会设置以下默认配置

  • 启用 HTTP

  • 禁用严格主机名解析

  • 将缓存设置为本地（不使用用于高可用性的分布式缓存机制）

  • 禁用主题缓存和模板缓存

在生产模式下启动 Keycloak

将 Keycloak 部署到生产环境中时使用生产模式。此模式遵循默认情况下安全原则。

要在生产模式下启动，请输入以下命令

bin/kc.[sh|bat] start

在不进行任何其他配置的情况下，此命令将无法启动 Keycloak，而是显示错误信息。这是故意的，因为 Keycloak 遵循默认情况下安全原则。在启动时，生产模式期望已设置主机名，并且 HTTPS/TLS 设置可用。

默认值

生产模式设置以下默认值

  • 禁用 HTTP，因为传输层安全 (HTTPS) 至关重要

  • 期望主机名配置

  • 期望 HTTPS/TLS 配置

在生产环境中部署 Keycloak 之前，请确保按照 为生产配置 Keycloak 中概述的步骤进行操作。

默认情况下，生产模式的示例配置选项在默认 conf/keycloak.conf 文件中已注释掉。这些选项让您了解在生产环境中运行 Keycloak 时要考虑的主要配置。

创建初始管理员用户

您可以使用 Web 前端创建初始管理员用户，您可以通过本地连接 (localhost) 访问该前端。您可以使用环境变量创建此用户。设置 KC_BOOTSTRAP_ADMIN_USERNAME=<用户名> 用于初始管理员用户名，设置 KC_BOOTSTRAP_ADMIN_PASSWORD=<密码> 用于初始管理员密码。

Keycloak 在首次启动时解析这些值，以创建具有管理权限的初始用户。一旦存在第一个具有管理权限的用户，您就可以使用管理员控制台或命令行工具 kcadm.[sh|bat] 创建其他用户。

如果初始管理员已存在并且环境变量在启动时仍然存在，日志中将显示一条有关创建初始管理员失败的错误消息。Keycloak 会忽略这些值并正常启动。

优化 Keycloak 启动

我们建议在将 Keycloak 部署到生产环境中之前对其进行优化，以实现更快的启动速度和更低的内存消耗。本节介绍如何应用 Keycloak 优化，以实现最佳性能和运行时行为。

创建优化的 Keycloak 构建

默认情况下，当您使用 start 或 start-dev 命令时，Keycloak 会出于便利性原因在后台运行 build 命令。

此 build 命令执行一组优化，用于启动和运行时行为。 构建过程可能需要几秒钟。 特别是在 Kubernetes 或 OpenShift 等容器化环境中运行 Keycloak 时，启动时间很重要。 为了避免浪费时间，请在启动之前显式运行 build，例如在 CI/CD 管道中的单独步骤中。

第一步：显式运行构建

要运行 build，请输入以下命令

bin/kc.[sh|bat] build <build-options>

此命令显示您输入的 build options。 Keycloak 区分在运行 build 命令时可用的 build options 和在启动服务器时可用的 configuration options。

对于未经优化的 Keycloak 启动，此区分没有影响。 但是，如果您在启动之前运行构建，则只有一部分选项可用于构建命令。 此限制是由于构建选项被持久化到优化的 Keycloak 映像中。 例如，凭据配置（例如 db-password，这是一个配置选项）出于安全原因不能持久化。

所有构建选项都以纯文本形式持久化。 不要将任何敏感数据存储为构建选项。 这适用于所有可用的配置源，包括 KeyStore 配置源。 因此，我们也不建议将任何构建选项存储在 Java 密钥库中。 此外，在配置选项方面，我们建议主要使用 KeyStore 配置源来存储敏感数据。 对于非敏感数据，您可以使用其余配置源。

构建选项在 所有配置 中用工具图标标记。 要查找可用的构建选项，请参阅 所有配置页面，其中选择了构建选项 或输入以下命令

bin/kc.[sh|bat] build --help
示例：在启动之前运行 build 将数据库设置为 PostgreSQL
bin/kc.[sh|bat] build --db=postgres

第二步：使用 --optimized 启动 Keycloak

构建成功后，您可以启动 Keycloak 并关闭默认启动行为，方法是输入以下命令

bin/kc.[sh|bat] start --optimized <configuration-options>

--optimized 参数告诉 Keycloak 假设使用预构建的、已优化的 Keycloak 映像。 结果，Keycloak 避免在启动时直接检查和运行构建，从而节省了时间。

您可以在启动时输入所有配置选项；这些选项是 所有配置 中 **未** 用工具图标标记的选项。

  • 如果在启动时发现构建选项的值等于输入 build 时使用的值，则在使用 --optimized 参数时该选项将被静默忽略。

  • 如果该选项的值与输入构建时使用的值不同，则日志中会显示警告，并使用之前构建的值。 要使此值生效，请在启动之前运行新的 build。

创建优化的构建

以下示例显示了创建优化的构建，然后在启动 Keycloak 时使用 --optimized 参数。

  1. 使用构建命令设置 PostgreSQL 数据库供应商的构建选项

    bin/kc.[sh|bat] build --db=postgres

  2. 在 conf/keycloak.conf 文件中设置 postgres 的运行时配置选项。

    db-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.com
https-certificate-file

  3. 使用优化参数启动服务器

    bin/kc.[sh|bat] start --optimized

您可以通过使用 build 命令实现启动和运行时行为的大多数优化。 此外，通过使用 keycloak.conf 文件作为配置源，您可以避免启动时的一些步骤，否则这些步骤将需要命令行参数，例如初始化 CLI 本身。 结果，服务器启动速度更快。

基本概念

本节概述了 Keycloak 使用的基本概念，特别是在优化启动方面。

Keycloak 在幕后使用 Quarkus 框架和重新增强/可变 jar 方法。 此过程在运行 build 命令时开始。

以下是 build 命令执行的一些优化

  • 创建关于已安装提供者的新的封闭世界假设，这意味着在每次 Keycloak 启动时无需重新创建注册表和初始化工厂。

  • 预先解析配置文件，以减少启动服务器时的 I/O。

  • 配置和准备特定于数据库的资源，以针对特定数据库供应商运行。

  • 通过将构建选项持久化到服务器映像中，服务器不会执行任何其他步骤来解释配置选项和（重新）配置自身。

您可以在特定 Quarkus 指南 中阅读更多内容

在本页
编辑本指南