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 [email protected]. RCDevs OpenOTP Authentication Server QuickStart Guide - Page 1 of 19
Transcript
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 WarrantyNo guarantee is given for the correctness of the information contained in this document.Please send any comments or corrections to [email protected].
RCDevs OpenOTP Authentication Server QuickStart Guide - Page 1 of 19
RCDevs OpenOTP Authentication Server QuickStart Guide - Page 2 of 19
1. IntroductionOpenOTP 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 Bridge‘s 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 3 of 19
2. Installing OpenOTP2.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 4 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 5 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 ServerYou 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 ‘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 6 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 7 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 installation4.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 8 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 9 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 10 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 11 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 12 of 19
2) You didn’t 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 13 of 19
5. Testing a Web server integrationYou 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 server’s 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 phprpm -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.
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 14 of 19
6. Configure your VPN server with OpenOTPThe 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 15 of 19
Appendix A - OpenOTP Server SOAP APIThe 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 16 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 one-time 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.
