.. SPDX-FileCopyrightText: 2024 - 2025 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _customize-keycloak:

Customization of Keycloak sign-in
=================================

.. dropdown:: Deployment — Kubernetes
   :color: info
   :icon: rocket

   This page refers to the Nubus for Kubernetes deployment.

This chapter describes how to customize the theme for the sign-in form provided by Keycloak,
the identity provider in Nubus for Kubernetes.
You need the Helm Chart for Nubus,
your customized :file:`custom_values.yaml` deployment file,
and the files for customization described in this chapter.

.. _customize-keycloak-theme:

Theme
-----

You can customize the following theme elements of Keycloak in Nubus:

* The theme of the sign-in form including a branding.
* Additional links at the bottom of the sign-in form.
* The cookie consent banner.

The sign-in form of Keycloak shares the theme with the Univention Portal.
For information about the customization of the portal,
see :ref:`customization-theme-portal`.

.. _customize-keycloak-additional-links:

Additional links
----------------

Operators can add links below the sign-in dialog,
for example to a password forgotten service,
or legal information.

To configure up to twelve addition links,
add them to the list :envvar:`nubusKeycloakBootstrap.bootstrap.loginLinks`
in your :file:`custom_values.yaml` deployment file.
Each item needs the following attributes:

:``link_number``: Consecutive number for the link determining the order.
:``description``: The label for the link.
:``language``: The language when the link applies.
:``href``: The target destination of the link.

See the example in :numref:`customize-keycloak-additional-links-listing`.

.. code-block:: yaml
   :caption: Add additional links to deployment file :file:`custom_values.yaml`
   :name: customize-keycloak-additional-links-listing

   nubusKeycloakBootstrap:
     bootstrap:
       loginLinks:
         - link_number: 1
           description: "Website"
           language: "en"
           href: "https://www.example.com/"
         - link_number: 2
           description: "Privacy"
           language: "en"
           href: "https://www.example.com/privacy"

.. _customize-keycloak-apply-changes:

Apply configuration changes
---------------------------

To apply and activate the configuration changes,
use the following steps:

#. To apply the updated configuration in your :file:`custom_values.yaml` deployment file to Nubus,
   run the commands shown in :numref:`customize-keycloak-apply-changes-listing`.

   .. code-block:: console
      :caption: Apply customization to Nubus
      :name: customize-keycloak-apply-changes-listing

      $ export NAMESPACE_FOR_NUBUS="Set to your Kubernetes namespace"
      $ export RELEASE_NAME="The Helm Chart release name"
      $ export VERSION="Your version of Nubus"
      $ helm upgrade \
         "$RELEASE_NAME" \
         --namespace="$NAMESPACE_FOR_NUBUS" \
         oci://artifacts.software-univention.de/nubus/charts/nubus \
         --values custom_values.yaml \
         --version "$VERSION"

#. To ensure that Keycloak applies the settings,
   you must restart the Kubernetes pod for the *UMC Gateway*,
   because it serves the required data to *Keycloak*.
   Run the commands shown in :numref:`customize-keycloak-restart-umc-gateway-listing`.

   .. code-block:: console
      :caption: Restart pod for *UMC Gateway* to apply customization
      :name: customize-keycloak-restart-umc-gateway-listing

      $ kubectl --namespace "$NAMESPACE_FOR_NUBUS" get pods | grep "umc-gateway"
      $ export NAME_OF_POD="Name of the pod in the output of the previous command."
      $ kubectl --namespace "$NAMESPACE_FOR_NUBUS" \
         delete pod $NAME_OF_POD