管理界面配置

了解如何为指标和健康检查等端点配置 Keycloak 的管理界面。

管理界面允许通过与主 HTTP 服务器不同的 HTTP 服务器访问管理端点。它提供隐藏外部世界中的端点(例如 /metrics/health)的可能性,从而加强安全性。最显著的优势可能在 Kubernetes 环境中看到,因为特定的管理端口可能不会公开。

管理界面配置

当管理界面上公开了一些内容时,管理界面就会开启。当启用指标和健康检查时,/metrics/health 等管理端点将默认在管理端口 9000 上公开。管理界面提供一组选项,并且是完全可配置的。

如果管理界面属性未显式设置,则其值将自动从默认 HTTP 服务器继承。

端口

要更改管理界面的端口,可以使用 Keycloak 选项 http-management-port

相对路径

您可以更改管理界面的相对路径,因为管理端点的前缀路径可能不同。您可以通过 Keycloak 选项 http-management-relative-path 来实现。

例如,如果您设置 CLI 选项 --http-management-relative-path=/management,则指标和健康检查端点将在 /management/metrics/management/health 路径上访问。

当指定相对路径时,用户会自动重定向到 Keycloak 托管的路径。这意味着当将相对路径设置为 /management 时,并且用户访问 localhost:9000/ 时,页面将重定向到 localhost:9000/management

如果您没有显式设置它的值,则将使用 http-relative-path 属性的值。例如,如果您设置 CLI 选项 --http-relative-path=/auth,则这些端点可以在 /auth/metrics/auth/health 路径上访问。

TLS 支持

当为默认 Keycloak 服务器设置 TLS 时,管理界面也将通过 HTTPS 访问。管理界面只能在 HTTP 或 HTTPS 上运行,不能像主服务器一样同时运行在两者上。

为管理 HTTP 服务器设置不同 TLS 参数,提供了一组以 https-management-* 为前缀的特定 Keycloak 管理界面选项。它们的功能与主 HTTP 服务器的对应选项类似,有关详细信息,请参阅 配置 TLS。当这些选项未显式设置时,TLS 参数将从默认 HTTP 服务器继承。

禁用管理界面

当管理界面上没有任何内容公开时,管理界面会自动关闭。目前,只有健康检查和指标在管理界面上公开,无论如何。如果您要禁用在管理界面上公开它们,请将 Keycloak 属性 legacy-observability-interface 设置为 true

出于安全原因,不建议在默认服务器上公开健康检查和指标端点,您应该始终使用管理界面。注意,legacy-observability-interface 选项已弃用,将在未来的版本中删除。它只允许您为迁移提供更多时间。

相关选项

http-management-port

管理界面的端口。

仅在管理界面上公开了一些内容时才相关 - 请参阅指南了解详细信息。

CLI: --http-management-port
Env: KC_HTTP_MANAGEMENT_PORT

9000 (默认)

http-management-relative-path

设置相对于 / 的路径,用于从管理界面提供资源。

路径必须以 / 开头。如果未给出,则该值将从 HTTP 选项继承。仅在管理界面上公开了一些内容时才相关 - 请参阅指南了解详细信息。

CLI: --http-management-relative-path
Env: KC_HTTP_MANAGEMENT_RELATIVE_PATH

/ (默认)

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

配置管理界面以要求/请求客户端身份验证。

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

CLI: --https-management-client-auth
Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH

none (默认), request, required

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 (默认)

legacy-observability-interface

如果指标/健康检查端点应该在主 HTTP 服务器上公开(不推荐)。

如果设置为 true,则管理界面将被禁用。

CLI: --legacy-observability-interface
Env: KC_LEGACY_OBSERVABILITY_INTERFACE

已弃用。

true, false (默认)

在本页