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:

The Offline Installer is provided for our customers to download.

After installation, configure your SVA:

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>

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


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

<Location /validate>
    # No Authentication

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

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

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.


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.


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;
MIME-Version: 1.0
Subject: ${Subject}
From: ${From}
To: ${To}

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

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

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


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


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



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




enroll, setPin, authentication



enroll, setPin, authentication



enroll, setPin, authentication



enroll, setPin, authentication



enroll, setPin, authentication


John Doe,Room 22,+49(0)1234-22,+49(0)5678-22, john.doe@example.com

enroll, setPin, authentication



enroll, setPin, authentication



enroll, setPin, authentication



enroll, setPin, authentication



enroll, setPin









enroll, setPin, authentication


“A new ${tokentype} token (${serial}) with pin ‘${Pin}’ for ${givenname} ${surname} has been enrolled.”

enroll, setPin, authentication


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.

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.

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


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


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.


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