.. /*
    * 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-papercut-user-source-solutions:

User Source Solutions
---------------------

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

With the absence of a common :ref:`User Source <ch-webapp-admin-options-user-source>`,
SavaPage can act as Sync Source in PaperCut. Conversely, PaperCut can act as
User Source for |PRODUCT_NAME|.

However, since PaperCut does not provide an API for User Authentication,
in this case an extra shared Authentication Service is required.

.. _app-papercut-savapage-user-sync-auth:

SavaPage as Sync Source in PaperCut
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

With the absence of a common :ref:`User Source <ch-webapp-admin-options-user-source>`,
SavaPage can provide User Sync and Authentication Services for PaperCut. In this
way :ref:`Internal Users <ch-webapp-admin-options-internal-users>` can be
synchronized to and authenticated in PaperCut.

The interface is implemented as HTTP Basic Auth service. This interface
can easily be used in Python or Linux ``curl`` scripts.

Sample scripts for use in `PaperCut Custom Sync <https://www.papercut.com/kb/Main/CaseStudyCustomUserSyncIntegration>`__
are available in ``/opt/savapage/server/examples/papercut/``

.. note::

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

.. list-table:: SavaPage as Sync Source in PaperCut : Configuration Properties
   :width: 100%
   :widths: 45 55
   :header-rows: 1

   * - Configuration property
     - Description

   * - ext.papercut.user.sync.enable
     - Set to ``Y`` or ``N`` (default) to enable/disable 
       PaperCut Custom User Sync Integration.  

   * - ext.papercut.user.sync.username
     - Basic HTTP Authentication User name.

   * - ext.papercut.user.sync.password
     - Basic HTTP Authentication password.

   * - ext.papercut.user.sync.ip-addresses-allowed
     - The allowed client IP addresses as a 
       :ref:`CIDR Set <ch-install-on-linux-cidr-set>`. |br|
       |br|
       *If void, not a single client is allowed.* 


See |RST_LINK_CONFIG_EDITOR| on how to set these properties.

.. _app-papercut-as-user-source:

PaperCut as User Source in |PRODUCT_NAME|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PaperCut can be set as :ref:`User Source <ch-webapp-admin-options-user-source>`
in SavaPage by setting configuration property ``custom.user-sync.papercut`` to ``Y``.
There are three extra settings needed to make this work:

1. :ref:`PaperCut Integration <ch-webapp-admin-options-integration-papercut>`
   must be enabled, because a connection to the PaperCut Server (XML-RPC API)
   is needed to select the users that were synchronized by PaperCut from
   their User Source. |br|
   |br|

2. Because User Authentication is not part of the PaperCut API,
   authentication must be configured as :ref:`OAuth Client Plug-in <app-plugin-oauth-client>`
   that connects to the same User Source configured in PaperCut. |br|
   |br|

3. :ref:`User Source <ch-webapp-admin-options-user-source>` must be
   disabled by selecting the - option. This will show PaperCut as User
   Source.


   .. figure:: ../images/manual/screenshots/admin/sp-01-05-options-user-source-papercut.png
      :width: 400

   Admin Web App: Options - PaperCut User Source


.. list-table:: PaperCut as User Source in SavaPage: Configuration Properties
   :width: 100%
   :widths: 55 45
   :header-rows: 1

   * - Configuration property
     - Description

   * - custom.user-sync.papercut
     - Set to ``Y`` or ``N`` (default) to enable/disable PaperCut as
       :ref:`User Source <ch-webapp-admin-options-user-source>`.

   * - custom.user-sync.papercut.user-card-number.first-byte 
     - NFC Card Number First Byte: ``MSB`` or ``LSB`` (default).

   * - custom.user-sync.papercut.user-card-number.format
     - NFC Card Number Format: ``DEC`` or ``HEX`` (default).


See |RST_LINK_CONFIG_EDITOR| on how to set these properties.