OpenOTP LDAP Bridge
  Download PDF

1. Product overview

The main use-case of OpenOTP LDAP Bridge is enabling enterprise applications that use LDAP as external authentication mechanism to work with OpenOTP. LDAP Bridge allows authentication to be delegated to an OpenOTP server transparently, without changing the LDAP back-end. From the client applications perspective, the main change is that it will use the LDAP Bridge as an LDAP server, instead of the backend-end LDAP server.

LDAP Bridge works 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 with OpenOTP. It then sets the result of the bind request to the authentication result of the OpenOTP call.

One drawback of LDAP protocol is that LDAP bind does not support challenge-response or interactive user dialogue, which means that all authentication factors must be passed concatenated in one unique login request. Like RCDevs’ OpenOTP RADIUS Bridge, LDAP Bridge is not designed to be exposed to the internet, but rather to sit besides WebADM, or in a DMZ.

2. System requirements

LDAP Bridge runs on Linux 64bit operating systems with GLIBC ≥ 2.5. The installation package contains all the required dependencies allowing LDAP Bridge to run on any Linux system without any other requirement.

LDAP Bridge requires a working OpenOTP+WebADM installation (version ≥ 1.4) connected to a LDAP backend.

The LDAP Bridge can be run on the same server as OpenOTP and WebADM. A standlone LDAP Bridge should meet the following requirements:

  • Running a Linux distribution with Glibc ≥ 2.5 installed (RedHat, Centos, SuSe, Debian, Ubuntu).
  • At least a 1 GHz x86-64 processor (two cores or vCPUs recommended).
  • 512 MB of RAM.
  • At the very least 20MB of free disk space.

3. Installation

3.1 Install with yum repository

On a RedHat, Centos or Fedora system, you can use our repository, which simplifies installation and updates.

Add the repository:

curl http://www.rcdevs.com/repos/redhat/rcdevs.repo -o /etc/yum.repos.d/rcdevs.repo

Clean the yum cache and install LDAP Bridge:

yum clean all
yum install ldproxy

3.2 Install with Debian repository

On a Debian system, you can use our repository, which simplifies installation and updates.

Add the repository:

echo "deb http://rcdevs.com/repos/debian ./" > /etc/apt/sources.list.d/rcdevs.list
apt-key adv --fetch-key http://rcdevs.com/repos/debian/RPM-GPG-KEY-rcdevs.pub

Clean the cache and install WebADM with all WebApps & Services:

apt-get update
apt-get install ldproxy

3.3 Install using the self-installer

You first need to download and install the LDAP Bridge software package. You can download OpenOTP LDAP Bridge on the RCDevs Website and copy it to your server. You can copy the package file to the server with WinSCP or scp. Then connect via SSH to your server, uncompress and run the self-installer package with:

gunzip ldproxy-1.1.*.sh.gz
bash ldproxy-1.1.*.sh

The installation process will automatically run the console-based setup script in bin/setup.

4. configuration

Once the package is installed, you can run the setup script:

[root@ldproxy ~]# /opt/ldproxy/bin/setup 
Checking system architecture...Ok

You insert the hostname of the LDAP Bridge server for the certificate generation:

Enter the server fully qualified host name (FQDN): ldproxy.test.local
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.

You enter the IP of the WebADM server:

Enter WebADM server IP or hostname: 192.168.3.148
Found one server URL: https://192.168.3.148:8443/openotp/
Retrieving 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... Ok

You connect to the WebADM interface and approve the certificate request:

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

You can edit the configuration and set the LDAP server URI:

vi /opt/ldproxy/conf/ldproxy.conf

…
ldap_uri1 "ldap://192.168.3.148:636"
…

Now, you can restart ldproxy:

/opt/ldproxy/bin/ldproxy restart

You can use ldapsearch for testing. If it’s not already available, yo can install it with yum install openldap-clients on centos. In this example, the user john is reading informations about itself, his passwors is password and his OTP is 637991:

[root@ldproxy ~]# ldapsearch -H ldap://localhost:10389 -D  cn=john,o=Root -w password637991 -b cn=john,o=Root 
# extended LDIF
#
# LDAPv3
# base <cn=john,o=Root> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#

# john, Root
dn: cn=john,o=Root
objectClass: webadmAccount
objectClass: person
objectClass: inetOrgPerson
cn: john
uid: john
sn: john
userPassword:: e1NTSEF9ckloR2QzQTNvaWROUkVuSzdCVTQ4dmV1eEtQRkF1ZkQ=
webadmData: OpenOTP.TokenType={wcrypt}utxATYuu7ybSc3qUDzC93A==,OpenOTP.TokenKe
 y={wcrypt}XtG15KtCl/O80XoPnvbVXKRpmcJAuXX9oioBG5XN2rY=,OpenOTP.RejectCount=MT
 c=,OpenOTP.TokenState={wcrypt}vJcqiQgAgWb5C5cRYOVZFg==,OpenOTP.LastLogin=MjAx
 OC0wNS0wOSAxNDozMDowMg==,OpenOTP.LoginCount=MTg=,OpenOTP.LastOTP={wcrypt}bPTq
 yKL8FCglZytS4g6K7e+VVgD1+uFbwAdAU7+/SPY=,DataMode=A+kiYp4=

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

You can also define other settings in ldproxy.conf:

  • soap_timeout, which is the time in seconds without before LDproxy’s connection to OpenOTP times out. The LDAP clients of LDproxy must have a higher tolerance than soap_timeout to time outs when connecting to LDproxy.

  • user_settings, which are the public OpenOTP settings that will be passed in every request. OpenOTP must be configured with “Allow Request Settings” in WebADM. These settings will have priority over any setting define on the users, groups, client policies and OpenOTP configuration.

  • client_id, the Client ID that will be set in every request to OpenOTP, who can then match requests to a client policy with the same name (or alias).

  • default_domain, the WebADM domain that, in the current LDproxy version, will be set on every request to OpenOTP.

  • server-policy, the load-balancing policy of requests between OpenOTP servers, if two servers are defined in server_url.

  • status_cache, the time in seconds between health polls of the backend OpenOTP servers.

  • ignored_dn, a list of users who don’t nee to use OpenOTP, the authentication is not redirected to the OpenOTP server.

  • denied_dn, a list of users who are not allowed to be authenticated by OpenOTP, they will receive an authentication failed.

ldproxy.conf can also contain client sections, which can, for requests coming from a single client, override client_id, default_domain and ignored_dn (see below for this one).

Upgrades of LDAP Bridge will overwrite the file /opt/ldproxy/conf/ldproxy.conf.default, which will indicate the default values for any new configuration directive added by the upgrade. If new directives or any significant change has been added, it will be mentioned in /opt/ldproxy/RELEASE_NOTES.

3.1 LDAP Ports

LDAP Bridge provides the LDAP service over the following ports:

  • TCP 10389 for un-encrypted LDAP and TLS
  • TCP 10636 for LDAP over SSL

The LDAP Bridge’s default listening network interface and ports can be changed by creating an environment file /opt/ldproxy/conf/ldproxy.env with the following configurations:

##This is ldproxy.env example

INTERFACE=0.0.0.0
PORT_STD=10389
PORT_SSL=10636

4. Maintenance and troubleshooting

This section should cover your common administrative tasks concerning LDAP Bridge. For additional support you can contact RCDevs’ commercial support if you are a client or our Google Group if you are using the freeware edition of OpenOTP.

4.1. Starting and stopping

If during the setup, you’ve let the installer set the LDProxy init scripts and systems service files on your machine, the LDAP Bridge should start at machine boot. You should also be able to start and stop the LDAP Bridge through your distribution’s usual commands, such as systemctl start ldproxy for distributions using systemd like RedHat Enterprise Linux 7.

Alternatively, you can use

/opt/ldproxy/bin/ldproxy start | restart | stop

4.2. Upgrading and un-installing

If LDAP Bridge was installed using RCDevs repository, it will be updated with the system when you will execute yum update or apt-get upgrade.

If was installed with the tar file, you can download and install it as you did for your first installation. The installer will offer you the option of upgrading your installation.

Be aware that, to do so, the installer will stop LDProxy. As a matter of principle, you should backup the /opt/ldproxy/ directory before the upgrade. You can then restore the directory if anything breaks and restart the LDProxy service.

The installer also gives you the option of removing an existing LDProxy installation.

You can reset your installation by executing /opt/ldproxy/setup reset, which removes any init, systemd and logrotate files the installer put on the machine. This will also remove the log files, SSL certificate and secret key.

4.2.1 Upgrading from 1.0.x to 1.1.x

The version 1.1.0 includes sevaral changes. You probly need to change some settings manually.

Before the update, keep a backup of /opt/ldproxy/conffolder, then run the update.

Once it is done, if you don’t have changed the default port, you probably need to change it. The previous version used 389 and 636 and the new version 10389 and 10636. If you want to continue to use 389 and 636, you need to create /opt/ldproxy/conf/ldproxy.env with the following content:

PORT_STD=389
PORT_SSL=636

You need also to copy uri and ignored_dn from slapd.conf to ldproxy.conf. uri is now called ldap_uri1.

To finish, you need to replace denied_usernames with denied_dn, replace nolock_usernames with nolock_dn, replace all usernames with their distingished name and remove uid_attribute in ldproxy.conf.

You can use ldproxy.conf.default as an example of the new configuration.

4.3. Troubles and known issues

LDAP Bridge was not designed to work with SELinux. If your host has SELinux enabled, you should set its mode to Permissive. On RedHat 7, you can execute setenforce Permissive, and set SELINUX to permissive in /etc/selinux/config to make the change permanent.

You can start LDAP Bridge in debug mode to get a verbose output of what the proxy does on your terminal.

service ldproxy debug <logleve>

If you omit <logleve>, it will be setted to statsby default, but you can also choose another loglevel:

loglevel Description
any enable all debugging
trace trace function calls
packets debug packet handling
args heavy trace debugging
conns connection management
BER print out packets sent and received
filter search filter processing
config configuration processing
ACL access control list processing
stats stats log connections/operations/results
stats2 stats log entries sent
shell print communication with shell backends
parse print entry parsing debugging
sync syncrepl consumer processing
none only messages that get logged whatever log level is set