TOTPRADIUS Documentation

last updated: November 22 2019


TOTPRadius is deployed as a software-based virtual appliance that runs on two hypervisors: VMWare ESXi and Microsoft Hyper-V. Upon request, virtual appliances for other hypervisors can be provided. It is free to use with up to 5 users. You need to obtain a license to increase the number of allowed users.

Download VMWare OVA
In addition to VMware vSphere (ESXi), OVA format can also be imported and used with Oracle VirtualBox
Download Hyper-V appliance
A zip file with the virtual machine exported from a Hyper-V host . Requires Hyper-V v.10 or higher (Win10 or Win2016). For earlier versions, create the VM manually with default settings and connect the IDE0 to the VHDX file in the archive. No further configuration changes are required.


Import OVF to VMWare or VirtualBox
TOTPRadius is deployed in standard OVF format. Follow usual OVF import procedures to install the appliance.
Import VM to Hyper-V
TOTPRadius has been tested on standard Windows 2012 R2 and Windows 2016(Core) based Hyper-V hosts and has been exported using Hyper-V manager. To import, unzip the downloaded archive to a location visible from Hyper-V manager and import the appliance. Initial configuration of the appliance Power on the virtual machine and open its console.
While there is no official image released for XenServer, a number of clients managed to import and use the VMWare image by editing the grub options in the boot menu to make the root filesystem /dev/xvda1 (what XenServer looks for) instead of /dev/sda1 (what VMware presents).

Ldap Proxy Mode

About LDAP Proxy mode
LDAP Proxy mode is useful when you need to enable two-factor authentication for systems that only support single-factor authentication. The principle behind it is that users will provide their AD or LDAP password together with the one-time passwords in the password field. TOTPRadius will then parse the password, split it into two parts and authenticate the OTP and if correct will send the AD/LDAP password part further to the AD/LDAP server configured. The order of authentication is exactly as stated above, OTP is checked first and AD after OTP is confirmed correct; this is done in order to prevent account lockouts during brute force attacks. Enabling LDAP Proxy on your TOTPRadius appliance allows implementing two-factor authentication for systems that do not natively support it, such as Cisco Meraki VPN, Cisco WLC, and many others.
LDAP username format
If the username expected by your LDAP servers should contain additional information, such as domain name, make sure it is specified in LDAP username format field in General Settings page. For example, if the user jsmith is to be presented to LDAP as [email protected] , the username format field should look like "%username%@xyzcorporation.local" . TOTPRadius will replace %username% with he username submitted during authentication and/or tests. So when running LDAP test, only provide the username and the password.

High Availability

TOTPRadius has high availability implemented by enabling the "slave" appliance mode - you can deploy additional TOTPRadius appliances and configure master to slave replication. No additional user licenses required. Slave mode can be enabled under "Advanced settings". "Strict SSL" mode is highly recommended and requires a valid SSL certificate installed on the master node.


If you are using netscaler with more than one Active Directory domain and usernames are not unique accross domains, you have to enable multidomain configuration with TOTPRadius. If not enabled, the system will ignore usernames in DOMAIN\username or [email protected] format. If the domain names used to login are not matching with the NetBios domain names, you have to configure mapping NetBios domains (used by StoreFront authentication) to login domain. So if the user is logging in as [email protected] but StoreFront recognizes it as ACME\user, domain mapping should look like "". Separate multiple mappings with ";" sign.

Local Passwords Mode

Note! Not compatible with LDAP mode
Local passwords mode, as the name states, enables local passwords for user login. Please note that this feature is added primarily for tests and is not recommended for production use. The passwords are stored in the database in SHA1 hashed format.

If this setting is enabled, LDAP feature gets disabled automatically. Note that this password is for RADIUS authentication only and cannot be used to log in to Web administration panel. This mode does not support single factor mode or initial login attempt allowance.

Authentication Modes Summary

TOTPRadius supports different authentication modes which can be configured as described in the table below.

# Authentication mode Settings
1 OTP Authentication only Disable both local password and LDAP. If no self-service enrollment integration is required, set "Allow initial login" parameter to 0
2 LDAP and OTP Authentication Enable LDAP and Enforce 2FA (keep Local passwords disabled)
3 LDAP and OTP or OTP only Authentication Enable LDAP , Disable "Enforce 2FA" option
4 Local Passwords and OTP Authentication Disable LDAP and Enable Local Passwords (Initial logins will not be allowed in this configuration)

Realtime Debugging

TOTPRadius allows debugging the authentication attempts in real-time. If "Real-time log" button clicked (from the main page or General Settings menu) and the RADIUS service is running, all authentication attempts will be shown in a pop-up window.
Realtime log window has the possibility of displaying the passwords. You can control this behaviour via a setting in the General Settings (Advanced)

Testing User Authentication

We recommend NTRadPing 1.5 RADIUS Test Utility (Windows only) for testing the authentication.

Increasing Disk Space

By default TOTPRadius has around 8Gb disk space allocated to it. This should be enough for the most of the cases, but depending on the usage frequency, the disk may get full. Follow the instructions below to free and increase the disk space of the appliance.
1. Empty log files
Check if you have a lot of *.gz or *.log.X (where X is an integer) files under /var/log . If so, you can safely delete them by issuing sudo rm *.gz command.
If the kern.log and syslog files are large, you can empty them by issuing the commands: sudo echo "" > kern.log and sudo echo "" > syslog
2. Increase disk space
After increasing the disk space using your Hypervisor (Hyper-V or VMware), you should reconfigure the appliance to reflect the disk changes.
i) Install parted (not needed for versions above 0.2.5): sudo apt-get install parted
ii) Execute parted (sudo parted) and make sure the active disk is /dev/sda
iii) Type resizepart and select 1 when asked for a partition number. Confirm by typing 'Yes'
iv) Enter the new size of the disk (usually in MB)
v) Issue print command to ensure the new size is reflected

Netscaler 12 Compatibility

Netscaler 12 has "hardcoded" order of authentication sources in XenApp configuration wizard and it is OTP first and AD second. And there is no way to change it. So when users log in, they should put OTP in the first password field and AD password in the second field. The problem here is that the Netscaler does not allow the empty value of Password, so the users without 2FA active will have to put "something" there, which makes the overall user experience cumbersome.

For the time being it is recommended to use the "classic" method of configuring virtual servers with Netscaler, specifying RADIUS as the secondary authentication method