#############################
LinOTP Helpdesk documentation
#############################

Request
=======

Starting with LinOTP 2.11 the LinOTP Helpdesk can be used as GUI or via the API. Currently it is not yet an actively integrated part of LinOTP.

Provision of a GUI and the corresponding API calls to roll out or reset the PIN of defined user e-mail tokens.

The users receive an e-mail about the processes concerning them.

Requirements and installation
=============================

* LinOTP version >= LinOTP 2.11

* LinOTP Helpdesk, installable on the SVA, the packages are currently provided by the LinOTP support on request.

* Email provider via which the mails are sent

* Email templates to send the notifications via the email provider.

Installation of a SVA with LinOTP and the Helpdesk
==================================================

To install the SVA with LinOTP follow the instructions below:

  http://linotp.org/doc/latest/part-appliance/sva_installer_offline.html#sva-offline-installation

The Offline Installer is provided for our customers to download.

After installation, configure your SVA:

  http://linotp.org/doc/latest/part-appliance/quickstart.html#quickstart-appliance

LinOTP is now ready for further configuration at 'https://<linotp>/manage'.

To install the Helpdesk, you can use the currently installed SVA/LinOTP or a previously installed LinOTP.

First update the LinOTP to the required software version >= 2.11
----------------------------------------------------------------

**Connect with ssh to the SVA (LinOTP)**

.. code:: console

        ssh root@<linotp>
        unsupported


**Download the software using the link provided by LinOTP support.**

.. code:: console

        wget https://www.linotp.org...


**Install the downloaded package**

.. code:: console

        apt-get update && apt-get dist-upgrade
        dpkg -i linotp-helpdesk-paket-file


Configuring the Helpdesk
------------------------

Create local operators
......................

Default is the htdigest configuration based on **/etc/linotp2/auth_helpdesk**.
Similar to the configuration of /manage for LinOTP, operators of a corresponding Windows AD group can be used here.
First test with the local operators, which always form a good fallback.

.. code:: console

        htdigest -c /etc/linotp2/auth_helpdesk "LinOTP2 helpdesk area" operator1
        htdigest /etc/linotp2/auth_helpdesk "LinOTP2 helpdesk area" operator2


Customizing the Apache LinOTP Configuration
...........................................

First remove the linotp-helpdesk.conf file from /etc/apache2/sites-available

The LinOTP helpdesk configuration is part of the virtual host configured in **/etc/apache2/sites-available/linotp2.conf**.

Currently a file is provided which can be included with an Apache include directive.
If you insert them directly, there is currently the possibility that they will be removed.

The file **/etc/apache2/conf-avialable/linotp-helpdesk.conf** contains a configuration which is added to linotp2.conf with include.

.. code:: console

    RewriteEngine On

    Alias /helpdesk /usr/share/linotp-helpdesk/dist

    RewriteCond %{HTTP:Accept-Language} ^de [NC]
    RewriteRule ^/helpdesk/$ /helpdesk/de/ [L,R=302]
    RewriteRule ^/helpdesk/$ /helpdesk/en/ [L,R=302]

    # fallback for non-supported languages and english

    <LocationMatch /(api|(helpdesk/(en|de)))>
        AuthType Digest
        AuthName "LinOTP2 helpdesk area"
        AuthDigestProvider file
        AuthUserFile /etc/linotp2/auth_helpdesk
        Require valid-user

        #FallbackResource /helpdesk/en/index.html

        # logout page is used to invalidate the digest auth. Redirect brings user
        # back to helpdesk after it reauthorizes itself
        Redirect 301 /helpdesk/de/logout /helpdesk/de
        Redirect 301 /helpdesk/en/logout /helpdesk/en

    </LocationMatch>

Adding /etc/apache2/conf-avialable/linotp-helpdesk.conf to **/etc/apache2/sites-available/linotp2.conf** by include.

.. code:: console

    ...
    <Location /validate>
        # No Authentication
    </Location>

    # Include linotp helpdesk Apache config
    Include conf-available/linotp-helpdesk.conf

    ErrorLog /var/log/apache2/error.log

    LogLevel warn
    ...



Finally restarting Apache

.. code:: console

        systemctl restart apache2.service


Apache now expects the operator for login under /helpdesk, /helpdesk/(en|de) and under /api/helpdesk/<command> the API can be used.

Configure redundant LinOTP
..........................

The steps performed so far must also be performed on the redundant LinOTP (installation and update, Apache configuration).
Operations that are stored in the database are immediately available on both LinOTPs (policy, provider).

Set operator rights
...................

If LinOTP does not currently have a policy in the scope system and admin has nothing to do for the helpdesk.

If you use LinOTP policy to limit the rights of the admins, you need to extend them for the helpdesk operators.

The minimum rights required for operators are as follows:

* Operators may use but not change the configuration of the system.

.. code:: console

    [systemro]
    scope = system
    action = "read,"
    realm = *
    user = operator,...
    client = <client-ip>


* Operators may list users and their tokens in the helpdesk, reset the PIN of tokens and create e-mail tokens for users. If these operators also log in under /manage (requires appropriate configuration) they have no further rights there either

.. code:: console

    [operatoren]
    scope = admin
    action = "show, userlist, setOTPPIN, initEMAIL"
    realm = *
    user = operator,...
    client = <client-ip>


* Login to the Helpdesk or via the API is now possible with the appropriate rights.

.. code:: console

        https://<linotp>/helpdesk


The optional language version: /en or /de can be attached, here the language selection of the browser is supported. This refers to the GUI but not to the templates used for the mails.

.. _mail_templates:

Using mail templates to notify users
====================================

Without templates, the LinOTP generates and sends a simple text mail. The parameters for the mail text available in the provider configuration are applied.
Details are here: :ref:`emailprovider`

If individual templates are to be used for the rollout, a separate provider can be defined for each one.
These providers are activated via Policy in Scope notification.

Storage location of the mail templates
--------------------------------------

To adjust the location of the templates, this must be saved in the Config of LinOTP. The default is **/etc/linotp2/custom-templates/emailtemplates**.  Like the email providers, the entry is stored in the database and is available to redundant LinOTP. The templates must be inserted on all redundant LinOTPs. The following API call allows to set an individual path for the templates.

.. code::

    https://<linotp>/system/setConfig?email_provider_template_root=\
    /etc/linotp2/custom-templates/mailtemplates/&session=<cookie4manage>


The templates are specified relative to this path in the e-mail provider configuration. We use different templates for sending the OTP (basic) of the PIN (setpin) for reset and for rolling out a new token (enroll).

The basic provider configuration, which ensures the sending of mails, is required. Additionally, the template entry **TEMPLATE" : "file://enroll2user.eml "** defines the corresponding template.  The design of the template is free (e.g. multilingual, text and HTML), the variables shown below allow the insertion of various specifications (OTP,PIN,Serial,...).


.. figure:: images/emailprovider0.png
   :scale: 60%


Provider and template for rolling out the token
-----------------------------------------------

Example an email provider with template for the notification of the user about his token. The provider is used when rolling out a new token.

.. figure:: images/enroll_mail.png
   :scale: 60%


Provider and template for setting a new PIN
-------------------------------------------

Example an email provider with template for the notification of the user about his new PIN for the token. The provider is used when setting a new PIN for the token.

.. figure:: images/pin_mail.png
   :scale: 60%


Provider and template for transmitting the OTP to the user
----------------------------------------------------------

Example an email provider with template for the notification of the user about the current OTP of the token. The provider is used when transmitting the OTP of the token.

.. figure:: images/otp_mail.png
   :scale: 60%


Structure of a Tempate
----------------------

Example for the otp_mail template: otp2user.eml. The other templates are constructed according to the same principle. The files are not subject to replication, so they must be made available on all redundant LinOTPs in the same location.

.. code:: console

    Content-Type: multipart/alternative;
     boundary="===============3294676191386143061=="
    MIME-Version: 1.0
    Subject: ${Subject}
    From: ${From}
    To: ${To}

    This is a multi-part alternative message in MIME format.
    --===============3294676191386143061==
    Content-Type: text/plain; charset="us-ascii"
    MIME-Version: 1.0
    Content-Transfer-Encoding: 7bit

    For Token ${serial} your requested OTP is ${otp}.
    --===============3294676191386143061==
    Content-Type: multipart/related;
     boundary="===============3984710301122897564=="
    MIME-Version: 1.0

    --===============3984710301122897564==
    Content-Type: text/html; charset="us-ascii"
    MIME-Version: 1.0
    Content-Transfer-Encoding: 7bit

    <html>

    <body>
        <div align='center' height='100%'>
            <table width='40%' cellpadding='20px' bgcolor="#f1f2f5">
                <thead>
                    <tr>
                        <th align='center'><img src="cid:image1"></th>
                    </tr>
                    <tr>
                        <th align='center'>For Token ${serial} your requested OTP is</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td align='center'><big><big>${otp}</big></big></td>
                    </tr>
                    <tr>
                        <td align='right'><i>Happy authenticating</i></td>
                    </tr>
                </tbody>
            </table>
        </div>
    </body>

    </html>

    --===============3984710301122897564==
    Content-Type: image/png
    MIME-Version: 1.0
    Content-Transfer-Encoding: base64
    Content-ID: <image1>

    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
    D0/NjSxsT+QnY9UDTohK8K/wC6DFM6K30QyzQZzo7ske6e7JHq8QvN+N2acrdTaK4EDK9stUb49V
    Ko1LoXDZvv8tHB9/+r3W1rSbMaKwHNU/7kuGVxdEzuxL2aYAsi8ZDhmRbUbkLs+bPOFT7fWWZC8H
    Oqava1sNK9ktL/Yp7PY2RG5dvLs4cTkmvz8ZZsmjhYKorq1KWj5fsqxjwIsGfg7sKFrWSSPiLa+O
    iOoay7LG9zdPxQ3DU3CzG1ayitxQx8YulddhYNXlUcibP5lL9/rhZwZS9rUqEp/i4UXu0tq26F1U
    v78kk/vTgu1caVw1nZKDDaY/lRfllcscM/Uab9g1R8/3BX43Pa38nnx2eKK8SfzGPCKq94vqm9OG
    h6rbRfWOJfn87xZsP1cDqYEp863nJ3RqnRw3YZoR7t8rPgUM1lSyEdGAMS9bql+eMZBX3QvgM+Yh
    YKuAKoxZj58rofqNeUbgr64Ax1A9VBVivepTvd0t/KuWI4rJmgRARyJf3JeydxbhZb9ql4G7VOQW
    haBbU34ZkVcUzkarPj/VydxiPtUn3OflgJpG26/axzke/ApHGjEVblXzceB7OEmn71L3Q/9P5513
    blfvYg5vaaOePax4+3qeud64mTz54Az9FxJp1LuuXo3c++HDSTqrnKTTWznoYxbNdHQ4SecmJ+m8
    6CSdwJWMk//vyPX8C+ubwBpgfeWznp9yjXYWFwnXwQWBe4D7gb8BjyXiiZOVfnGSzknK9VffLGUX
    DMt11kPAK5S/Dn2QiCeKXgf4X0iH4OfyrFVlAAAAAElFTkSuQmCC
    --===============3984710301122897564==--

    --===============3294676191386143061==--



Result, the mail was created with the template.

.. figure:: images/otp2user_eml.png
   :scale: 60%


Making templates available in redundant LinOTP
----------------------------------------------

With a specially created script, the necessary exchange of data can take place quickly.
The script only exists on the LinOTP on which the templates are maintained/adapted.

.. code:: console

   #! /bin/bash
   rsync <lokaler Pfad zu den Templates/*> \
   root@<remote LinOTP>:<lokaler Pfad zu den Templates>
   exit 0

   #Ändern der Login Shell für root auf dem Remote LinOTP (ausschalten der
   #lshell)
   #root:x:0:0:Super User:/root:/bin/bash
   #Hinterlegen des Public Key für ssh auf dem Remote LinOTP
   #ssh-copy-id root@<remote LinOTP>


Compilation of the variables that can be used in providers and templates
------------------------------------------------------------------------

.. list-table:: Variablen in Mail Templates
   :widths: 3 2 4
   :header-rows: 1

   * - scope
     - ${var}
     - example
   * - enroll, setPin, authentication
     - username
     - john
   * - enroll, setPin, authentication
     - surname
     - Doe
   * - enroll, setPin, authentication
     - givenname
     - John
   * - enroll, setPin, authentication
     - mobile
     - +49(0)1234-22
   * - enroll, setPin, authentication
     - description
     - John Doe,Room 22,+49(0)1234-22,+49(0)5678-22, john.doe@example.com
   * - enroll, setPin, authentication
     - userid
     - 42
   * - enroll, setPin, authentication
     - email
     - john.doe@example.com
   * - enroll, setPin, authentication
     - phone
     - +49(0)5678-22
   * -
     -
     -
   * - enroll, setPin, authentication
     - serial
     - LSEM00015E83
   * - enroll, setPin
     - Pin
     - test123!
   * - enroll
     - tokentype
     - email
   * - authentication
     - otp
     - 819033
   * -
     -
     -
   * - enroll, setPin, authentication
     - message
     - "A new ${tokentype} token (${serial}) with pin '${Pin}' for ${givenname} ${surname} has been enrolled."
   * - enroll, setPin, authentication
     - Subject
     - New email token enrolled


Policy - Assignment of e-mail providers for their use
-----------------------------------------------------

In the 'Scope' 'notification' the different e-mail providers are combined with the intended use. In the action, enrollment or setPin is connected to a provider whose mail is generated with the template defined in it.

.. code:: console

    [E-Mail-Provider]
    scope = notification
    action = "enrollment=email::enroll_mail, setPin=email::pin_mail"


The following useful settings are recommended to control the length and complexity of the PIN. With 'maxtoken' the number of tokens per user is additionally limited.

.. code:: console

    [Token-PIN]
    scope = enrollment
    action = "maxtoken=1, otp_pin_random=6, otp_pin_random_content=C|c|n"


Administration of tokens via the GUI - Helpdesk
===============================================

Login
-----

.. code:: console

        https://<linotp>/helpdesk


.. figure:: images/helpdesk-login1.png
   :scale: 60%


Die GUI zeigt nach dem Login die Liste der verwaltbaren User. Durch die Policy im Scope Admin werden die verwaltbaren Realms gesteuert.

.. figure:: images/helpdesk-login2.png
   :scale: 60%


List and filter users
---------------------

With the help of the filter located in the header, the list can be searched. Currently, mainly user names and mail addresses can be filtered.

.. figure:: images/helpdesk-filter1.png
   :scale: 60%


Filter with wildcards

.. figure:: images/helpdesk-filter2.png
   :scale: 60%

|

.. figure:: images/helpdesk-filter3.png
   :scale: 60%


Roll out an e-mail token to a user
----------------------------------

Prerequisite is that the user is selected and his card is visible in the helpdesk.
If the user already has an e-mail token, no further token can be rolled out, the button is grey.
With the black button 'Roll out new E-Mail Token' the roll out process is started.

.. figure:: images/helpdesk-user1.png
   :scale: 50%


The token is rolled out to the selected user, the user can be listed in different realms. If necessary, the correct realm must be selected.
Which realm the operator sees here can be controlled by his admin policy.

.. figure:: images/helpdesk-enroll1.png
   :scale: 50%


When the roll-out process is completed, the new token is displayed and the user receives a mail with the serial of the token and the PIN valid for the token.

.. figure:: images/token-enroll.png
   :scale: 50%

|

.. figure:: images/helpdesk-enroll2.png
   :scale: 50%


If an error occurs while rolling out the token, the token is not created or is rejected by LinOTP.
Causes for errors can be:

* Missing or incorrect mail address of the user, this is read from his settings in the UserIdResolver e.g. from the Windows AD.

    * After correcting the mail address, the process can be repeated.

* Sending the mail is currently not possible due to a fault.

    * Once the fault has been eliminated, the process can be repeated.

Set a new PIN for a token
-------------------------

Prerequisite is that the user is selected and his card is visible in the Helpdesk. If the user token has been rolled out, the PIN can be reset. With the black button 'Reset Token PIN' at the height of the desired token the roll-out process is started.

.. figure:: images/helpdesk-user2.png
   :scale: 50%


The user receives a corresponding mail with the serial of the token and the new PIN.

.. figure:: images/token-setpin.png
   :scale: 50%


.. figure:: images/helpdesk-audittrail-setPin.png
   :scale: 50%


Manage tokens via the API
=========================

Manage Session Cookie
---------------------

Picking up a cookie

.. code:: console

   curl --no-keepalive -c cookies.txt --anyauth -u 'operator:PASSWORD' \
   --insecure 'https://<linotp>/api/helpdesk/getsession'


End the session

.. code:: console

   curl --no-keepalive -c cookies.txt --anyauth -u 'operator:PASSWORD' \
   --insecure 'https://<linotp>/api/helpdesk/dropsession'


Get the list of users
---------------------

Prerequisite is that a valid cookie was fetched for the operator.

.. code:: console

   curl -b cookies.txt --form 'realm=NAME' --form 'query=USERNAME' \
   --anyauth -u 'OPERATOR:PASSWORD' --insecure \
   --form "session=$(grep helpdesk_session cookies.txt | tr -d ' ' |\
     awk -F ' ' '{print $7}'|head -1)" 'https://<linotp>/api/helpdesk/users'

   --form 'realm=NAME'      #Selection of the realm (optional)
   --form 'query=USERNAME'  #Selection of users (optional, without all are listed)


Get the list of tokens of a user
--------------------------------

.. code:: console

    curl -b cookies.txt --form 'qtype=loginname' --form 'query=peter.czaska' \
    --anyauth -u 'operator:PASSWORD' --insecure \
    --form "session=$(grep helpdesk_session cookies.txt | tr -d ' ' |\
      awk -F ' ' '{print $7}'|head -1)" 'https://<linotp>/api/helpdesk/tokens'

    --form 'qtype=loginname'    #Selection of the search characteristic qtype=(loginname|realm|all)
    --form 'query=peter.czaska' #String for the search characteristic


Roll out a token
---------------------

.. code:: console

    curl -b cookies.txt --form 'realm=winad' --form 'user=peter.czaska' \
    --form 'type=email' --anyauth -u 'operator:PASSWORD' --insecure \
    --form "session=$(grep helpdesk_session cookies.txt | tr -d ' ' |\
      awk -F ' ' '{print $7}'|head -1)" 'https://<linotp>/api/helpdesk/enroll'

    --form 'realm=winad'        #Realm in which the token is rolled out, without=default, (optinal)
    --form 'user=loginname'     #Loginname of the user for whom the token is rolled out
    --form 'type=email          #token type, currently only 'email'


Resetting the PIN of a token
-----------------------------

.. code:: console

    curl -b cookies.txt --form 'realm=winad' --form 'serial=LSEM0002BFB9' \
    --form 'type=email' --anyauth -u 'operator:PASSWORD' --insecure \
    --form "session=$(grep helpdesk_session cookies.txt | tr -d ' ' |\
      awk -F ' ' '{print $7}'|head -1)" 'https://<linotp>/api/helpdesk/setPin'

    --form 'realm=winad'            #Realm in which the token is, without=default, (optinal)
    --form 'serial=LSEM0002BFB9'    #Serial of the token
    --form 'type=email'             #token type (optional), formally other token types can also be
                                     be edited by email