Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 25 additions & 5 deletions appendix/single-sign-on.rst
Original file line number Diff line number Diff line change
Expand Up @@ -596,15 +596,27 @@ 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. Run it from the stack's
directory:

.. 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
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.

$ sudo chmod 0400 local/zammad-sso/zammad.keytab
.. 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:
Expand Down Expand Up @@ -755,7 +767,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
"""""""""""""""""""""""""""
Expand Down Expand Up @@ -1006,6 +1019,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 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
issues the Kerberos challenge. It cannot verify the key itself. Check
Expand Down
Loading