RCDevs OpenOTP Authentication Server QuickStart Guide - Page 1 of 19

The specifications and information in this document are subject to change without notice.
Companies, names, and data used in examples herein are fictitious unless otherwise noted. This
document may not be copied or distributed by any means, in whole or in part, for any reason,
without the express written permission of RCDevs.
Copyright (c) 2010-2013 RCDevs SA. All rights reserved.
http://www.rcdevs.com/
WebADM and OpenOTP are trademarks of RCDevs.
All further trademarks are the property of their respective owners.
Limited Warranty
No guarantee is given for the correctness of the information contained in this document.
Please send any comments or corrections to info@rcdevs.com.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 2 of 19

1. Introduction!

2. Installing OpenOTP!

2.1. Install and configure WebADM!

2.2. Download and install the OpenOTP packages!

3. Configure OpenOTP Server!

3.1 OpenOTP application configuration!

3.2 Radius Bridge configuration!

4. Testing your OpenOTP installation!

4.1. Enroll a Software Token!

4.2. Configure the user authentication method!

11

4.3. Test user authentication!

12

5. Testing a Web server integration!

14

6. Configure your VPN server with OpenOTP!

15

Appendix A - OpenOTP Server SOAP API!

16

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 3 of 19

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. Specific guides
are available through the RCDevs online documentation library at http://www.rcdevs.com/.
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 Bridges installation and configuration manuals are not covered
by this guide and are documented in specific documents available through RCDevs online
documentations.
A detailed specification of the OpenOTP features and APIs is provided in the OpenOTP Technical
Specification document, available in RCDevs online documentations.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 4 of 19

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 http://www.rcdevs.com/
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 the OpenOTP Server
package and Radius Bridge package at http://www.rcdevs.com/downloads/.
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

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 5 of 19

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).
You can now install OpenOTP Radius Bridge like you did for the OpenOTP Server. Simply run the
following commands:
gunzip radiusd-1.0.x.sh.gz
Then run the installer with the commands:
chmod 755 radiusd-1.0.x.sh
./radiusd-1.0.x.sh

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 6 of 19

Your OpenOTP Radius Bridge is now installed in the /opt/radiusd/ directory and you will need to
configure Radius Bridge (in section 3.2).

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/. Lets 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 OTP 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.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 7 of 19

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.

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

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.

3.2 Radius Bridge configuration

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 8 of 19

OpenOTP Radius Bridge can be configured by editing the files in the /opt/radiusd/conf/ directory.
There is no graphical configuration for the RADIUS server. For our tests, we will keep the default
configuration. To connect a VPN server to Radius Bridge, you will need to edit the clients.conf file
to register the VPN IP address and shared RADIUS secret.
A detailed configuration manual for Radius Bridge is available through RCDevs online
documentations. We strongly encourage you to read the manual in order to correctly setup your
VPN for use with OpenOTP.

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.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 9 of 19

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

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 10 of 19

4) Click the Register / Unregister Token button.

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

is displayed on the page.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 11 of 19

6) Start the Google Authenticator application on your mobile phone and click the Scan 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.

4.2. Configure the user authentication method

You have registered 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 Add Settings button in the Object Details box.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 12 of 19

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

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 click the Apply button at the bottom of the page.

4.3. Test user authentication

1) Return to the OTP Authentication Server in the Application Actions box for the user and click
the Test User Login action. A login form is displayed. Enter test in the LDAP Password field
and let the rest empty. Click the Start button.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 13 of 19

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

3) WebADM displays the authentication result and server message.

You can have a look at the Web Service Logs in the Database menu to see what happened.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 14 of 19

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. Just can download the sample code archive in the the
Downloads section on the RCDevs Website. Go to the Libraries & Examples folder and download
the OpenOTP Sample PHP Login Form.
Copy the ZIP archive to your public Web servers document root 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 check it with :
rpm -q php
rpm -q 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) like we did in our authentication test previously.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 15 of 19

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

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 16 of 19

Appendix A - OpenOTP Server SOAP API

The OpenOTP authentication service is implemented over the SOAP/XML and RADIUS APIs. The
SOAP/XML API is provided with a SOAP WSDL service description listed below.
The OpenOTP API is very simple and provides 3 methods:
1) openotpLogin
This method is used to send an authentication request.
The request contains the following attributes:
- username : User login name (mandatory).
- domain : User login domain (optional if OpenOTP as a default domain setting set).
- ldapPassword : User LDAP password (mandatory if OpenOTP login mode setting is LDAPOTP or
LDAP).
- otpPassword : One-time password (optional and usable only with Token OTPs).
- client: Client identifier (NAS) to be used in service logs (defaults to the client IP address).
- source: IP address of the end user system (optional).
- settings: List of OpenOTP settings which will override the user / group / application server-side
settings (ex. "LoginMode= LDAPOTP, OTPType=SMS").
The response contains the following attributes:
- code: 1 means authentication success
0 means authentication failure
2 mean authentication challenge
- message : The server reply message to be displayed to the user.
With code 2, message contains the challenge message.
- session : With challenge, this is the session ID to be passed in the openotpChallenge request.
- timeout : With challenge, this is the remaining session time to send the challenge response.
- data : This attribute contains the ReplyData set in the LDAP user or group settings.
With Radius, the data can be used by rule-based policies on a RADIUS VPN client for example.
In that case, OpenOTP RadiusBridge will return this data in a Filter-Id RADIUS attribute.
In OpenOTP versions equal or greater than 1.0.9, the openotpChallenge SOAP method includes
the username and domain fields like in the openotpLogin method. This simplifies authentication
programming in web applications as the developers do not have to to ensure that the credentials
passed via hidden fields in the challenge login form have been altered or not.
Before, if a challenge response was returned after an openotpLogin call, the website had to store
the username and domain because it cannot trust these informations when passed via hidden
fields in the challenge HTML form. They can be altered on the client side before being posted
again.
Now the openotpChallenge method requires the same username and domain as those given in the
openotpLogin method. OpenOTP will also succeed only if the username and domain are identical
in the openotpLogin and openotpChallenge. The website can also start a PHP session and use the
information gathered by the hidden fields securely to get the user identity gathered in the first login
form.
2) openotpChallenge
This method is used when the openotpLogin returned a challenge (code 2). This is the second
request to be sent containing the user one-time password.

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 17 of 19

The request contains the following attributes:

- username : User login name (mandatory).
- domain : User login domain (optional if OpenOTP as a default domain setting set).
- session : The session ID returned in the openotpLogin response.
- otpPassword : The user one-time password (i.e. challenge response).
The response contains the following attributes:
- code : 1 means authentication success
0 means authentication failure
- message : The server reply message to be displayed to the user.
- data : See openotpLogin response above.
3) openotpStatus
This method is used to query a server status.
The request does not contain any attribute.
The response contains the following attributes:
- status : 1 if the server is willing to accept requests.
0 if the server cannot accept new requests.
- message: The server status details.
Note: The otpPassword attribute is usable in an openotpLogin request only with OATH HOTP onetime password. In this mode, the user can generate and enter the OTP in the first request (which i
not possible with SMSOTP or MAILOTP).

OpenOTP WSDL
This SOAP WSDL specification defines the interface explained just before.
<?xml version="1.0" encoding="UTF-8"?>
<definitions targetNamespace="http://www.rcdevs.com/wsdl/openotp/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://www.rcdevs.com/wsdl/openotp/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<message name="openotpSimpleLoginRequest">
<part name="username" type="xsd:string"/>
<part name="domain" type="xsd:string"/>
<part name="anyPassword" type="xsd:string"/>
<part name="client" type="xsd:string"/>
<part name="source" type="xsd:string"/>
<part name="settings" type="xsd:string"/>
</message>
<message name="openotpNormalLoginRequest">
<part name="username" type="xsd:string"/>
<part name="domain" type="xsd:string"/>
<part name="ldapPassword" type="xsd:string"/>
<part name="otpPassword" type="xsd:string"/>
<part name="client" type="xsd:string"/>

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 18 of 19

<part name="source" type="xsd:string"/>

<part name="settings" type="xsd:string"/>
</message>
<message name="openotpLoginResponse">
<part name="code" type="xsd:integer"/>
<part name="message" type="xsd:string"/>
<part name="session" type="xsd:string"/>
<part name="data" type="xsd:string"/>
<part name="timeout" type="xsd:integer"/>
</message>
<message name="openotpChallengeRequest">
<part name="username" type="xsd:string"/>
<part name="domain" type="xsd:string"/>
<part name="session" type="xsd:string"/>
<part name="otpPassword" type="xsd:string"/>
</message>
<message name="openotpChallengeResponse">
<part name="code" type="xsd:integer"/>
<part name="message" type="xsd:string"/>
<part name="data" type="xsd:string"/>
</message>
<message name="openotpStatusRequest"/>
<message name="openotpStatusResponse">
<part name="status" type="xsd:boolean"/>
<part name="message" type="xsd:string"/>
</message>
<portType name="openotpPortType">
<operation name="openotpSimpleLogin">
<input name="openotpSimpleLoginRequest" message="tns:openotpSimpleLoginRequest"/>
<output name="openotpSimpleLoginResponse" message="tns:openotpLoginResponse"/>
</operation>
<operation name="openotpNormalLogin">
<input name="openotpNormalLoginRequest" message="tns:openotpNormalLoginRequest"/>
<output name="openotpNormalLoginResponse" message="tns:openotpLoginResponse"/>
</operation>
<operation name="openotpLogin">
<input name="openotpLoginRequest" message="tns:openotpNormalLoginRequest"/>
<output name="openotpLoginResponse" message="tns:openotpLoginResponse"/>
</operation>
<operation name="openotpChallenge">
<input name="openotpChallengeRequest" message="tns:openotpChallengeRequest"/>
<output name="openotpChallengeResponse" message="tns:openotpChallengeResponse"/>
</operation>
<operation name="openotpStatus">
<input name="openotpStatusRequest" message="tns:openotpStatusRequest"/>
<output name="openotpStatusResponse" message="tns:openotpStatusResponse"/>
</operation>
</portType>
<binding name="openotpBinding" type="tns:openotpPortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="openotpSimpleLogin">
<soap:operation soapAction="openotpSimpleLogin"/>
<input><soap:body use="encoded" namespace="urn:openotp" encodingStyle="http://
schemas.xmlsoap.org/soap/encoding/"/></input>

RCDevs OpenOTP Authentication Server QuickStart Guide - Page 19 of 19

<output><soap:body use="encoded" namespace="urn:openotp"

schemas.xmlsoap.org/soap/encoding/"/></output>
</operation>
<operation name="openotpNormalLogin">
<soap:operation soapAction="openotpNormalLogin"/>
<input><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></input>
<output><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></output>
</operation>
<operation name="openotpLogin">
<soap:operation soapAction="openotpLogin"/>
<input><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></input>
<output><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></output>
</operation>
<operation name="openotpChallenge">
<soap:operation soapAction="openotpChallenge"/>
<input><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></input>
<output><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></output>
</operation>
<operation name="openotpStatus">
<soap:operation soapAction="openotpStatus"/>
<input><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></input>
<output><soap:body use="encoded" namespace="urn:openotp"
schemas.xmlsoap.org/soap/encoding/"/></output>
</operation>
</binding>
<service name="openotpService">
<port name="openotpPort" binding="tns:openotpBinding">
<soap:address location="http://localhost:8080/openotp/"/>
</port>
</service>
</definitions>

encodingStyle="http://

encodingStyle="http://
encodingStyle="http://

encodingStyle="http://
encodingStyle="http://

encodingStyle="http://
encodingStyle="http://

encodingStyle="http://
encodingStyle="http://