.. /*  
    * This file is part of the SavaPage project <https://www.savapage.org>.
    * Copyright (c) 2026 Datraverse B.V.
    * Author: Rijk Ravestein.
    *
    * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. <info@datraverse.com>
    * SPDX-License-Identifier: CC-BY-SA-4.0
    *
    * For more information, please contact Datraverse B.V. at this
    * address: info@datraverse.com
    */

.. _ch-webapp-user:

.. figure:: ../images/manual/savapage-logo-no-text-100px.png
   :width: 75px

User Web App
============

.. admonition:: |ADMONITION_TABLE_OF_CONTENTS|

   - :numref:`{number}. {name} <ch-webapp-user-login>`
   - :numref:`{number}. {name} <ch-webapp-user-login-alternatives>`
   - :numref:`{number}. {name} <ch-webapp-user-main>`
   - :numref:`{number}. {name} <ch-webapp-user-main-pdf>`
   - :numref:`{number}. {name} <ch-webapp-user-main-print>`
   - :numref:`{number}. {name} <ch-webapp-user-main-letterheads>`
   - :numref:`{number}. {name} <ch-webapp-user-main-delete>`
   - :numref:`{number}. {name} <ch-webapp-user-main-log>`
   - :numref:`{number}. {name} <ch-webapp-user-sort>`
   - :numref:`{number}. {name} <ch-webapp-user-main-user-details>`
   - :numref:`{number}. {name} <ch-webapp-user-main-upload>`
   - :numref:`{number}. {name} <ch-webapp-user-main-upload-dropzone>`
   - :numref:`{number}. {name} <ch-webapp-user-main-gdpr>`


The User Web App can be reached at |RST_URL_SERVER_PATH_USER|. For
all URL options see |RST_LINK_APPENDIX_URL_CHEAT_SHEET|. 

.. important::

   When using the User Web App concurrently with the |RST_LINK_USER_CLIAPP|
   and :ref:`Proxy Print Authentication <ch-webapp-admin-devices-card-reader-proxy-print-auth>`
   you are strongly advised to use an external database like PostgreSQL.
   See :ref:`Using an External Database <ch-external-db>`.


.. _ch-webapp-user-login:

Login
-----

.. contents::
   :depth: 2
   :local:

Dialog
~~~~~~

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login.png
   :alt: Web App: Login Dialog
   :width: 400
   
   Web App: Login Dialog

.. note::

   When a user opens the Web App the login dialog is skipped when an
   :ref:`Authentication Token <ch-security-auth-tokens>` is present in
   *local storage* of the browser. The login dialog is also skipped when
   the Web App is opened from a trusted and authenticated
   |RST_LINK_USER_CLIAPP| or with a 
   :ref:`One-Time Authentication Token <xmlrpc_onetime-auth_createToken>`.

   For a description of the global user authentication defaults see
   :ref:`User Authentication <ch-webapp-admin-options-user-auth>`.

-  The language of the dialog defaults to the language setting of the
   browser.

-  You can overrule the default language and country or preselect a user
   by using the URL parameters. See |RST_LINK_APPENDIX_URL_CHEAT_SHEET|.
   
-  Version and copyright information is shown when you press the 
   |RST_BUTTON_ABOUT| button. See |RST_LINK_USER_ABOUT|.

-  You can choose an alternative language by pressing the |RST_BUTTON_LANGUAGE|
   button. See :ref:`Select Language <ch-webapp-user-login-select-language>`.

-  The top of the Login dialog can be customized: see 
   :ref:`Custom HTML <ch-custom-webapp-html>`.

-  Use the |RST_BUTTON_EYE_SYMBOL| button on the right side of the
   |RST_GUILABEL_PASSWORD| entry field to show/hide the password.

-  :ref:`Login Alternatives <ch-webapp-user-login-alternatives>` appear at
   the bottom of the dialog.

-  :ref:`Rate Limiting <ch-security-rate-limiting>` is applied to login
   failures.

Some invariants:

-  Only a :ref:`Person <ch-auth-print-key-concepts-person>` can login.

-  :ref:`Disabled users <ch-webapp-admin-user-edit>` are not allowed to
   log in.

-  The internal ``admin`` user is not allowed to log in as user.

-  As long as :ref:`system setup <ch-install-configure-login>` is needed
   user login attempts are blocked with a message saying “Application
   setup is required”.

-  When the system is in :ref:`Maintenance Mode <ch-webapp-admin-dashboard-status>`, 
   access is restricted to users with Administrator role. Regular users are shown
   a message explaining the situation at this Login dialog, or after login in the
   authorized session.

.. tip::

   |RST_GUILABEL_USER_NAME| can be an *alias*.
   See :ref:`User Name Aliases <ch-auth-print-user-name-aliases>`.

.. _ch-webapp-user-login-about:

About
~~~~~

The About dialog shows version and copyright information. The top of the
dialog can be customized: see :ref:`Custom HTML <ch-custom-webapp-html>`.

.. note::

   The dialog contains a Printer Driver section with a download link for
   the CUPS :ref:`SAVAPAGE.ppd <ch-printer-postscript-driver>` file. This
   section can be enabled or disabled by setting the configuration key
   ``webapp.about.driver-download.enable`` to ``Y`` or ``N``. 
   See |RST_LINK_CONFIG_EDITOR| on how to change this value.

.. _ch-webapp-user-login-select-language:

Select Language
~~~~~~~~~~~~~~~

.. figure:: ../images/manual/screenshots/user/sp-00-01-user-select-language.png
   :width: 400
   
   Web App: Select Language Dialog


-  At the moment :ref:`English, French, German, Swedish, Chinese (Traditional, Taiwan) and Dutch <ch-i18n>`
   are fully supported. Press the language of your choice. This will reload the login dialog
   in the newly selected language.

-  Press |RST_BUTTON_CANCEL| to return to the login dialog.

.. note::

   You can use the ``webapp.language.available`` configuration property
   to enter a comma separated list of selectable ISO 639 language codes.
   For instance: ``de,en,fr,es,ru,nl``. See |RST_LINK_CONFIG_EDITOR|
   on how to enter this value.

   When the list is restricted to a single language, the |RST_BUTTON_LANGUAGE| button
   is not shown in the :ref:`Login <ch-webapp-user-login>` dialog, and
   the Web App Locale is set to the single available language.

.. _ch-webapp-user-login-self-registration:

Self Registration
~~~~~~~~~~~~~~~~~

If :ref:`User Self Registration <ch-webapp-admin-options-internal-users>`
is enabled a |RST_BUTTON_REGISTER| button is displayed.

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login-register-button.png
   :width: 400
   
   Web App: Register Option

If |RST_BUTTON_REGISTER| is pressed, registration data can be entered.

.. note::

   :ref:`Rate Limiting <ch-security-rate-limiting>` is applied before the
   Registration dialog is shown. This could result in a message that
   registration is currently unavailable. In that case, try again later.

Press |RST_BUTTON_SEND| for verification to the specified Email adress. This address
must match one of the approved domains. See :ref:`Internal Users <ch-webapp-admin-options-internal-users>`.
For email customization see :ref:`UserRegVerification <ch-custom-email-msg-type-user-reg-verification>`.

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login-register.png
   :width: 400
   
   Web App: Register Dialog

A prefix, in this case |RST_GUILABEL_GUEST_PREFIX|, is applied to the User Name / ID to
distinguish registered :ref:`Internal Users <ch-webapp-admin-options-internal-users>`
from users synced from a :ref:`User Source <ch-webapp-admin-options-user-source>`.
The prefix and other parameters are held as configuration property, as
explained in :ref:`Create Internal User <ch-webapp-admin-user-create-internal>`.

By pressing |RST_BUTTON_SEND| a verification link is send to the specified Email
adress. The address must match one of the approved domains. See
:ref:`Internal Users <ch-webapp-admin-options-internal-users>`. For email
customization see :ref:`UserRegVerification <ch-custom-email-msg-type-user-reg-verification>`.

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-registration-email.png
   :width: 500
   
   Self Registration Verification Email


The status of the verification (Pending or Expired) is shown in the User
List. See :ref:`Registration Requests <ch-webapp-admin-user-list-self-registration-requests>`.

After the user follows the link in the verification email, the
registration is completed.

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-registration-completed.png
   :width: 400
   
   Self Registration Completed


.. _ch-webapp-user-login-single-webapp-session:

Single Web App Session
~~~~~~~~~~~~~~~~~~~~~~

A warning message is shown when a *desktop*  [1]_ user tries to open
the *same* Web App type a second time in the same browser instance. In
rare occasions, for instance, due to network connectivity issues, this
statement might be false. In that case a Login will bring you back on
track.

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login-webapp-session-detected.png
   :width: 400
   
   Same type Web App session detected


When a user opens a second Web App session of *another* type this
message is shown:

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login-webapp-session-change.png
   :width: 400
   
   Web App type change detected


In both situations, either go back to the active Web App session or
press Login to login to the intended Web App type. This will invalidate
any other SavaPage session in the same browser instance.

.. [1]
   The Single Web App Session check is solely done for certain *desktop*
   browser sessions. Sessions on macOS and mobile devices are *not*
   checked.

.. _ch-webapp-user-login-card-self-assoc-dialog:

Card Self Association Dialog
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If an unknown card is swiped, and NFC Card :ref:`Self Association <ch-webapp-admin-options-user-auth>`
is enabled, the user is presented this dialog to associate the new card.

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login-card-self-assoc.png
   :width: 400
   
   Web App: Login Dialog - Card Self Association


There is a time limit to enter the |RST_GUILABEL_USER_NAME| and |RST_GUILABEL_PASSWORD|.
The remaining seconds are shown and when counted down to zero the dialog is
automatically closed. The time limit (seconds) is contained in configuration key 
``webapp.card-assoc.dialog-max-secs``. See |RST_LINK_CONFIG_EDITOR| on how to change this value.

.. _ch-webapp-user-login-2-step:

2-Step Verification
~~~~~~~~~~~~~~~~~~~

If a user enabled :ref:`2-Step Verification <ch-webapp-user-main-user-details-authentication>`,
they are prompted to enter their verification code, after a successful first login step.

.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login-2-step.png
   :width: 400
   
   Web App: Login Dialog - 2-Step Verification

 
.. figure:: ../images/manual/screenshots/user/sp-00-00-user-login-2-step-recover.png
   :width: 400
   
   Web App: Login Dialog - 2-Step Verification (recovery)