From d5066509a28bbda1aaeebc361bf97126e003cd9d Mon Sep 17 00:00:00 2001 From: Alex Szczuczko Date: Thu, 28 May 2026 02:07:19 -0600 Subject: [PATCH] Clarify documentation of OS-level dependencies for Kerberos (#45764) Closes #32527 Signed-off-by: Alex Szczuczko --- .../server_admin/topics/authentication/kerberos.adoc | 4 ++-- docs/guides/migration/migrating-to-quarkus.adoc | 5 +++++ docs/guides/server/containers.adoc | 1 + 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/documentation/server_admin/topics/authentication/kerberos.adoc b/docs/documentation/server_admin/topics/authentication/kerberos.adoc index 56a3a411459..6d3f483be20 100644 --- a/docs/documentation/server_admin/topics/authentication/kerberos.adoc +++ b/docs/documentation/server_admin/topics/authentication/kerberos.adoc @@ -58,10 +58,10 @@ Ensure the keytab file `/tmp/http.keytab` is accessible on the host where {proje [[_server_setup]] -Install a Kerberos client on your machine. +Configure a Kerberos client on your machine. .Procedure -. Install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the link:https://www.freeipa.org/page/Downloads[freeipa-client] package, containing a Kerberos client and other utilities. +. Optionally, install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the link:https://www.freeipa.org/page/Downloads[freeipa-client] package, containing a Kerberos client and other utilities. Installing this package will supply you with tools and sensible defaults, but it is not required for JGSS Kerberos to function within {project_name}. . Configure the Kerberos client (on Linux, the configuration settings are in the link:https://web.mit.edu/kerberos/krb5-1.21/doc/admin/conf_files/krb5_conf.html[/etc/krb5.conf] file ). + Add your Kerberos realm to the configuration and configure the HTTP domains your server runs on. diff --git a/docs/guides/migration/migrating-to-quarkus.adoc b/docs/guides/migration/migrating-to-quarkus.adoc index 9eaed4fc606..20011d7c0e2 100644 --- a/docs/guides/migration/migrating-to-quarkus.adoc +++ b/docs/guides/migration/migrating-to-quarkus.adoc @@ -75,6 +75,11 @@ While the WildFly distribution automatically discovered custom providers, even s Depending on what APIs your providers use you may also need to make some changes to the providers. If you only leveraged classes from Keycloak SPIs you shouldn't need to, but if you used other APIs from WildFly you may need to make some changes. In addition, JavaEE APIs like session/stateless beans are no longer supported. +== Migrating containers + +The container images for the Quarkus distribution derive from UBI Micro instead of UBI Minimal. This means that some binaries or configuration files (those not necessary for Keycloak's main functionality) may be missing. The solution is to add these files in as part of the container customization process explained in the https://www.keycloak.org/server/containers[Container guide]. + +For example, for the Kerberos authentication features you will need to add `/etc/krb5.conf`. The `krb5-libs` RPM previously supplied this file, but was removed in the switch to UBI Micro. Note that binaries from `krb5-libs` are not required for Keycloak's Kerberos authentication features to work. == Migrating using the Operator diff --git a/docs/guides/server/containers.adoc b/docs/guides/server/containers.adoc index 2781a4562e8..df552edb0d7 100644 --- a/docs/guides/server/containers.adoc +++ b/docs/guides/server/containers.adoc @@ -105,6 +105,7 @@ First, consider if your use case can be implemented in a different way, and so a * A `+RUN curl+` instruction in your Containerfile can be replaced with `+ADD+`, since that instruction natively supports remote URLs. * Some common CLI tools can be replaced by creative use of the Linux filesystem. For example, `+ip addr show tap0+` becomes `+cat /sys/class/net/tap0/address+` * Tasks that need RPMs can be moved to a former stage of an image build, and the results copied across instead. +* The Kerberos features of {project_name} do not require the binary parts of `krb5-libs` to be installed. Instead you can `+ADD+` just the relevant text configuration files, e.g. `/etc/krb5.conf`. Here is an example. Running `+update-ca-trust+` in a former build stage, then copying the result forward: