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

.. _component-2fa-helpdesk:

2FA Helpdesk
============

This section provides and overview of the *2FA Helpdesk* component in Nubus for Kubernetes.
It describes the following components in detail:

#. :ref:`component-2fa-helpdesk-frontend`
#. :ref:`component-2fa-helpdesk-backend`

:numref:`component-2fa-helpdesk-figure` shows the *2FA Helpdesk* components,
their relationship among each other and to other functional components in Nubus.
The upcoming sections add the behavior level for each of the components.

.. _component-2fa-helpdesk-figure:

.. figure:: /images/Functional_component_2FA_Helpdesk.*
   :target: ../_images/Functional_component_2FA_Helpdesk.svg
   :alt: ArchiMate view for 2FA Helpdesk component
   :width: 550px

   ArchiMate view for 2FA Helpdesk component

.. seealso::

   :external+uv-nubus-kubernetes-operation:ref:`conf-2fa-authentication-groups`
      in :cite:t:`uv-nubus-kubernetes-operation`
      for information for operators
      about how to configure *2FA Helpdesk*.

   In :cite:t:`uv-nubus-manual`:

   :external+uv-nubus-manual:ref:`2fa-admin`
      for information for functional administrators
      about how to use the *2FA Administrator Helpdesk*.

   :external+uv-nubus-manual:ref:`2fa-self-service`
      for information for end users
      about how to use the *2FA Self Service*.

.. _component-2fa-helpdesk-frontend:

2FA Helpdesk Frontend
---------------------

:numref:`component-2fa-helpdesk-frontend-fig` shows the *2FA Helpdesk Frontend*
and the behavior of its parts. It has the following main components:

2FA Self Service
   The *2FA Self Service* is the frontend for end users
   that allows them to reset their personal 2FA token.

2FA Administrator Helpdesk
   The *2FA Administrator Helpdesk* is the frontend for functional administrators.
   It allows them to reset the 2FA token on behalf of end users
   to restore access for them.

Both frontend components run in the user's web browser.
They have in common
that they serve the UI elements for the *2FA Helpdesk*
and run the frontend as single page application.

Depending on the requesting user,
the user either only sees the portal tile for the *2FA Self Service*
or additionally the portal tile for the *2FA Administrator Helpdesk*.
The container image with the *2FA Helpdesk Frontend* delivers the static files,
such as CSS, JavaScript, and HTML.

.. _component-2fa-helpdesk-frontend-fig:

.. figure:: /images/Functional_component_2FA_Helpdesk_Frontend.*
   :target: ../_images/Functional_component_2FA_Helpdesk_Frontend.svg
   :alt: ArchiMate view for 2FA Helpdesk Frontend component

   ArchiMate view for 2FA Helpdesk Frontend component

.. _component-2fa-helpdesk-backend:

2FA Helpdesk Backend
--------------------

:numref:`component-2fa-helpdesk-backend-fig` shows the *2FA Helpdesk Backend* and the behavior of its parts.
The backend server HTTP endpoints validate the role of the requesting user
and trigger a reset of a 2FA token.
To reset a token, the *2FA Helpdesk Backend* sends an appropriate request to *Keycloak* in the *Identity Provider*.
Keycloak resets the token and upon the next sign-in asks the user to set up a new 2FA token.

For authentication with *Keycloak*,
the *2FA Helpdesk Backend* uses OpenID Connect.

The *2FA Helpdesk Backend* has no data persistence.
It requests all information about users and 2FA tokens from *Keycloak*.

.. _component-2fa-helpdesk-backend-fig:

.. figure:: /images/Functional_component_2FA_Helpdesk_Backend.*
   :target: ../_images/Functional_component_2FA_Helpdesk_Backend.svg
   :alt: ArchiMate view for 2FA Helpdesk Backend component
   :width: 500px

   ArchiMate view for 2FA Helpdesk Backend component