.. _authentication:

******************************************************
Authentication and Session Monitoring
******************************************************


.. rubric:: In this section:

.. contents::
   :local:


Authentication Types
===============================

FindFace Multi provides the following authentication types:

* ``password``: standard login/password authentication. Enabled by default. 
* ``face``: authentication is possible only by the user's face.  
* ``face_or_password``: authentication is possible using either a face or login/password.
* ``face_and_password``: two-factor authentication. After a face is successfully recognized, the user must enter their credentials.

.. important::
   For all the authentication types based on face recognition, you need the following configuration: 

   * :ref:`standalone liveness service <liveness-api>` (``findface-liveness-api``)
   * :ref:`HTTPS <https>`

.. important::
   Before using face recognition for authentication, you need to :ref:`attach photos <users>` to users' profiles and equip their workplaces with webcams.

.. note::
   You can enable a work session monitoring for the authentication types ``face`` and ``face_or_password``. In this case, the system will be periodically renewing the session after verifying that the face of a person at the workplace matches the user's face that has logged in (see :ref:`auth-settings` for details). 

.. tip::
   FindFace Multi also provides a certificate-based authentication that is configured independently. Contact our support team for details (support@ntechlab.com).

.. _auth-settings:

Configure Authentication and Session Renewal
===============================================

To configure authentication and session monitoring, do the following:

#. Open the ``/etc/findface-security/config.py`` configuration file. Find the ``FFSECURITY`` and ``FFSECURITY_AUTH_CONFIG`` sections.

   .. code::
 
      sudo vi /etc/findface-security/config.py

      FFSECURITY = {
          # auth config
          # available options: face, password, face_and_password, face_or_password
          'AUTH_TYPE': 'face_or_password',
          # 180 days by default
          'MAXIMUM_SESSION_LENGTH': 15552000,
          ...
          }

      ...
      # - FindFace Security authorization configuration dictionary -

      FFSECURITY_AUTH_CONFIG = {
          'FACE_AUTH_CONFIDENCE': 0.740,  # FAR = 2.5E-09  # model: [kiwi_320]
          # 3 settings below are for front-end only
          # session renew works only with face or face_or_password authorization type
          'NEED_SESSION_RENEW': False,
          'RENEW_SESSION_INTERVAL': 0,
          'MAXIMUM_RENEW_ATTEMPTS': 2,
      }

#. In the ``FFSECURITY`` section, set the following authentication parameters:

   * ``AUTH_TYPE``: authentication type. Available options: ``face``, ``password``, ``face_and_password``, ``face_or_password``.
   *  ``MAXIMUM_SESSION_LENGTH``: the maximum session length, in seconds. After a session expires, the user will be automatically logged out unless the session is renewed.

#. In the ``FFSECURITY_AUTH_CONFIG`` section, set the following authentication and session monitoring parameters:

   * ``FACE_AUTH_CONFIDENCE``: after a face in the webcam video is detected as alive, the system checks this face against the database of user photos with this confidence threshold.
   * ``NEED_SESSION_RENEW``: if ``True``, a session can be renewed and prolonged by the time equal to ``MAXIMUM_SESSION_LENGTH``, after verifying that the face of a person at the workplace matches the user's face that has logged in. 
   * ``RENEW_SESSION_INTERVAL``: period in seconds before the expected time of the session expiry, during which the system will attempt to renew the session by enabling the webcam and verifying the user's face. 
   * ``MAXIMUM_RENEW_ATTEMPTS``: the number of user verification attempts. The attempts occur in a row during the renewal interval.

   .. note::
      A verification attempt takes about 3 seconds to complete. 

   .. tip::
      We recommend you to set up the monitoring parameters so that ``MAXIMUM_RENEW_ATTEMPTS`` multiplied by the attempt duration is less than ``RENEW_SESSION_INTERVAL``. Otherwise, the system will extend the renewal interval x2, x3, and so on, subject to the number of attempts.    

#. Restart ``findface-security``.

   .. code::

      sudo systemctl restart findface-security.service


Log out All Users
=========================

To automatically log out all users, execute the following command on the FindFace Multi principal server console:

.. code::

   sudo findface-security logout_all_users

.. tip::
   This command comes in handy when switching to a different authentication type.