OpenOTP Cloud Bridge Virtual Appliance

Overview

This documentation provides a step-by-step guide on configuring the OpenOTP Cloud Bridge Virtual Appliance. The appliance comes with Rocky Linux 9.1 pre-installed and includes the necessary RCDevs software packages. The following components are included:

Radius Bridge (installed in /opt/radiusd/)
LDAP Bridge (installed in /opt/ldproxy/)

RCDevs strongly recommends using the Virtual Appliance or deploying the LDAP and Radius Bridges on a dedicated server within your infrastructure. This setup ensures secure communication of these protocols without transmitting them over the internet.

Before deploying and configuring the virtual appliance, ensure that your OpenOTP Cloud Tenant is created or that your dedicated hosted infrastructure is deployed.

For the purpose of this documentation, my tenant URL is https://fdn6jl.eu1.openotp.com.

Setups

General information

Here is the refined version of your instructions:

To download the Appliance, visit the RCDevs Website and download the ZIP archive. The Appliance is available in both VMX and OVF formats, compatible with VMware ESX, ESXi, Workstation, and Oracle VirtualBox. After downloading, unzip the archive and follow these steps:

In your VMware environment, select "Import Appliance."
Choose the VMX or OVF file from the extracted files.

Important: Avoid copying and running the appliance directly without importing it. Running the appliance directly may result in a read-only filesystem error during the boot process.

If necessary, you can adjust the CPU and memory settings of the Appliance. By default, it is configured with 1 virtual CPU and 2GB of memory.

If you decide to use the VMX import format (instead of the preferred OVF format), you'll need to set up the VM system manually and use the VMX file as the SCSI storage file. The following configuration tips may be helpful:

Keep the boot console open during the boot process to monitor any startup errors.
The Appliance is set to obtain its IP address via DHCP.

During the first boot, a setup script runs only once and does not require a login password. You can access the console or use SSH to perform the initial setup. If needed, you can restart the appliance setup script using the vm_init command.

The OpenOTP Cloud Bridge VM setup script will prompt you to:

Set the root password to access the virtual machine later.
Configure your time zone.
Configure the network interface.
Set up the Radius Bridge (radiusd) component with your OpenOTP cloud infrastructure (optional).
Set up the LDAP Bridge (ldproxy) component with your OpenOTP cloud infrastructure (optional).

Points 4 and 5 are optional, but if you are configuring the appliance, it is recommended to set up at least one of these services.

During the setup, you will need to access your WebADM Admin Portal to approve the certificate requests for the Radius and LDAP Bridge components.

The first step when you start the Virtual Appliance is to reset the root password and ensure you can access the VM with the newly configured password.

-------------------------------------------------------------------------
Welcome to RCDevs VMWare Appliance package webadm is not installed!
-------------------------------------------------------------------------

Please enter a new root password for console and ssh login: xxxxxxx
Please enter it again: xxxxxxx
Updating password
Please try a ssh login in an other session, does it work? (y/[n]): y

Try logging in through SSH using the root account and the freshly configured password.

Please identify a location so that time zone rules can be set correctly.
Please select a continent or ocean.
1) Africa 
2) Americas
3) Antarctica
4) Arctic Ocean
5) Asia
6) Atlantic Ocean
7) Australia
8) Europe
9) Indian Ocean
10) Pacific Ocean
11) none - I want to specify the time zone using the Posix TZ format.

#? 8

We choose the time zone, for example, Luxembourg (Europe).

Please select a country.
 1) Albania		               18) Guernsey		        35) Poland
 2) Andorra		               19) Hungary		        36) Portugal
 3) Austria		               20) Ireland		        37) Romania
 4) Belarus		               21) Isle of Man	        38) Russia
 5) Belgium		               22) Italy		        39) San Marino
 6) Bosnia & Herzegovina       23) Jersey	            40) Serbia
 7) Britain (UK)	           24) Latvia		        41) Slovakia
 8) Bulgaria		           25) Liechtenstein	    42) Slovenia
 9) Croatia		               26) Lithuania		    43) Spain
10) Czech Republic	           27) Luxembourg	        44) Sweden
11) Denmark		               28) Macedonia		    45) Switzerland
12) Estonia		               29) Malta		        46) Turkey
13) Finland		               30) Moldova		        47) Ukraine
14) France		               31) Monaco		        48) Vatican City
15) Germany		               32) Montenegro	        49) Åland Islands
16) Gibraltar	               33) Netherlands
17) Greece		               34) Norway
#? 27

The following information has been given:

	Luxembourg

Therefore TZ='Europe/Luxembourg' will be used.
Local time is now:	Tue May 16 16:06:47 CEST 2023.
Universal Time is now:	Tue May 16 14:06:47 UTC 2023.

All following options are set with the default value in square brackets. You can keep it by pressing enter.

This VM is running with dynamic IP assignment (DHCP)
The current IP address is 192.168.1.69
Do you want to configure a static IP ([y]/n)? 
y
Please type the fixed IP address [192.168.1.69]: 
192.168.1.69
Please type the network mask [255.255.255.0]: 
255.255.255.0
Please type the gateway address [192.168.1.1]: 
192.168.1.1
Please type your primary DNS server IP [8.8.8.8]: 
8.8.8.8
Please type your secondary DNS server IP []: 

Fixed IP address: 192.168.1.69
Network address: 192.168.1.0
Network mask: 255.255.255.0
Gateway IP address: 192.168.1.1
Primary DNS server: 8.8.8.8
Do you confirm ([y]/n): 
y
Restarting network...
Please enter the hostname [bridge.rcdevs.local]: 
bridge.support.rcdevs.com

The global VM configuration is complete. The next step is to configure the Radius Bridge product.

Radius Bridge

Configuration script

The setup continues as follows, where you will need to provide the FQDN (Fully Qualified Domain Name) of your server for SSL certificate generation and your WebADM/OpenOTP tenant URL.

Do you want to configure radiusd? ([y]/n)? y
Checking system architecture...Ok
Enter the server fully qualified host name (FQDN): bridge.rcdevsdocs.com
If WebADM is running on this server then press Enter.
Else enter one of your running WebADM server IP or hostname.
Note: You can use host:port if WebADM uses a custom HTTPS port.
Enter WebADM server IP or hostname: fdn6jl.eu1.openotp.com

At this step, you need to go to the WebADM interface and accept the SSL certificate request.

Found one server URL: https://fdn6jl.eu1.openotp.com:8443/openotp/
Retrieving WebADM CA certificate... Ok
Retrieving WebADM CA trusted bundle...  Ok
The setup needs now to request a signed SSL server certificate.
This request should show up as pending in your WebADM interface and an administrator must accept it!
Waiting 5 minutes for approbation...

Once accepted, you will have the following output:

Waiting 5 minutes for approbation... Ok
Updating configuration file... Ok
Setting file permissions... Ok
Do you want OpenOTP RADIUS Bridge to be automatically started at boot (y/n)? y
Adding systemd service... Ok
Do you want to register OpenOTP RADIUS Bridge logrotate script (y/n)? y
Adding logrotate script... Ok
OpenOTP RADIUS Bridge has successfully been setup.

The Radius Bridge setup is now complete, and the setup script will proceed with the optional LDAP Bridge configuration. For detailed instructions on fully configuring the Radius Bridge component, please refer to the Radius Bridge documentation.

RADIUS Clients declaration

Please refer to the Radius Bridge documentation to declare a Radius client in your Radius Bridge configuration. By default, all Radius clients are allowed with the shared secret testing123.

Advanced configuration

For a complete configuration and understanding of the Radius Bridge component, please refer to the Radius Bridge documentation.

LDAP Bridge

Overview

The LDAP Bridge allows LDAP authentication to be seamlessly delegated to an OpenOTP server. From the perspective of LDAP client applications, the primary change is that they will now use the LDAP Bridge as their LDAP server, instead of the existing LDAP backends.
The LDAP Bridge operates by relaying LDAP messages to a back-end LDAP server. It intercepts user bind (LDAP authentication) operations and makes an OpenOTP call to authenticate the request. The OpenOTP server should be configured with this LDAP backend for proper authentication.

LDAP Bridge works with Users' Distinguished Name (DN) attribute to authenticate users' credentials with the LDAP backend and with OpenOTP. That is why, the DN structure must be the same on your LDAP architecture and on OpenOTP Cloud.

E.g: If the DN of my user is cn=my_user,cn=users,dc=domain,dc=com in my Active Directory, then in OpenOTP cloud, the DN of my account must be cn=my_user,cn=users where users is an LDAP container containing the object my_user. Do not consider the LDAP treebase (dc=domain,dc=com) on OpenOTP Cloud as you can not configure it by your own.

In that example, the IP of my domain controller is 192.168.4.2.

Configuration script

Now, we are going to configure LDProxy:

Do you want to configure ldproxy ([y]/n):y
Checking the system architecture...Ok
Enter the LDAP server IP or hostname [localhost]: 192.168.4.2
Enter the LDAP server port [389]: 389
Enter the LDAP protocol (ldap/ldaps) [ldap]: ldap
Enter a bindable LDAP account from the back-end with no specific permission: cn=read_only_account,cn=users,dc=support,dc=rcdevs,dc=com
Enter the LDAP account password: xxxxxxx
Enter the WebADM server IP or hostname [localhost]: fdn6jl.eu1.openotp.com
Found one server URL: https://fdn6jl.eu1.openotp.com:8443/openotp/
Retrieving the WebADM CA certificate... Ok
The setup needs now to request a signed SSL server certificate.
This request should show up as pending in your WebADM interface and an administrator must accept it!
Waiting 5 minutes for approbation...

Approve the SSL certificate request from your WebADM Admin GUI, then you are prompted for the following:

Waiting 5 minutes for approbation... Ok
Updating the OpenOTP configuration file... Ok
Do you want OpenOTP LDAP Bridge to be automatically started at boot (y/n)[y]? y
Adding the systemd service... Ok
Do you want to register OpenOTP LDAP Bridge logrotate script (y/n)[y]? y

Adding the logrotate script... Ok
OpenOTP LDAP Bridge has successfully been set up.
Starting the OpenOTP LDAP Bridge... Ok

You can connect your server via SSH with 'ssh root@192.168.1.69'.

You can login RCDevs WebADM Admin Portal at 'https://fdn6jl.eu1.openotp.com'.

Press any key to finish!

LDProxy is now configured. You can configure your client application(s) to use the LDAP protocol targeting the LDProxy service (port 10389 or 10636) instead of your LDAP backend.
LDProxy does not handle authentication with challenge. Ensure that the Challenge Mode Supported setting in OpenOTP is configured to No at your client policy level.

Advanced configuration

For full configuration and understanding of LDAP Bridge component, please refer to the LDAP Bridge documentation.