inWebo LDAP Proxy v1.6 installation and configuration

Release notes

LDAP Proxy 1.6.1 (January, 2022)

New parameter ldap.proxy.max.simultaneous.push for managing parallelization (more details)

LDAP Proxy 1.6.0 (September, 2021)

Optimization of the send notification mechanism
Adding an optional Heartbeat to detect network failures
New parameters to optimize HTTPS API communications
Adding TLS 1.2

Introduction

The TrustBuilder MFA LDAP proxy allows you to add strong authentication via the TrustBuilder service.

Its role is to transmit the LDAP requests to the LDAP server. When a Bind request from the LDAP server is returned successfully, a PUSH request is sent to the TrustBuilder server. The user is then prompted to authenticate (PIN code, fingerprint, etc) on his previously registered device.

If the authentication is successful, the LDAP proxy finalizes the Bind request and the user is authenticated.

Prerequisites

Infrastructure

The machine hosting the proxy must have:

Access to the LDAP server that will be connected to the TrustBuilder proxy
Internet access to reach the TrustBuilder MFA API

Software

Windows or Linux

64-bit environment
Java 8 64 bits for the version without JRE or OpenJDK 8 64 bits

For LDAPS / SSL

.P12 certificate and passphrase from local Authority

Click here to see how to download an inWebo .P12 certificate

Log in to the administration console.
Go to Secure Sites and click on the "Download a new certificate for the API" button.
Set the certificate parameters

Remember the passphrase used. You will need it later for the TrustBuilder LDAP Proxy installation.

Click on Download.

Installation

Install the TrustBuilder LDAP Proxy on a server reachable from your LDAP server.

For Linux operating systems

Retrieve the Linux version: proxy-ldap-packaging-X.Y.Z-linux64.tar.gz

Unpack the archive
Create the config/config.properties file from the config_to_be_completed.properties file
Complete the config/config.properties file (see below)
Start the proxy:

for version using the JRE installed on the system:
POWERSHELL
```
bin/run.sh
```
for version using built-in JRE:
POWERSHELL
```
bin/run_standalone.sh
```

Others installation options:

inWebo proxy service start and stop

If your LDAP proxy listens for services numbered under 1024, you must start the proxy service with a root / administrator user.

Launching the Proxy service in background mode:
BASH
```
sudo ./run_standalone.sh &
```
Stopping the Proxy service:
BASH
```
sudo ./stop.sh
```

Proxy installation as a Linux service

Requires administrator rights

Edit bin/iw_ldap_proxy by replacing
1. @iw_ldap_proxy_installation_dir@ by the path of the installation directory
2. @iw_ldap_proxy_user@ by the user who runs the program
Installation
BASH
```
sudo cp bin/iw_ldap_proxy /etc/init.d/
```
Start the proxy
BASH
```
sudo /etc/init.d/iw_ldap_proxy start
```
Stop the proxy
BASH
```
sudo /etc/init.d/iw_ldap_proxy stop
```

For Windows operating systems

Retrieve the Windows version: proxy-ldap-packaging-X.Y.Z-win64.zip

Unpack the archive
Create the config/config.properties file from the config_to_be_completed.properties file
Complete the config/config.properties file (see below)
Start the proxy

Version using the JRE installed on the system:
VB
```
bin/run.bat 
```
Version using the built-in JRE:
VB
```
bin/run_standalone.bat
```

Others installation options:

Proxy installation as a Windows service

Requires administrator rights

Prerequisite → .NET Framework 4.0

Installation
VB
```
bin\ldap_proxy_service.exe install
```
Service start
VB
```
sc start "inWebo LDAP proxy"  
```
Service stop
VB
```
sc stop "inWebo LDAP proxy"
```
Uninstalling the service
VB
```
bin\ldap_proxy_service.exe uninstall
```

Service settings

When installing the LDAP proxy service on Windows, no automatic restart is set on the service.

Windows service recovery settings

Requires administrator rights

For security reasons, it is important to configure the service to be restarted by default as this will prevent some incidents.
This can be done directly with ldap_proxy_service.exe in the service section of Windows, in the recovery tab of the service.

Configuration

Summary of configuration items to modify

Basic TrustBuilder LDAP Proxy configuration

To configure the TrustBuilder LDAP Proxy, you should edit the configuration file (config.properties). The following table lists the required parameters and their values for a minimal configuration.

Parameters	Value	Description
ldap.proxy.port	389	the service number of the proxy LDAP is listening to accept requests/ default
ldap.host	LDAPServ.domain.test	IP address or Name of the LDAP server to send the request to
ldap.port	389	the service number of the proxy LDAP is listening to accept requests/ default
inwebo.service.id	MyserviceID	your TrustBuilder service ID
inwebo.service.certificate.path	./proxyLDAP/inWebo_Certificate12	the path of the TrustBuilder P12 certificate generated by your Administration console
inwebo.service.certificate.passphrase	mypassphrase	the passphrase of the TrustBuilder certificate

Configure your LDAP authentication

Depending on your integration, you will have to configure some settings to redirect the authentication requests to the TrustBuilder LDAP Proxy, instead of LDAP server.

The TrustBuilder LDAP Proxy’s role is to transmit the LDAP requests to the LDAP server. When a Bind request from the LDAP server is returned successfully, an additional authentication request will be sent in HTTPS to the TrustBuilder platform. This additional request is based on the user attribute defined in the inWebo LDAP Proxy configuration and retrieved from the user profile (uid, cn, samAccount, userPrincipleName)

Creating the LDAP credentials (DN) for Binding requests on LDAP server

To bind the LDAP proxy to the target LDAP server it is recommended to indicate or even create a whitelisted DN/Account used to search the LDAP.
ex: CN=ReadOnly,CN=Users,DC=domain,DC=test

This profile will be used as credentials with the LDAP and should not trigger inWebo push authentication each time you send a request to the LDAP server.

Whitelisting the LDAP credentials (DN) in the Configuration.properties file

ldap.proxy.whitelist.dn=CN=ReadOnly,CN=Users,DC=domain,DC=test

This configuration should be replicated on the Appliance/authentication server that will send the request to the inWebo LDAP proxy

Modifying the Appliance / authentication portal to send requests to your LDAP proxy

When configuring the LDAP server on your Appliance / Authentication portal, if an existing configuration already exists to authenticate on the LDAP server, you can duplicate and only replace the IP Address by the address of the LDAP proxy.
Be sure to verify that the LDAP Credentials (DN) / used by this appliance are whitelisted on the LDAP proxy.

Creating the Appliance / authentication portal configuration to send request to your LDAP proxy

If there is no existing profile, you have to indicate the following information:

you have to indicate a new LDAP authentication server:
the IP address of the LDAP proxy
the LDAP proxy service number (as indicated previously)
the Base DN of the LDAP server ex: DC=domain,DC=test
the group DN of the LDAP users if existing ex: CN=inWebo,OU=New_York,
the LDAP credentials DN used previously (ldap.proxy.whitelist.dn) CN=ReadOnly,CN=Users,DC=domain,DC=test
with the corresponding password

Testing LDAP Proxy authentication

Run the following command line to test the push Authentication of an inWebo login for your service and see if you are correctly notified with the current inWebo configuration (serviceID, inWebo Certificate, Passphrase).

included for Linux and Windows

VB

run_standalone -doPush <login_inWebo>

Troubleshooting LDAP Proxy configuration

Run the following command line to check if the LDAP configuration and the Bind command are successful

included for Linux and Windows

VB

run_standalone -validateConfiguration <DN>

For example: run_standalone -validateConfiguration CN=Administrator,CN=Users,DC=Domain,DC=test

Managing simultaneous push requests

ldap.proxy.max.simultaneous.push
The maximum number of simultaneous push requests that can handle the LDAP proxy. This value must be greater than or equal to 1. The default value is 100.

Microsoft Active Directory group configuration

If you wish to activate inWebo MFA only for a subset of your Microsoft Active Directory users (a.k.a. group) you must use either of these group configurations.

Both are valid because MS AD provide by default both group configurations. Choose the one which is the more suitable for you.

CODE

# sAMAccountName is typically use for AD, other possibility is cn
# This will be matched with the user “login” (mandatory today) field within inWebo tenant
# to be noted, ldapproxy default (uid) will not work with MS AD
ldap.proxy.login.attribute=sAMAccountName
# group DN for which members will be required to authenticate with inWebo (other users will not use MFA)
# /!\ Change value
ldap.proxy.do.step.up.group.base.dn=CN=<inWebo_group>,DC=<domain>,DC=<tld>
# Choose group membership within the user attributes, with memberOf attribute
ldap.proxy.do.step.up.by.type=user
# LDAP attribute for user memberOf
ldap.proxy.do.step.up.lookup.ismemberof.attribute=memberOf

or

Note here that there is an additional mandatory setting ldap.proxy.do.step.up.filter.group.object.class=group

CODE

# sAMAccountName is typically use for AD, other possibility is cn
# This will be matched with the user “login” (mandatory today) field within inWebo tenant
# to be noted, ldapproxy default (uid) will not work with MS AD
ldap.proxy.login.attribute=sAMAccountName
# group DN for which members will be required to authenticate with inWebo (other users will not use MFA)
# /!\ Change value
ldap.proxy.do.step.up.group.base.dn=CN=<inWebo_group>,DC=<domain>,DC=<tld>
# Choose group membership with group DN entry
ldap.proxy.do.step.up.by.type=group
# LDAP attribute for group members within the DN group entry
ldap.proxy.do.step.up.lookup.member.attribute=member
# LDAP objectClass attribute used to define a group within MS AD
# to be noted, ldapproxy default (group) will not work with MS AD
ldap.proxy.do.step.up.filter.group.object.class=group

Advanced parameters for inWebo LDAP Proxy

In the LDAP proxy configuration section, you can set additional parameters.

If you need help using the advanced parameters, please contact our inWebo support team.

Click here to see the advanced parameters

Transport Layer Security (TLS) Parameters

For sending requests to the LDAP proxy: ldap.proxy.cipher.protocol
When forwarding the request to the LDAP: proxy.cipher.protocol

Possible values:

Automatic choice of JVM: "TLS"
Protocol TLS v1: TLSv1
Protocol TLS v1.1: TLSv1.1
Protocol TLS v1.2: TLSv1.2

Managing LDAP requests timeouts

You can set timeout values for requests

For the Request timeout between the LDAP proxy and the LDAP server
Value in ms. Default 0 ( no timeout )
Setting: ldap.proxy.request.timeout
If a response is not received from the Directory Server within the timeout period, then the operation will be abandoned and an Exception error result returned.
A timeout setting of 0 disables operation timeout limits
For the Request timeout between the LDAP client and the LDAP proxy
Value in ms. Default 10000 ( 10sc )
Setting: ldap.proxy.connect.timeout
If a connection is not established within the timeout period (incl. SSL negotiation, initial bind request, and/or heart-beat), then an Exception error result will be returned.
The default operation timeout is 10 seconds and a timeout setting of 0 causes the OS connect timeout to be used.
When the timeout value is exceeded
An error is returned when the connection failed
"Authentication to LDAP failed : < information>"
The error is logged in the LDAP Proxy log file

Managing application threads and HTTP connection pool

To configure the number of threads allowed by the proxy LDAP app

ldap.proxy.selector.thread.count :
The number of simultaneous request that the LDAP proxy can perform. The default value is depending of the hardware (It's the maximum between 2 and the available processors / 2 )

To configure the HTTP connection pool

inwebo.client.http.timeout : (the default value is 30 seconds)
Read timeout interval and connect timeout interval, in milliseconds. A value of zero 0 is equivalent to an interval of infinity.
inwebo.pool.http.max.total : (the default value is 100)
The maximum number of connections allowed across all HTTP routes.
inwebo.pool.http.default.max.per.route : (the default value is 40)
The maximum number of connections allowed for a HTTP route.

The config.properties file

The following settings are in the config / config.properties file.

The config / config.properties file contains all the LDAP Proxy Configuration settings.

Click here to see the config.properties file

CODE

###############################
# LDAP Proxy configuration file
###############################

# Once complete, you must rename this file as config.properties

##################################
# LDAP PROXY CONFIGURATION SECTION
##################################
# Listening IP adresses used by the LDAP proxy
# List of IP/hostname separated by ";"
# All local addresses by default
#ldap.proxy.addresses=

# Listening port for the LDAP proxy
ldap.proxy.port=389

# Listening port for the LDAP proxy to handle LDAPS requests
#ldap.proxy.ssl.port=636

# LDAP server address/hostname
ldap.host=

# LDAP server port
# Required if ldap.proxy.port is set
ldap.port=389

# LDAPS server port
#ldap.ssl.port=636

# full path to a p12 certificate associated with the LDAP
#ldap.proxy.ssl.certificate.path=

# LDAP certificate passphrase
#ldap.proxy.ssl.certificate.passphrase=

# Mode of server certificate verification
# none by default
#   jvm      : use the JVM keystore
#   none     : trust all server certificates
#   keystore : use a specific keystore define by ldap.ssl.certificate.keystore et ldap.ssl.certificate.passphrase
#ldap.ssl.certificate.verification.mode=

# The path of the keystore to use when ldap.ssl.certificate.verification.mode=keystore
#ldap.ssl.certificate.keystore.path=

# The keystore pass associated to ldap.ssl.certificate.keystore.path
#ldap.ssl.certificate.keystore.passphrase=

# Protocol used for requesting the LDAP proxy
# default is TLS
#ldap.proxy.cipher.protocol=

# Protocol used by the LDAP proxy to request the LDAP
# default is TLSv1
#proxy.cipher.protocol=

# Request timeout between proxy and LDAP server ( in ms )
# default 0 ( no timeout )
#ldap.proxy.request.timeout=

# Timeout of proxy requests ( in ms )
# default 10000 ( 10sc )
#ldap.proxy.connect.timeout=

# Configures the connection factory to periodically send "heart-beat" or "keep-alive" requests to the Directory Server.
# Possible values : true | false
# default is false (no heartbeat)
#ldap.proxy.heartbeat.enabled=

# Specifies the time between successive heart-beat requests
# default 10000 (10s)
#ldap.proxy.heartbeat.interval=

# Specifies the timeout for heart-beat requests, after which the remote Directory Server will be deemed to be unavailable
# default 3000 (3s)
#ldap.proxy.heartbeat.timeout=


# Number of thread used for handle LDAP request
# This value define the number of simultaneous request that the LDAP proxy can perform
# The default value is depending of the hardware (It's the maximum between 2 and the available processors / 2 )
#ldap.proxy.selector.thread.count=

# The maximum number of simultaneous push request that can handle the ldap proxy
# This value must be gretter or equal to 1
# The default value is 100
#ldap.proxy.max.simultaneous.push=

######################################
# INWEBO SERVICE CONFIGURATION SECTION
######################################

# InWebo service ID
inwebo.service.id=

# full path to the p12 certificate associated with the InWebo service
inwebo.service.certificate.path=

# inWebo certificate passphrase
inwebo.service.certificate.passphrase=

# LDAP attribute for user login (will be matched with InWebo login)
# uid by default
#ldap.proxy.login.attribute=

# Condition to authenticate users with InWebo
# all by default
#   all      : all user will be authenticated with inWebo
#   none     : no user will be authenticated with inWebo (transparent)
#   user     : user group membership. Based on the group list the user is member of
#   group    : user group membership. Based on the group member list
#ldap.proxy.do.step.up.by.type=all

# LDAP group DN for which members will be required to authenticate with inWebo. Required if ldap.proxy.do.step.up.by.type is set to "user" or "group"
#ldap.proxy.do.step.up.group.base.dn=

# LDAP attribute for group members. Required when ldap.proxy.do.step.up.by.type = group 
# member by default
#ldap.proxy.do.step.up.lookup.member.attribute=

# LDAP attribute for group list. Required when ldap.proxy.do.step.up.by.type = user
# isMemberOf by default. Use memberOf for AD
#ldap.proxy.do.step.up.lookup.ismemberof.attribute=

# LDAP objectClass attribute used to define a group
# groupOfNames by default
#ldap.proxy.do.step.up.filter.group.object.class=

# LDAP objectClass attribute used to define a user
# person by default
#ldap.proxy.do.step.up.filter.user.object.class=

# Bypass inWebo authentification for a list of users (usefull for technical accounts)
# DN list separated by ";"
#ldap.proxy.whitelist.dn=
 
# 16 characters key used to cipher logins
# No cipher by default
#inwebo.cipher.aes.secret.key=

##################################
# INWEBO API CONFIGURATION SECTION
##################################

# InWebo API URL
# https://api.myinwebo.com/FS by default
#inwebo.base.url=

# HTTP timeout in second (the default value is 30 seconds)
#inwebo.client.http.timeout=30

# The maximum number of connections allowed across all routes. (the default value is 100)
#inwebo.pool.http.max.total=100

# The maximum number of connections allowed for a route that has not been specified. (the default value is 40)
#inwebo.pool.http.default.max.per.route=40

# Force ldap-proxy to contact inWebo through an http or https proxy
# HTTP proxy host used to call InWebo
# No HTTP proxy by default
#inwebo.proxy.host=hostname_or_ip

# HTTP proxy port
#inwebo.proxy.port=port

# Use https to proxy
# false by default - http only (http://hostname:port)
# true - https only (https://hostname:port)
#inwebo.proxy.https=true

# HTTP proxy login - option
#inwebo.proxy.username=proxy_user_login

# HTTP proxy password - option
#inwebo.proxy.password=proxy_user_password

Integration examples

Here are some inWebo documentations that refer to third-party integration, using inWebo LDAP proxy.