OpenOTP Quick Start
  Download PDF

1. Introduction

OpenOTP is the RCDevs user authentication solution. The OpenOTP solution is composed of a set of server applications and components which provide secure and reliable authentication of users to applications and online services, intranet and extranet access, secure Internet transactions… OpenOTP relies on proven technologies and open standards such as OATH (the initiative for open authentication), HOTP / TOTP / OCRA, Radius, LDAP.

A one-time password (OTP) is a password that is only valid for a single login session or transaction. OTPs avoid a number of shortcomings that are associated with traditional (static) passwords. The most important shortcoming that is addressed by OTPs is that, in contrast to static passwords, they are not vulnerable to replay attacks. This means that, if a potential intruder manages to record an OTP which was already used to log into a service or to conduct a transaction, he will not be able to abuse it since it will be no longer valid. On the downside, OTPs cannot be memorized by human beings. Therefore they require additional technology in order to work.

OpenOTP provides multiple One-Time Password-based authentication methods for your LDAP users, including:

  • OATH event-based (HOTP) hardware and software tokens.
  • OATH time-based (TOTP) hardware and software tokens.
  • OATH challenge-response (OCRA) hardware and software tokens.
  • YubiKey hardware tokens.
  • SMS one-time password.
  • Mail and Secure Mail one-time password (with integrated PKI).
  • Pre-generated OATH OTP password lists.

The OpenOTP authentication solution is composed of the WebADM server application, the OpenOTP SOAP/XML and JSON Web service (i.e. the OTP Authentication Server), the Radius Bridge server (i.e. The OpenOTP RADIUS API), the User Self-Service Desk and Token Self Registration end-user Web applications (WebApps) and the SMS Hub Server Web service. This document is intended to provide a quick start guide to administrators who want to test and implement RCDevs WebADM and OpenOTP Authentication Server. The reader should notice that this document is not a guide for installing and using WebADM and its applications.

In this quick start guide, we will cover the following points:

  1. How to install and configure your OpenOTP Authentication server in WebADM.
  2. How to install and configure your OpenOTP Radius Bridge.
  3. How to create a user and test the OTP authentication.
  4. How to implement OTP in a PHP login page.
  5. How to configure your VPN to enable OTP authentication.

WebADM and OpenOTP Radius Bridge‘s installation and configuration manuals are not covered by this guide and are documented in specific documents available through RCDevs’ online documentation.

2. Installing OpenOTP

2.1 Install and Configure WebADM

In order to setup RCDevs OpenOTP Server, you must have a working WebADM server installation. This guide assumes your target system already has a running WebADM server, configured and connected to a compatible LDAP directory. If you do not have the proper environment in place, we recommend that you first download and run one of the RCDevs’ pre-installed VMWare appliances. Please go to RCDevs Downloads to get your VMWare appliance.

2.2 Download and Install the OpenOTP Packages

If you installed a VMWare Appliance, OpenOTP server and Radius Bridge are already installed. If you installed on one of your Linux servers with the RCDevs webadm-all-in-one package, OpenOTP is already installed (but not Radius Bridge). You can download here OpenOTP Server & Radius Bridge packages.

To install OpenOTP in WebADM, copy the package files on your WebADM Linux server with WinSCP or another SSH/SCP client application and unzip it with the command:

gunzip openotp-1.0.x.sh.gz

Then run the installer with the commands:

chmod 755 openotp-1.0.x.sh
./openotp-1.0.x.sh

The installer will ask you to confirm the installation or to confirm the upgrade if an older version of OpenOTP Server is already installed. Just say ‘y’ and press ‘enter’. Once OpenOTP Server is installed, restart your WebADM server with the command:

/opt/webadm/bin/webadm restart


Your OpenOTP server is now installed in the /opt/webadm/websrvs/openotp/ directory and you will need to configure the OpenOTP web service settings in WebADM (in section 3.1).

3. Configure OpenOTP Server

You now need to configure your OpenOTP server in WebADM and to edit some Radius Bridge configuration files in /opt/radiusd/conf/. Let’s start with the OpenOTP configuration.

3.1 OpenOTP Application Configuration

Log in the WebADM Admin Portal with your Super Administrator account and click the Applications button in the top menu bar. The MFA Authentication Server now appears in the list of installed Web Services but is not registered. Just click the REGISTER button to register the OpenOTP Web Service application in WebADM.

screenshot

The OpenOTP application is now registered but is still not fully configured. The registration created a default configuration for your application. But some configuration changes are required for our testing. Click the CONFIGURE button to enter the OpenOTP application configuration.

screenshot

Most of the settings here are just fine to start using OpenOTP. We will only adjust the Default Domain setting. Domains are a very important thing in WebADM. They are required by your Web Services (ex. OpenOTP) to know where to search for users while processing requests. Your WebADM server should have at least one Domain already setup and your testing users must be located in an LDAP tree below the User Search Base setting of this Domain.

You can check the Default Domain checkbox and select your existing Domain (here Default).

screenshot

Once the settings are configured, click the Save button and your OpenOTP application is now configured. All the other settings are just fine for the moment. The OpenOTP service is now running and the SOAP API is accessible under the web service URLs in the Applications menu.

4. Testing your OpenOTP Installation

4.1 Enroll a Software Token

Your OpenOTP Server is now working and you can start enrolling a test user. We will enroll a Software Token for a new user with Google Authenticator.

1) On your iPhone or Android phone, go to the AppStore and search for Google Authenticator. Download and install the application on your mobile.

2) Create a WebADM Account test user in your LDAP tree. Go to the top menu in WebADM, and click the Create button. Choose the WebADM Account object and create a user with login name ‘testing’ and password ‘test’. Alternatively, you can use an existing WebADM user for your tests. Set the Container (LDAP folder) to a location below you Domain User Search Base.

screenshot

3) Once the user is created, edit it and click the MFA Authentication Server button in the Application Actions box.

screenshot

4) Click the Register / Unregister Token button.

screenshot

5) Check the Google Authenticator Time-based or Event-based checkbox. Immediately, a QRCode is displayed on the page.

screenshot

6) Start the OpenOTP Token or Google Authenticator application on your mobile phone and click the Camera button. Scan the QRCode to register a new Software Token on your mobile phone. When done, click the Register button on the screen. The Software Token is now registered in OpenOTP.

screenshot

4.2 Configure the User Authentication Method

You have registered an OpenOTP Token or a Google Authenticator Software Token for your test user. We will now configure the user to work with ‘TOKEN’ authentication mode.

1) Edit the user and click the CONFIGURE button in the Object Details box.

screenshot

2) Select MFA Authentication Server in the Application list box.

screenshot

3) Check the ‘OTP Type’ checkbox and select TOKEN. If TOKEN is already the default OTP Type, then you do not need to configure this setting.

4) Save the user settings by clicking the Apply button at the bottom of the page.

4.3 Test User Authentication

1) Return to the MFA Authentication Server in the Application Actions box for the user and click the Test User Authentication action.

screenshot

A login form is displayed. Enter ‘test’ in the LDAP Password field and let the rest empty. Click the Start button.

screenshot

2) You didn’t enter the OTP in the login and OpenOTP also activates the Challenged-OTP mode. A new window is displays with a message asking for your Token password. Enter the password displayed on your Google Authenticator mobile application.

screenshot

3) WebADM displays the authentication result and server message.

screenshot

You can have a look at the ‘WebADM Server Log Files’ in the ‘Database’ menu to see what happened.

5. Testing a Web Server Integration

You can download and use the RCDevs sample PHP Login Form for OpenOTP to experiment a very simple Web integration with OpenOTP:

loginform.zip

Copy the ZIP archive to your public Web server’s document root (for example /var/www/html), and unzip it. It will create a loginform directory. The testing URL on your Web server will be http://yourwebsite.com/loginform/

Be sure to have PHP and the PHP-SOAP extension installed on your public Web server. On a RedHat server, You can install it with:

yum install php php-soap

Enter the loginform directory and edit the index.php file. You need to adjust the OpenOTP SOAP web service URL (server_url) at the beginning of the file. Remember that the web service URLs are displayed in the Applications menu in WebADM.

$server_url = "http://mywebadmserver:8080/openotp/";

You can now go to the login form URL at http://mywebsite.com/loginform/ with a Web browser to test the sample OpenOTP login integration.

Enter the username and LDAP password. You can enter the OTP password in this screen or in the challenge screen (after pressing the ‘Login’ button) as we did in our authentication test previously.

6. Configure your VPN Server with OpenOTP

The configuration of your VPN server depends on your VPN software. Get your vendor documentation and look for a section explaining how to use a RADIUS server for remote authentication. As a general rule, you will need to set up a RADIUS server connection by specifying the IP address of the Radius Bridge and the RADIUS shared secret. On your Radius Bridge server, you will need to edit the /opt/radiusd/conf/clients.conf and add a RADIUS client block (with the IP address of the VPN server and the shared RADIUS secret). Please look at RCDevs’ Radius Bridge Manual for details about the RADIUS server configuration and integration.

Appendix A - OpenOTP Server SOAP API & WSDL

Please, refer to the following documentation.