Arculix LDAP Agent deployment guide

Any virtualization platform that is capable of hosting Linux or Windows servers should be suitable, including on-premises solutions such as VMware ESXi and Microsoft Hyper-V, and cloud environments such as Amazon EC2 and Microsoft Azure.

All communication with the LDAP Agent is over HTTPS. There is an additional layer of security that provides authenticity above and beyond the HTTPS certificates by signing all communication.

The Arculix LDAP Agent communicates with the user directory using the LDAP protocol. Before deployment, a user account must be provisioned which allows read-only access to the directory.

The following information needs to be prepared before the installation:

The package may be installed using:

rpm -ivh acceptto-ldap-agent-X.Y.Z-1.x86_64.rpm

After installation, the customer should configure the agent using the YAML configuration file in /etc/acceptto/ldap-agent.conf. See the LDAP Agent configuration section below for full details on configuring the LDAP Agent.

After configuration, you can test the agent's connectivity to the LDAP server using the following commands. If you've used the YAML configuration (ldap-agent.conf), run the following command to test your installation:

ldap-agent -config /etc/acceptto/ldap-agent.conf -test

( set -a && source /etc/acceptto/ldap-agent.env && ldap-agent -test )

You should see diagnostics output similar to the following:

Using configuration: Config(AgentID=ldap:v1:f6ac662c-0c4f-45b2-8721-13388db62f8e,SharedSecret=✓,
  SwitchboardURL=wss://switchboard.acceptto.com,LogLevel=info,AuthenticationTimeout=5s,
  RequestTimeout=10s,RequestWorkers=500,LDAPURLs=[ldaps://ad1.acceptto.local/],
  LDAPBindUser=abe.lincoln@acceptto.local,LDAPBindPass=*****,LDAPBaseDN=dc=acceptto,dc=local,
  LDAPTLSDisableVerification=false,LDAPTLSTrustedCAs=✓,LDAPTLSServerNames=[])
Healthy: true
LDAP query time: 22 ms

After a successful connectivity test, the agent should be enabled in systemd to arrange for its launch when the server boots:

systemctl enable acceptto-ldap-agent

Then, start the agent:

systemctl start acceptto-ldap-agent

The agent may be upgraded to a newer version by using the -U option of RPM instead of -i:

rpm -Uvh acceptto-ldap-agent-X.Y.Z-1.x86_64.rpm

The package may be removed using:

rpm -e acceptto-ldap-agent

Any running LDAP Agent instance will be shut down. Any modified configuration file will be renamed and preserved with a .rpmsave extension.

To install the Arculix LDAP Agent, first upload the provided ldap-agent-X.Y.Z.tar.xz archive to the server. (Where X.Y.Z, here and elsewhere in the installation instructions, is the version of this release.) On the server, find the archive and extract it using the following command:

tar -xvJ -f ldap-agent-X.Y.Z.tar.xz

Note that the extraction will create an ldap-agent-X.Y.Z directory containing the installation assets. Change to this directory:

cd ldap-agent-X.Y.Z

If this server does not have Docker and Docker Compose installed, they can be installed using the provided helper script:

sudo ./install-docker.sh

(Note the use of sudo, as this step requires root access.)

If this is a new installation, SecureAuth will provide an ldap-agent-config.env configuration file template pre-configured with any credentials needed to pair your agent with Arculix. You should edit this file using an editor of your choice (vi, vim, nano, or whatever editor may be available in your Linux system):

vi ldap-agent-config.env

This configuration file supplies settings in the form of environment variables. See the LDAP Agent configuration section below for full details on configuring the LDAP Agent.

Finally, to install the agent, run the install.sh script from a user account with sufficient privileges to manage Docker:

sudo ./install.sh

Note that sudo is used in the above example to run the script as root, which should always have Docker privileges.

The installation process needs a destination directory where it can store agent assets such as the configuration file. It will suggest a default path, but you can provide an alternate location if desired.

After the LDAP Agent is installed, you can test connectivity from the agent to Active Directory:

You should see diagnostics output similar to the following:

Using configuration: Config(AgentID=ldap:v1:f6ac662c-0c4f-45b2-8721-13388db62f8e,SharedSecret=✓,
  SwitchboardURL=wss://switchboard.acceptto.com,LogLevel=info,AuthenticationTimeout=5s,
  RequestTimeout=10s,RequestWorkers=500,LDAPURLs=[ldaps://ad1.acceptto.local/],
  LDAPBindUser=abe.lincoln@acceptto.local,LDAPBindPass=*****,LDAPBaseDN=dc=acceptto,dc=local,
  LDAPTLSDisableVerification=false,LDAPTLSTrustedCAs=✓,LDAPTLSServerNames=[])
Healthy: true
LDAP query time: 22 ms

After installation, the extracted contents of the archive are no longer needed and may be removed:

cd ..
rm -rf ldap-agent-X.Y.Z

Upgrading to a newer version of the LDAP Agent works mostly the same as performing a fresh installation: extract the provided archive and run its install.sh script. Note the following minor differences:

The LDAP agent may be removed by shutting down the Docker container, then removing the installed files from the system. First, change directory to the installed location, then use Docker Compose to shut down the agent:

cd /root/acceptto/ldap-agent
docker-compose down

You will see output similar to the following:

Stopping ldap-agent ... done
Removing ldap-agent ... done
Removing network ldap-agent_default

After the container is shut down in this way, it will not restart when the system reboots. If the agent shutdown is meant to be temporary, you can run docker-compose up -d in the installation directory at a future time to restart the agent. To remove the agent permanently, simply remove the installation directory entirely.

Download the latest version of the Arculix LDAP Agent to a Windows Server that is prepared for installation. This server can be a member server in your Active Directory domain or a domain controller.

After the LDAP Agent is installed, you can test connectivity from the agent to your LDAP server:

The LDAP Agent may be upgraded to a newer version using these steps:

The LDAP Agent may be removed the same way as most Windows applications:

The agent's configuration file (ldap-agent.conf) will remain in the installation directory, and will be used if another LDAP Agent is installed in the same directory in the future.

The following configuration files are templates for a minimal configuration setup. You may add more parameters as specified in the Configuration options section.

# Login to https://mfa.acceptto.com and go to the "Connectors" page to get the
# "Agent ID" and "Shared Secret" parameters.
AgentID: CHANGE_ME
SharedSecret: CHANGE_ME

# The LDAP parameters used to reach Active Directory
LDAPURLs:
    - ldaps://acceptto.local/
LDAPBindUser: administrator@acceptto.local
LDAPBindPass: verysecret
LDAPBaseDN: dc=acceptto,dc=local

# If using LDAPS and the LDAP server's certificate is not issued by a public
# certificate authority, a trusted root CA or the LDAPS certificate itself may
# provided here to establish trust.
#
# LDAPTLSTrustedCAs: |
#     -----BEGIN CERTIFICATE-----
#     MIIFdzCCA1+gAwIBAgIUPhmZ5ytNQDJ1gqIYtPWXsFSXbm8wDQYJKoZIhvcNAQEL
#     BQAwYzELMAkGA1UEBhMCVVMxDzANBgNVBAgMBk9yZWdvbjERMA8GA1UEBwwIUG9y
#     ...
#     nRFv5H77DMo15HfFgGsy7zCt7OrIHl/G/PVLce4/4T+cLjahHDbn5J6Cz9DWNYYq
#     jRgO45686HIchzfyTpPRbdt+S7TA+1ToUX5nlnCFhsgcCwBuPqCozNBvTbYN7xdq
#     fkATtpM5lE4Ip7Y=
#     -----END CERTIFICATE-----

######################################################################
# To use this configuration, source this script into your bash shell:
#   ( set -a && source /etc/acceptto/ldap-agent.env && ldap-agent -test )
######################################################################

# Login to https://mfa.acceptto.com and go to the "Connectors" page to get the
# "Agent ID" and "Shared Secret" parameters.
ALA_AGENT_ID=CHANGE_ME
ALA_SHARED_SECRET=CHANGE_ME

# The LDAP parameters used to reach Active Directory
ALA_LDAP_URLS='ldap://acceptto.local/'
ALA_LDAP_BIND_USER='administrator@acceptto.local'
ALA_LDAP_BIND_PASS='verysecret'
ALA_LDAP_BASE_DN='dc=acceptto,dc=local'

# If using LDAPS and the LDAP server's certificate is not issued by a public
# certificate authority, a trusted root CA or the LDAPS certificate itself may
# provided here to establish trust.
#
# ALA_LDAP_TLS_TRUSTED_CAS='
# -----BEGIN CERTIFICATE-----
# MIIFdzCCA1+gAwIBAgIUPhmZ5ytNQDJ1gqIYtPWXsFSXbm8wDQYJKoZIhvcNAQEL
# BQAwYzELMAkGA1UEBhMCVVMxDzANBgNVBAgMBk9yZWdvbjERMA8GA1UEBwwIUG9y
# ...
# nRFv5H77DMo15HfFgGsy7zCt7OrIHl/G/PVLce4/4T+cLjahHDbn5J6Cz9DWNYYq
# jRgO45686HIchzfyTpPRbdt+S7TA+1ToUX5nlnCFhsgcCwBuPqCozNBvTbYN7xdq
# fkATtpM5lE4Ip7Y=
# -----END CERTIFICATE-----
# '

The following configuration items are required for the agent to start:

The following configuration items are optional, and may be used to further guide the behavior of the agent:

Some customers will provide a pool of LDAPS servers behind a load balancer. Thus, the agent will be configured with a single specific URL which points to the load balancer, but each backend LDAPS server may present a different certificate with a different hostname embedded. This can prevent certificate verification from working if we connect to the load balancer and expect a certificate that matches either the load balancer's address or a single item in LDAPTLSServerNames which corresponds to the single LDAPS URL.

Potential remedies include: