.. /*  
    * 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
    */

.. _app-plugin-user-source:

User Source Plug-ins
--------------------

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

See :numref:`{number}. {name} <ch-webapp-admin-options-user-source-custom>`.

.. tip::

   A sample CLI program ``custom-auth-sync-sample.sh`` with both plug-in
   interfaces combined is found in
   ``/opt/savapage/server/examples/ext/`` .

.. _app-plugin-user-source-sync:

User Synchronization Plug-in
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table:: User Synchronization Plug-in CLI
   :width: 100%
   :widths: 45 55
   :header-rows: 1
   
   * - Argument
     - stdout

   * -  ``--list-users``
     -  List of all users. Each user is separated   by ``\n``. User details must be
        supplied in the correct order separated by ``\t`` like this: |br|
        |br|

        ``UserName\tFullName\tEmail\tCardNumber\tIDNumber\n`` |br|
        |br|

        ``UserName`` identifies the user and is mandatory. 
        Other fields can be void with respect to the mandatory 
        ``\t`` field separator. Note: :ref:`Email <ch-webapp-admin-user-edit-email>`
        is the Primary email.

     
   * - ``--list-groups``
     - List of all groups. Each group is separated by ``\n``. Group details must
       be supplied in the correct order separated by ``\t`` like this:  |br|
       |br|
       ``GroupName\tFullName\n`` |br|
       |br|
       ``GroupName`` identifies the group and is mandatory.
       ``FullName`` can be void with respect to the mandatory ``\t`` field separator.
     
   * - ``--get-user-details [UserName]``
     - | ``UserName`` details separated by ``\t``
       | as in ``--list-users``. 
     
   * - ``--get-group-details [GroupName]``
     - | ``GroupName`` details separated by ``\t``
       | as in ``--list-groups``.
     
   * - ``--list-group-members [GroupName]``
     - List of users as in ``--list-users`` that are member of ``GroupName``.
     
   * - ``--is-group-present [GroupName]``
     - ``Y`` if ``GroupName`` is present, ``N`` if not.
     
   * - ``--is-user-in-group [GroupName] [UserName]``
     - ``Y`` if ``UserName`` is a member of ``GroupName``, ``N`` if not.
     
   * - ``--rfid-format``
     - The :ref:`Card Number Format <app-nfc-card-number>` as 
       ``LSB|MSB`` and ``HEX|DEC``. For example: |br|
       |br|
       ``LSB\tHEX\n``


.. _app-plugin-user-source-auth:

User Authentication Plug-in
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. table:: User Authentication Plug-in CLI

   +--------------------------+-------------------------------------------+
   | stdin                    | stdout                                    |
   +==========================+===========================================+
   | ``UserName\nPassword\n`` | ``OK`` if authentication succeeded,       |
   |                          | ``ERROR`` if not.                         |
   +--------------------------+-------------------------------------------+