.. /*
    * 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-auth-print-user-name-aliases:

User Name Aliases
-----------------

A User Alias is a way of mapping a user name in one format to a name in
another. It is useful in the following situations:

-  Providing extra convenience for users to log into the system with a
   user name formatted in a different way. So Georg Friedrich Händel can
   have a :ref:`User Alias <ch-auth-print-key-concepts-user-alias>` of
   “georg_handel”, “gf_handel”, and “gfhandel”.

-  Used as a temporary tool to manage domain or user name format
   changes. For example, you may have changed names from j.brown to
   john.brown. An alias can help forgetful users to log in with their
   old name.

Name aliases are applied at the following levels:

-  User Login to the User and Admin Web App.

-  Print jobs arriving under the alias name.

The aliases information is kept in the file, |br|
``/opt/savapage/server/data/conf/username-aliases.txt``

... and can be created based on the provided template file, |br|
``/opt/savapage/server/data/conf/username-aliases.txt.tmpl``

You can create your own custom alias file as follows:

-  Go to the directory ``/opt/savapage/server/data/conf/``

-  Open your favorite text editor with the file
   ``username-aliases.txt.tmpl``

-  For example, add the following lines to the end:

   .. code-block:: text

      j.brown : john.brown
      jbrown  : john.brown

-  Save file as ``username-aliases.txt``

The format of the alias file is:

.. code-block:: text

   aliasname1: username1
   aliasnameA: username2
   aliasnameB: username2

... where ``aliasname`` is mapped to ``username`` in the system database. A
user may have multiple aliases. In this example, ``username2`` is known
both as ``aliasnameA`` and ``aliasnameB``. The separator between
``aliasname`` and ``username`` can be “:”, “=“ or tab.

.. warning::

   If an offered user name does not match an alias in the alias file, it
   is assumed it represents the user's real name. If this user is new to
   the system he might be created automatically in |PRODUCT_NAME|,
   according to the user creation policy defined in the 
   :ref:`Options > User Creation > On demand user creation <ss-admin-options-user-creation-on-demand>`
   section of the Admin Web App. So please take care that your alias list is valid
   and up-to-date.

.. tip::

   The content of the user name aliases file is read and cached when the
   SavaPage service is started. See 
   :ref:`User Name Aliases Cache <ch-webapp-admin-options-advanced-username-aliases>`
   on how to refresh the cache after you edited the file content.