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 username 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 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: