配置 Keycloak

了解如何配置和启动 Keycloak

本指南解释了 Keycloak 的配置方法，以及如何启动和应用首选配置。它包括优化 Keycloak 以实现更快启动和更低内存占用的配置指南。

配置 Keycloak 的来源

Keycloak 从四个来源加载配置，这些来源按应用顺序在此处列出。

  1. 命令行参数

  2. 环境变量

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

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

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

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

以下示例展示了如何在四个配置来源中设置 db-url 值

来源 格式

命令行参数

--db-url=cliValue

环境变量

KC_DB_URL=envVarValue

配置文件

db-url=confFileValue

Java KeyStore 文件

kc.db-url=keystoreValue

基于应用优先级，启动时使用的值是 cliValue，因为命令行具有最高优先级。

如果未使用 --db-url=cliValue，则应用的值将是 KC_DB_URL=envVarValue。如果该值既未通过命令行也未通过环境变量应用，则将使用 db-url=confFileValue。如果之前的任何值都未应用，则将使用值 kc.db-url=keystoreValue，因为它在可用配置来源中优先级最低。

配置格式

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

命令行参数格式

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

环境变量格式

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

配置文件格式

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

KeyStore 配置文件格式

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

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

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

以下示例展示了三个配置来源的 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 KeyStore 文件设置敏感选项

感谢 Keystore 配置源，您可以使用 [--config-keystore] 和 [--config-keystore-password] 选项直接从 Java KeyStore 加载属性。可选地，您可以使用 [--config-keystore-type] 选项指定 KeyStore 类型。默认情况下，KeyStore 类型为 PKCS12。

KeyStore 中的密钥需要使用 PBE（基于密码的加密）密钥算法存储，其中密钥从 KeyStore 密码派生而来。您可以使用以下 keytool 命令生成这样的 KeyStore

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

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

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

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 命令以应用此属性。有关 build 命令的详细信息，请参阅后续关于优化 Keycloak 的章节。

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

您还可以将 Quarkus 属性存储在 Java KeyStore 中。

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

在值中使用特殊字符

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

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

Windows 特有的注意事项

在配置值中指定 Windows 文件路径时，反斜杠也必须转义。例如，如果您想指定路径 C:\path\to\file，您应该将其写为 C:\\path\\to\\file。或者，您可以使用不需要转义的正斜杠：C:/path/to/file。

当使用 PowerShell 并且您的值包含逗号等特殊字符时，请在双引号周围使用单引号

.\kc.bat start --log-level='"INFO,org.hibernate:debug"'

PowerShell 处理引号的方式不同。它在将带引号的字符串传递给 kc.bat 脚本之前对其进行解释，从而删除外部引号字符。因此，需要额外的引号层来保留值结构。否则，逗号将被解释为分隔符。在 Windows CMD 中，您可以直接使用双引号。

启动 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 优化以获得最佳性能和运行时行为。

创建优化的 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 命令时可用）和 配置选项（在启动服务器时可用）。

对于非优化的 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. 使用 build 命令为 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. 使用 optimized 参数启动服务器

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

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

在 realm 配置中使用系统变量

某些 realm 功能允许管理员在配置 realm 及其组件时引用系统变量，例如环境变量和系统属性。

默认情况下，Keycloak 禁止使用系统变量，但仅允许使用通过 spi-admin-allowed-system-variables 配置选项显式指定的系统变量。此选项允许您指定逗号分隔的键列表，这些键最终将解析为来自具有相同键的系统变量的值。

  1. 启动服务器并将一组系统变量公开给服务器运行时

    bin/kc.[sh|bat] start --spi-admin-allowed-system-variables=FOO,BAR

在未来的版本中，此功能将被删除，以支持阻止在 realm 配置中使用任何系统变量。

底层概念

本节概述了 Keycloak 使用的底层概念，尤其是在优化启动方面。

Keycloak 在底层使用 Quarkus 框架和重新增强/可变 jar 方法。当运行 build 命令时，此过程将启动。

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

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

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

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

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

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

在此页面上
编辑本指南