1. LinOTP Helpdesk documentation¶

1.1. 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.

1.2. 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.

1.3. 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.

1.3.1. First update the LinOTP to the required software version >= 2.11¶

Connect with ssh to the SVA (LinOTP)

ssh root@<linotp>
unsupported

Download the software using the link provided by LinOTP support.

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

Install the downloaded package

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

1.3.2. Configuring the Helpdesk¶

1.3.2.1. 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.

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

1.3.2.2. 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.

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.

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

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.

1.3.2.3. 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).

1.3.2.4. 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.

[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

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

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.

1.4. 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: E-mail Provider for E-mail Token

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.

1.4.1. 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.

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,…).

1.4.2. 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.

1.4.3. 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.

1.4.4. 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.

1.4.5. 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.

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

1.4.6. 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.

#! /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>

1.4.7. Compilation of the variables that can be used in providers and templates¶

Variablen in Mail Templates¶
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

1.4.8. 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.

[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.

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

1.5. Administration of tokens via the GUI - Helpdesk¶

1.5.2. 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.

Filter with wildcards

1.5.3. 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.

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.

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.

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.

1.5.4. 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.

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

../_images/helpdesk-audittrail-setPin.png

1.6. Manage tokens via the API¶

1.6.2. Get the list of users¶

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

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)

1.6.3. Get the list of tokens of a user¶

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

1.6.4. Roll out a token¶

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'

1.6.5. Resetting the PIN of a token¶

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

1. LinOTP Helpdesk documentation¶

1.1. Request¶

1.2. Requirements and installation¶

1.3. Installation of a SVA with LinOTP and the Helpdesk¶

1.3.1. First update the LinOTP to the required software version >= 2.11¶

1.3.2. Configuring the Helpdesk¶

1.3.2.1. Create local operators¶

1.3.2.2. Customizing the Apache LinOTP Configuration¶

1.3.2.3. Configure redundant LinOTP¶

1.3.2.4. Set operator rights¶

1.4. Using mail templates to notify users¶

1.4.1. Storage location of the mail templates¶

1.4.2. Provider and template for rolling out the token¶

1.4.3. Provider and template for setting a new PIN¶

1.4.4. Provider and template for transmitting the OTP to the user¶

1.4.5. Structure of a Tempate¶

1.4.6. Making templates available in redundant LinOTP¶

1.4.7. Compilation of the variables that can be used in providers and templates¶

1.4.8. Policy - Assignment of e-mail providers for their use¶

1.5. Administration of tokens via the GUI - Helpdesk¶

1.5.2. List and filter users¶

1.5.3. Roll out an e-mail token to a user¶

1.5.4. Set a new PIN for a token¶

1.6. Manage tokens via the API¶

1.6.2. Get the list of users¶

1.6.3. Get the list of tokens of a user¶

1.6.4. Roll out a token¶

1.6.5. Resetting the PIN of a token¶

Table of Contents

Search

1. LinOTP Helpdesk documentation¶

1.1. Request¶

1.2. Requirements and installation¶

1.3. Installation of a SVA with LinOTP and the Helpdesk¶

1.3.1. First update the LinOTP to the required software version >= 2.11¶

1.3.2. Configuring the Helpdesk¶

1.3.2.1. Create local operators¶

1.3.2.2. Customizing the Apache LinOTP Configuration¶

1.3.2.3. Configure redundant LinOTP¶

1.3.2.4. Set operator rights¶

1.4. Using mail templates to notify users¶

1.4.1. Storage location of the mail templates¶

1.4.2. Provider and template for rolling out the token¶

1.4.3. Provider and template for setting a new PIN¶

1.4.4. Provider and template for transmitting the OTP to the user¶

1.4.5. Structure of a Tempate¶

1.4.6. Making templates available in redundant LinOTP¶

1.4.7. Compilation of the variables that can be used in providers and templates¶

1.4.8. Policy - Assignment of e-mail providers for their use¶

1.5. Administration of tokens via the GUI - Helpdesk¶

1.5.1. Login¶

1.5.2. List and filter users¶

1.5.3. Roll out an e-mail token to a user¶

1.5.4. Set a new PIN for a token¶

1.6. Manage tokens via the API¶

1.6.1. Manage Session Cookie¶

1.6.2. Get the list of users¶

1.6.3. Get the list of tokens of a user¶

1.6.4. Roll out a token¶

1.6.5. Resetting the PIN of a token¶

Table of Contents

Search