配置 TLS

了解如何为传入和传出请求配置 Keycloak 的 https 证书。

传输层安全协议(简称:TLS)对于通过安全通道交换数据至关重要。对于生产环境,您绝不应该通过 HTTP 暴露 Keycloak 端点,因为敏感数据是 Keycloak 与其他应用程序交换的核心内容。在本指南中,您将学习如何配置 Keycloak 以使用 HTTPS/TLS。

Keycloak 可以配置为使用 PEM 格式的文件或 Java 密钥库加载所需的证书基础设施。当两种方式都配置时,PEM 文件优先于 Java 密钥库。

以 PEM 格式提供证书

当您使用一对匹配的 PEM 格式证书和私钥文件时,您可以通过运行以下命令配置 Keycloak 以使用它们

bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem

Keycloak 会在内存中从这些文件创建一个密钥库,并在之后使用此密钥库。

提供密钥库

当没有显式配置密钥库文件,但 http-enabled 设置为 false 时,Keycloak 会查找 conf/server.keystore 文件。

作为替代方案,您可以使用现有的密钥库,方法是运行以下命令

bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file

密钥库的可识别文件扩展名

  • .p12.pkcs12.pfx 用于 pkcs12 文件

  • .jks.keystore 用于 jks 文件

  • .key.crt.pem 用于 pem 文件

如果您的密钥库没有与其文件类型匹配的扩展名,您还需要设置 https-key-store-type 选项。

设置密钥库密码

您可以使用 https-key-store-password 选项为您的密钥库设置安全密码

bin/kc.[sh|bat] start --https-key-store-password=<value>

如果未设置密码,则使用默认密码 password

保护凭据安全

避免使用 CLI 或将其添加到 conf/keycloak.conf 文件中以明文形式设置密码。而是使用最佳实践,例如使用 vault / 挂载的 secret。有关更多详细信息,请参阅 使用 vault为生产环境配置 Keycloak

配置 TLS 协议

默认情况下,Keycloak 不启用已弃用的 TLS 协议。如果您的客户端仅支持已弃用的协议,请考虑升级客户端。但是,作为临时解决方法,您可以通过运行以下命令启用已弃用的协议

bin/kc.[sh|bat] start --https-protocols=<protocol>[,<protocol>]

要同时允许 TLSv1.2,请使用如下命令:kc.sh start --https-protocols=TLSv1.3,TLSv1.2

切换 HTTPS 端口

Keycloak 在端口 8443 上监听 HTTPS 流量。要更改此端口,请使用以下命令

bin/kc.[sh|bat] start --https-port=<port>

证书和密钥重新加载

默认情况下,Keycloak 将每小时重新加载 https-* 选项中指定的证书、密钥和密钥库。对于服务器密钥可能需要频繁轮换的环境,这允许在无需服务器重启的情况下进行轮换。您可以通过 https-certificates-reload-period 选项覆盖默认值。重新加载密钥库、信任库和 https-* 选项引用的证书文件的间隔。该值可以是 java.time.Duration 值、整数秒数或后跟时间单位 [ms, h, m, s, d] 的整数。必须大于 30 秒。使用 -1 禁用。

相关选项

http-enabled

启用 HTTP 监听器。

在开发模式下默认启用。通常在生产环境中不启用,除非服务器前面有 TLS 终止代理。

CLI: --http-enabled
Env: KC_HTTP_ENABLED

true, false (默认)

https-certificate-file

PEM 格式的服务器证书或证书链的文件路径。

CLI: --https-certificate-file
Env: KC_HTTPS_CERTIFICATE_FILE

https-certificate-key-file

PEM 格式的私钥文件路径。

CLI: --https-certificate-key-file
Env: KC_HTTPS_CERTIFICATE_KEY_FILE

https-certificates-reload-period

重新加载密钥库、信任库和 https-* 选项引用的证书文件的间隔。

可以是 java.time.Duration 值、整数秒数或后跟 [ms, h, m, s, d] 之一的整数。必须大于 30 秒。使用 -1 禁用。

CLI: --https-certificates-reload-period
Env: KC_HTTPS_CERTIFICATES_RELOAD_PERIOD

1h (默认)

https-cipher-suites

要使用的密码套件。

如果未给出,则选择合理的默认值。

CLI: --https-cipher-suites
Env: KC_HTTPS_CIPHER_SUITES

https-key-store-file

保存证书信息的密钥库,而不是指定单独的文件。

CLI: --https-key-store-file
Env: KC_HTTPS_KEY_STORE_FILE

https-key-store-password

密钥库文件的密码。

CLI: --https-key-store-password
Env: KC_HTTPS_KEY_STORE_PASSWORD

password (默认)

https-key-store-type

密钥库文件的类型。

如果未给出,则根据文件扩展名自动检测类型。如果 fips-mode 设置为 strict 且未设置值,则默认为 BCFKS

CLI: --https-key-store-type
Env: KC_HTTPS_KEY_STORE_TYPE

https-port

使用的 HTTPS 端口。

CLI: --https-port
Env: KC_HTTPS_PORT

8443 (默认)

https-protocols

要显式启用的协议列表。

CLI: --https-protocols
Env: KC_HTTPS_PROTOCOLS

[TLSv1.3,TLSv1.2] (默认)

管理服务器

https-management-certificate-file

PEM 格式的管理服务器的服务器证书或证书链的文件路径。

如果未给出,则该值从 HTTP 选项继承。仅当在管理界面上暴露某些内容时才相关 - 请参阅指南了解详细信息。

CLI: --https-management-certificate-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_FILE

https-management-certificate-key-file

PEM 格式的管理服务器的私钥文件路径。

如果未给出,则该值从 HTTP 选项继承。仅当在管理界面上暴露某些内容时才相关 - 请参阅指南了解详细信息。

CLI: --https-management-certificate-key-file
Env: KC_HTTPS_MANAGEMENT_CERTIFICATE_KEY_FILE

https-management-certificates-reload-period

重新加载管理服务器的 https-management-* 选项引用的密钥库、信任库和证书文件的间隔。

可以是 java.time.Duration 值、整数秒数或后跟 [ms, h, m, s, d] 之一的整数。必须大于 30 秒。使用 -1 禁用。如果未给出,则该值从 HTTP 选项继承。仅当在管理界面上暴露某些内容时才相关 - 请参阅指南了解详细信息。

CLI: --https-management-certificates-reload-period
Env: KC_HTTPS_MANAGEMENT_CERTIFICATES_RELOAD_PERIOD

1h (默认)

https-management-key-store-file

保存证书信息的密钥库,而不是为管理服务器指定单独的文件。

如果未给出,则该值从 HTTP 选项继承。仅当在管理界面上暴露某些内容时才相关 - 请参阅指南了解详细信息。

CLI: --https-management-key-store-file
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_FILE

https-management-key-store-password

管理服务器的密钥库文件的密码。

如果未给出,则该值从 HTTP 选项继承。仅当在管理界面上暴露某些内容时才相关 - 请参阅指南了解详细信息。

CLI: --https-management-key-store-password
Env: KC_HTTPS_MANAGEMENT_KEY_STORE_PASSWORD

password (默认)

在此页面上