.. _systemconfig:

System Config
=============

Using the System Config you can define some of LinOTP's overall behavior.  This
is the view of the System Config of the management web interface. The native
client looks rather the same.

.. figure:: images/system-config/system-config.png
   :width: 100%

   *LinOTP Config part System Config*

|

Tab Settings
~~~~~~~~~~~~~~~~~

.. figure:: images/system-config/system-config-settings.png
   :width: 80%

   *System Config tab Settings*

|

``Split At @ Sign (splitAtSign)``
        This determines, how the username is handled during the login process.
        If set to true (checked) the following will be done:
        If the username contains a “@”, the username will be split into
        username and realm name.
        E.g. the username “user1@company2” will be split into
        
            * username = user1
            * realm = company2

        If SplitAtSign is false (not checked), the username will be always take
        as it is. i.e. LinOTP will look for a user “user1@company2” following
        the default user resolving techniques.

``Return SAML attributes``

        Starting with version 2.4 LinOTP is capable of communicating with
        simpleSAMLphp via the LinOTP interface /validate/samlcheck.  If this is
        true (checked) LinOTP will not only return the information if the user
        successfully authenticated but also return the user attributes:

	 - username
	 - surname
	 - given name
	 - phone
	 - mobile
	 - email

``FailCounterOnFalsePIN``

        LinOTP will split the OTP value and then compare the remaining password
        as PIN to the PINs of each token assigned to the user. If the PIN
        matches to a token, LinOTP will calculate the OTP value of this token
        and compare it to the given one. If the OTP values do not match, LinOTP
        will increase the FailCounter for this very token.  If “Increase
        FailCounter on false PIN” is set to true (checked) and the PIN does not
        match to any token at all, LinOTP will increase the FailCounter of all
        tokens.

        If it is set to false (not checked) LinOTP will not increase any
        FailCounters.

``PrependPIN``

        If set to true (checked) the user needs to put the OTP PIN in front of
        the OTP value. (e.g.  “mySecret647356”). If it is set to false (not
        checked) the user needs to put the OTP PIN behind the OTP value. (e.g.
        “647356mySecret”).

``Auto resync``

        If Auto resync is true (checked) LinOTP will work like this:
        If a token is out of sync, LinOTP will remember the given OTP value for
        this user and for this token.  If the user logs on during the timeout
        time and provides another PIN and OTP value, LinOTP will try to
        resynchronize the token – identified by the OTP PIN – with these two
        OTP values.

        Of course the two OTP values need to be consecutive values.

``Auto resync timeout``

        This is the time, how long LinOTP will remember the first given OTP
        value. I.e. this is the time window, in which the user needs to enter
        two consecutive OTP values.



Field Authentication
--------------------

``Pass on user not found``

        If LinOTP is not able to resolve the given username during the logon
        process, access will be granted.

.. WARNING:: Use this with caution and only if you know what you are doing!

``Pass on user no token``

        If no token is assigned to the user, LinOTP will grant access to this
        user during the logon process.

.. WARNING:: Use this with caution and only if you know what you are doing!

.. _timestamps:

``Log usage timestamps in token``

        If the checkbox is activated three timestamps are displayed in the token info.

        ``LinOtp.CreationDate``
             
             Time at which this token was created.
             
        ``LinOtp.LastAuthMatch``

             Time at which this token was checked in an authentication or similar process. Several tokens of a user can be checked (multiple challenges).

        ``LinOtp.LastAuthSuccess``

             Time to use this token the last time it was successfully authenticated.

``Custom timestamp format``
        
        Format of the token timestamps
        default %d. %B. %Y, %H:%M
        %d - day: Mon, Thu,...
        %B - day in month: 03 Sep
        %Y - Year: 2020
        %H - hour
        %M - Minute
        GMT - time zone
        It is similar to international date format

Field Authorization
-------------------

``Override authentication client:``

 If a RADIUS server is authenticating it's clients via LinOTP the IP address of
 the RADIUS server is used as client IP in LinOTP by default. This IP address
 can be used in policies e.g. to map all clients from a specific RADIUS server
 to a realm. If it is required to have the real client IPs in LinOTP available
 the RADIUS can be allowed to hand on those IPs to LinOTP. Enter the IPs of the
 authorized RADIUS servers for this behaviour here.

.. figure:: images/system-config/radius_client_ip_override.png
   :width: 70%


.. NOTE:: If the RADIUS server is running on the same machine as LinOTP (like
 on the KeyIdentity Smart Virtual Appliance) you have to enter "127.0.0.1" to
 allow this local RADIUS server the transmission of the client IPs.

Tab Caching
~~~~~~~~~~~~~

In environments with a large number of users, complex realm setups and slow
UserIdResolvers the caching features can improve the performance of LinOTP
significantly.

|

.. figure:: images/system-config/system-config-caching.png
   :width: 80%

|

The caching is splitted up in two configuration items.

**Resolver Lookup Caching**

If several UserIdResolvers are joined in realms LinOTP can remember to which of
the UserIdResolver a certain user belongs. The next time the user is e.g.
authenticating LinOTP does not need to iterate over all UserIdResolver to find
the user but can directly access the correct UserIdResolver.

**User Lookup Caching**

LinOTP caches the attributes of the users (like the objectGUID). This will
speed up authentication as well as Selfservice Portal operations.


The expiration is configured in seconds.

.. code::

 1h  = 3600
 2h  = 7200
 6h  = 21600
 12h = 43200
 18h = 64800
 24h = 86400
 36h = 129600
 48h = 172800


Tab GUI settings
~~~~~~~~~~~~~~~~

.. figure:: images/system-config/system-config-gui_settings.png
   :width: 100%

   *System Config tab GUI settings*

|

``Display realm select box``

        If this is true (checked) a dropdown box containing a list of all
        realms will be displayed on the logon page of the Selfservice Portal.
        If this is false (not checked), no logon box will be displayed
        (default). This way, you can hide the names of all realms from the
        users. The user then needs to log on by entering *username@realm*.

Tab Client Identification
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. figure:: images/system-config/system-config-client_identifikation.png
   :width: 100%

   *System Config tab Client Identification with Proxy*

|

``Support for HTTP_X_FORWARDED_FOR``

  The X-Forwarded-For (XFF) HTTP header field is a common method for identifying the originating
  IP address of a client connecting to a web server through an HTTP proxy or load balancer.
  As of 2014 RFC 7239 (Wikipedia)
  If this is true (checked) this method is used for identify client IP address,
  for example in Policy.
  
``Support for HTTP_FORWARDED``

  The HTTP_Forwarded HTTP header field is a common method for identifying the originating
  IP address of a client connecting to a web server through an HTTP proxy or load balancer.
  If this is true (checked) this method is used for identify client IP address,
  for example in Policy.
    
``Trusted Forwarding Proxy``

  List of allowed Proxy's. Client can connect over trusted Proxy in list.