Time-based one-time passwords with multiOTP on Debian Wheezy

Setting up Debian Wheezy

For this guide I used the debian­7.3.0­amd64­netinst.iso and did a graphical install with the following customizations. This will install Apache web server for you automatically which we’ll use to serve the QR code to pair multiOTP with the authenticator app.

TOTP Wheezy


First let’s add my user account to sudo group so we can run all installations with sudo:

$ su
$ adduser erik sudo
$ exit

(log out and log back in for sudo group to take effect)

Setting up PHP

GD library is needed to create QR codes

$ sudo apt­-get install php5­-common libapache2­-mod­-php5 php5­-cli php5­-gd

Setting up NTP to synchronize time

It is crucial that the time on the local machine is correct for TOTP to work

$ sudo apt­-get install ntp
Verify that the date is correct
$ date
Sun, 02 Feb 2014 19:12:36 +0200

Setting up multiOTP

The latest version of multiOTP was used for this guide, which at the time of writing was 4.1.0.

$ sudo unzip ­-d /opt/multiotp /home/erik/Downloads/multiotp­-4.1.0

$ cd /opt/multiotp

To be able to run multiotp.php from command line do

$ sudo chmod ugo+rx multiotp.php

Create the config/multiopt.ini file by running multitop.php with sudo first time

$ sudo ./multiotp.php ­-v
multiOTP 4.1.0 (2013­12­23)

Setting debug and display log for all commands makes it easier to see what’s going on

$ sudo ./multiotp.php ­-config debug=1 display­log=1
19 INFO: Requested operation successfully done

We’ll set write permissions on user to be able to create and authenticate users without sudo. This should be set to something more sensible in a production environment.
$ sudo chmod o+w users/

You’re now set to start using multiOTP from the command line. I highly recommend you to play around with the examples in the readme.txt, create different accounts and try to authenticate to get a feel for it.

Here’s an example on how to create a Google Authenticator account and create the url link or QR code used to add your account on your phone.

Create a Google Authenticator user. Please note that the user erik I have set up below in multiOTP is not connected to the local linux user account that I use to login to Debian. This is something I as a developer will have to take care of myself later on. Usually the website account is stored in a database, and then it makes sense to configure multiOTP to store the information in the same database as well. In my guide the accounts are stored in text files.

$ ./multiotp.php ­-createga erik

LOG 2014­02­02 19:15:44 (user erik) Info: File created: ./users/erik.db
LOG 2014­02­02 19:15:44 (user erik) Info: User erik successfully created and saved.
LOG 2014­02­02 19:15:44 (user erik) Info: user erik successfully created 11 INFO: User successfully created or updated

Create the URL link and display it in console

$ ./multiotp.php -­urllink erik

17 INFO: UrlLink successfully created

Create the same link in a QR code. This code will contain the same otpauth URL as above. Sudo is needed to write to /var/www/.
$ sudo ./multiotp.php ­-qrcode erik /var/www/erik.png
16 INFO: QRcode successfully created

TOTP qr1

View and scan the QR code in a browser using http://<your local ip>/erik.png. Google Authenticator will read this code without problems. If you happen to be using Microsoft Authenticator you will have to input the name and secret by hand ­ because the QR code interpreter expects the ?secret parameter to be first parameter in the list ­ or use Bing vision and copy the secret part of the url from there. For your convenience I’ve included a modified QR code (otpauth://totp/erik?secret=2233445566777733&period=30&digits=6) for all you Windows Phone users out there.

TOTP qr2

Now your authenticator is set up and you can verify the TOTP from command line:

$ ./multiotp.php erik <6 digit totp from app>
LOG 2014­02­02 19:22:16 (user erik) OK: user erik successfully logged in 0 OK: Token accepted

This is what will happen if I try to authenticate with a made up code:

$ ./multiotp.php erik 12356
LOG 2014­02­02 19:26:37 (user erik) Error: authentication failed for user erik

LOG 2014­02­02 19:26:37 (user erik) (authentication typed by the user: 123456) 99 ERROR: Authentication failed (and other possible unknown errors)

That’s it. I hope this practical guide gives you got a better understanding of how TOTP works behind the scenes!

Erik Nylund

Erik Nylund