Tutorial: Manage the LDAP Authentication Method from the Command-line Interface

Abstract

Use this tutorial to manage LDAP as an Access Server authentication method from the command-line interface.

Overview

Use this tutorial to find the commands necessary to manage the LDAP authentication method for Access Server.

In LDAP authentication mode, the users and passwords for authentication are stored in an LDAP server such as OpenLDAP, Windows Server with Active Directory and an LDAP connector, JumpCloud, Okta, or any other LDAP server program that adheres to the LDAP standard. After creating a user in the directory server, you must add this user to Access Server to set user-specific properties like auto-login privilege, group assignment, and static IP. You can do this via the Admin Web UI or the command line. Once the user is present in Access Server with the same name as in the directory server, when this user logs in, Access Server looks up this user in User Permissions and automatically applies the user-specific properties specified there. If you notice that properties aren’t applied, make sure the name is correct. The user name in the directory is leading here.

You can also define the configuration parameters in the Admin Web UI under “Authentication” and “LDAP” via the command line. You can only set some settings from the command line. We list all of the available options below.

Tip

Current Access Server versions use the LDAP3 library. If your Access Server is an older version using the OpenLDAP library, we recommend upgrading.

Prerequisites

Root privileges on your Access Server's console.
A directory service that supports LDAP.

Commands to configure LDAP

Set authentication mode to LDAP:

./sacli --key "auth.module.type" --value "ldap" ConfigPut
./sacli start

Set primary LDAP server address:

./sacli --key "auth.ldap.0.server.0.host" --value <FQDN_OR_IP> ConfigPut
./sacli start

Set backup LDAP server address:

./sacli --key "auth.ldap.0.server.1.host" --value <FQDN_OR_IP> ConfigPut
./sacli start

Optionally set bind credentials (usually an admin account):

./sacli --key "auth.ldap.0.bind_dn" --value <USER_NAME> ConfigPut
./sacli --key "auth.ldap.0.bind_pw" --value <PASSWORD> ConfigPut
./sacli start

Use anonymous binding (the default):

./sacli --key "auth.ldap.0.bind_dn" ConfigDel
./sacli --key "auth.ldap.0.bind_pw" ConfigDel
./sacli start

Base DN to search for user entries:

./sacli --key "auth.ldap.0.users_base_dn" --value <BASE_DN> ConfigPut
./sacli start

LDAP Attribute that contains the user name (sAMAccountName in Active Directory):

./sacli --key "auth.ldap.0.uname_attr" --value <ATTRIBUTE_NAME> ConfigPut
./sacli start

Enable LDAP authentication once you've finished the configuration:

./sacli --key "auth.ldap.0.enable" --value True ConfigPut
./sacli start

Optional configuration commands

Set a friendly name for the LDAP servers (purely for ease of administration):
```
./sacli --key "auth.ldap.0.name" --value <FRIENDLY_NAME> ConfigPut
```
You can specify an additional LDAP expression that must evaluate as true to allow the user to sign in. Below is an example with the requirement that the users trying to log on must be members of a built-in LDAP group called "Administrators" on a directory server where the base DN is "DC=myserver,DC=mycompany,DC=tld". memberOf=CN=Administrators,CN=Builtin,DC=myserver,DC=mycompany,DC=tld. Set this in the configuration database via the command line:
```
./sacli --key "auth.ldap.0.add_req" --value <LDAP_EXPRESSION> ConfigPut
./sacli start
```
Primary LDAP server timeout before switching to backup LDAP server (default is 4 seconds):
```
./sacli --key "auth.ldap.0.timeout" --value <SECONDS> ConfigPut
./sacli start
```

Implicitly chase referrals or not — 0 means no, 1 means yes (default is 0):

./sacli --key "auth.ldap.0.referrals" --value <NUMBER> ConfigPut
./sacli start

Configure using SSL over the connection to the LDAP server or not. There are three possible choices:
1. never: don't use SSL (default setting).
2. adaptive: try using SSL; if that fails, use plain-text.
3. always: always use SSL
```
./sacli --key "auth.ldap.0.use_ssl" --value <VALUE> ConfigPut
./sacli start
```
Configure how to verify the SSL certificate when connecting to the LDAP server. There are three possible choices:
1. never: no peer certificate is required.
2. allow: request a peer certificate, but the session won’t be aborted if the certificate can’t be validated.
3. demand: a valid peer certificate is required, the session will be aborted if one isn’t provided.
```
./sacli --key "auth.ldap.0.ssl_verify" --value <VALUE> ConfigPut
./sacli start
```
Specify a CA certificate bundle file to use for validating the LDAP server certificate (PEM format):
```
./sacli --key "auth.ldap.0.ssl_ca_cert" --value <PATH_TO_FILE_NAME> ConfigPut
./sacli start
```
Note
The <PATH_TO_FILENAME> must be a full path like "/usr/local/openvpn_as/ca_cert.pem".
Get more debug information by setting debug levels (default is 0). Access Server 2.13.0 and newer supports these debug levels:
1. off=0 — nothing is logged.
2. error=10 — only exceptions are logged.
3. basic=20 — library activity is logged, only operation result is shown.
4. protocol=30 — LDAPv3 operations are logged, sent requests and received responses are shown.
5. network=40 — socket activity is logged.
6. extended=50 — LDAP messages are decoded and properly printed.
```
./sacli --key "auth.ldap.0.debug_level" --value <NUMBER> ConfigPut
./sacli start
```
Tip
Refer to LDAP documentation for specific information about the debug levels.
Enable case-sensitive account name matching (the user admin is different from Admin):
```
./sacli --key "auth.ldap.0.case_sensitive" --value "true" ConfigPut
./sacli start
```

LDAP Check

You can enable an additional LDAP check when using auto-login profiles. Before Access Server 2.10, we didn’t have a check for LDAP authentication with these profiles. Instead, Access Server authenticated against the client certificate in the .ovpn profile. This could lead to a use case where you’ve removed or disabled the user in LDAP, but they can still connect to the VPN. Resolving this before 2.10 required manually revoking the autologin certificate for the user. Using the LDAP check is much more user-friendly.

Access Server 2.10 and newer has an LDAP check to ensure the user exists with the LDAP server before successfully connecting. Use the following commands to configure this.

Enforce LDAP authorization for users connecting with auto-login profiles:

./sacli --key "auth.ldap.0.user_exists_check" --value "true" ConfigPut
./sacli start

Disregard LDAP authorization for users connecting with auto-login profiles:

./sacli --key "auth.ldap.0.user_exists_check" --value "false" ConfigPut
./sacli start

The following table helps clarify how to use the LDAP check for your use cases:

LDAP Check Enabled	User Account Present on LDAP	Authorized
Yes	No	No
Yes	Yes	Yes
No	Yes	Yes
No	No	Yes, only if previously imported auto-login profile when the user account was present on LDAP.

In this section: