.. /*
    * 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-security-user-authentication:

User Authentication
-------------------

.. contents:: |RST_TABLE_OF_CONTENTS|
   :depth: 1
   :local:

This section discusses how user credentials are protected.

.. _ch-security-login-passwords-and-pin:

Login Passwords
~~~~~~~~~~~~~~~

This section is about the passwords and PIN codes entered in the Web App
Login Dialog.

.. tip::

   Users can use the HTTPS protocol for connecting to the Web App, so
   data is encrypted to and from the server.

.. _ch-security-login-passwords-user:

User Domain Passwords
^^^^^^^^^^^^^^^^^^^^^

|PRODUCT_NAME| does *not* store or cache user domain login passwords.
These passwords are always checked real-time at the source.

.. _ch-security-login-passwords-internal-user:

Internal User Passwords
^^^^^^^^^^^^^^^^^^^^^^^

Passwords of :ref:`Internal Users <ch-webapp-admin-options-internal-users>`
are stored as SHA1 hash in the database.

.. _ch-security-login-passwords-admin:

Internal Admin Password
^^^^^^^^^^^^^^^^^^^^^^^

The SHA1 hashed password of the internal administrator ``admin`` is
stored in a text file located at
``/opt/savapage/server/data/admin.properties``. Access to this file
is restricted to the ``savapage`` user.

SavaPage installs with ``admin`` as initial password for user
``admin``.

.. tip::

   If you forgot the internal admin password, you can reset it by
   editing the ``admin.password`` property in the
   ``/opt/savapage/server/data/admin.properties`` text file. Ignore
   the existing HASH value. |PRODUCT_NAME| will hash your password upon
   first use.

.. _ch-security-login-pin:

PIN Codes
~~~~~~~~~

:ref:`User PIN codes <ch-webapp-admin-user-edit>` are stored in the
database as :ref:`encrypted secret <ch-security-encrypted-secrets>`.

.. _ch-security-auth-tokens:

Authentication Tokens
~~~~~~~~~~~~~~~~~~~~~

When Authentication Persistence is enabled for Browser Local Storage,
authentication tokens are stored in the “Local Storage” of the browser.
See :ref:`User Authentication <ch-webapp-admin-options-user-auth>`.

Separate authentication tokens are held for the User, Admin, POS and Job
Tickets Web App context and the same token is used for different
sessions (on different devices) of a single user. A explicit logout in
the Web App destroys the token. Authentication tokens are managed in
memory on the |PRODUCT_NAME| server. So, when the server restarts all
local tokens are implicitly invalidated.

One-time Authentication Tokens
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Trusted Third Party (TTP) can acquire a one-time token for Web App
user authentication by calling an XML-RPC method. The expiration time of
the token should be as short as possible to minimize the risk that an
accidentally exposed token can be misused. See
:ref:`onetime-auth.createToken <xmlrpc_onetime-auth_createToken>` for
details.

.. _ch-security-user-dialog:

User Dialog
~~~~~~~~~~~

When authentication fails a neutral "Authentication failed" message is
communicated to the user to prevent “Account Enumeration” and “Guessable
User Account”.