From 86d893c9aea301dbfc5e6b464a6f8bce8fd7feb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Silke=20Ja=CC=88nichen?= Date: Mon, 16 Nov 2026 20:48:16 +0100 Subject: [PATCH 1/2] Maintenance: Set the SSO keytab permissions in a way that works with rootless Docker. The Docker section of the SSO guide set the keytab's owner and mode with sudo chown 33 on the host. With a rootless Docker daemon, user ID 33 inside the container maps to a different user ID on the host, so the container could not read the keytab and never became healthy. The guide now sets owner and mode from a throwaway container, which works with rootful and rootless daemons alike, warns against making the keytab world-readable, and adds a troubleshooting entry for an unhealthy SSO container. --- appendix/single-sign-on.rst | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/appendix/single-sign-on.rst b/appendix/single-sign-on.rst index 3aae3348..b84c4c2c 100644 --- a/appendix/single-sign-on.rst +++ b/appendix/single-sign-on.rst @@ -596,15 +596,26 @@ The SSO container consists of the following files next to the stack's Keep the keytab out of the build context: Docker reads every file in ``zammad-sso/`` when it builds the image, and a keytab that only the container's user may read makes the build fail. The container runs as -``www-data`` with user ID 33, so on a Linux host: +``www-data`` with user ID 33, so give the keytab to that user and make it +readable for nobody else. Do this from a throwaway container, which works +with a rootful as well as a rootless Docker daemon: .. code-block:: console - $ sudo chown 33 local/zammad-sso/zammad.keytab + $ docker run --rm -v "$PWD/local/zammad-sso:/k" alpine \ + sh -c 'chown 33 /k/zammad.keytab && chmod 0400 /k/zammad.keytab' -.. code-block:: console +.. note:: With a rootless Docker daemon, user ID 33 inside a container is a + different user ID on the host. ``chown 33`` on the host therefore fails or + gives the keytab to the wrong user, and the container cannot read it. + + Don't make the keytab readable for everyone (mode ``0644``) instead: + anyone who can read it can act as the Zammad service towards Active + Directory. - $ sudo chmod 0400 local/zammad-sso/zammad.keytab + Afterwards, your own user on the host can no longer read the keytab. To + replace it, delete it, copy the new one in its place and run the command + again. ``zammad-sso/Dockerfile`` builds Apache with ``mod_auth_gssapi`` from the Debian packages and runs it unprivileged: @@ -755,7 +766,8 @@ Then build and start the stack: The ``zammad-sso`` container reports ``healthy`` once the keytab is readable and Apache answers ``/auth/sso`` with the Kerberos challenge. If it stays -unhealthy, the keytab is missing or not readable by user ID 33. +unhealthy, the keytab is missing or not readable by user ID 33 inside the +container. Configure the Reverse Proxy """"""""""""""""""""""""""" @@ -1006,6 +1018,13 @@ Docker Stack Proxy IPs**. Restart the services that trust the proxy: ``docker compose restart zammad-railsserver zammad-websocket``. +The ``zammad-sso`` container stays unhealthy + Check whether the container's user can read the keytab: ``docker compose + exec zammad-sso klist -k /etc/apache2/zammad.keytab``. If it reports + "Permission denied while starting keytab scan", the keytab's owner or mode + was set on the host, which does not work with a rootless Docker daemon. + Set them from a container as described in :ref:`sso-docker`. + Signing in via SSO fails although the ``zammad-sso`` container is healthy The health check verifies that the keytab is readable and that Apache issues the Kerberos challenge. It cannot verify the key itself. Check From 5770eeb78e93fa151c2ced77dd316cd74bbd5a63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Silke=20Ja=CC=88nichen?= Date: Wed, 18 Nov 2026 21:33:36 +0100 Subject: [PATCH 2/2] Maintenance: Address review of the rootless keytab permissions. --- appendix/single-sign-on.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/appendix/single-sign-on.rst b/appendix/single-sign-on.rst index b84c4c2c..11bd134c 100644 --- a/appendix/single-sign-on.rst +++ b/appendix/single-sign-on.rst @@ -598,24 +598,25 @@ Keep the keytab out of the build context: Docker reads every file in container's user may read makes the build fail. The container runs as ``www-data`` with user ID 33, so give the keytab to that user and make it readable for nobody else. Do this from a throwaway container, which works -with a rootful as well as a rootless Docker daemon: +with a rootful as well as a rootless Docker daemon. Run it from the stack's +directory: .. code-block:: console $ docker run --rm -v "$PWD/local/zammad-sso:/k" alpine \ sh -c 'chown 33 /k/zammad.keytab && chmod 0400 /k/zammad.keytab' +Afterwards, your own user on the host can no longer read the keytab. To +replace it, delete it, copy the new one in its place and run the command +again. + .. note:: With a rootless Docker daemon, user ID 33 inside a container is a different user ID on the host. ``chown 33`` on the host therefore fails or gives the keytab to the wrong user, and the container cannot read it. - Don't make the keytab readable for everyone (mode ``0644``) instead: - anyone who can read it can act as the Zammad service towards Active - Directory. - - Afterwards, your own user on the host can no longer read the keytab. To - replace it, delete it, copy the new one in its place and run the command - again. +.. warning:: Don't solve the permission problem by making the keytab readable + for everyone (mode ``0644``): anyone who can read it can act as the Zammad + service towards Active Directory. ``zammad-sso/Dockerfile`` builds Apache with ``mod_auth_gssapi`` from the Debian packages and runs it unprivileged: @@ -1021,9 +1022,9 @@ Docker Stack The ``zammad-sso`` container stays unhealthy Check whether the container's user can read the keytab: ``docker compose exec zammad-sso klist -k /etc/apache2/zammad.keytab``. If it reports - "Permission denied while starting keytab scan", the keytab's owner or mode - was set on the host, which does not work with a rootless Docker daemon. - Set them from a container as described in :ref:`sso-docker`. + "Permission denied while starting keytab scan", the keytab's owner was set + on the host, which does not work with a rootless Docker daemon. Set it from + a container as described in :ref:`sso-docker`. Signing in via SSO fails although the ``zammad-sso`` container is healthy The health check verifies that the keytab is readable and that Apache