Setting up Debian Wheezy
For this guide I used the debian7.3.0amd64netinst.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.
First let’s add my user account to sudo group so we can run all installations with sudo:
$ adduser erik sudo
(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
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 (20131223)
Setting debug and display log for all commands makes it easier to see what’s going on
$ sudo ./multiotp.php -config debug=1 displaylog=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 20140202 19:15:44 (user erik) Info: File created: ./users/erik.db
LOG 20140202 19:15:44 (user erik) Info: User erik successfully created and saved.
LOG 20140202 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
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.
Now your authenticator is set up and you can verify the TOTP from command line:
$ ./multiotp.php erik <6 digit totp from app>
LOG 20140202 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 20140202 19:26:37 (user erik) Error: authentication failed for user erik
LOG 20140202 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!