LDAP Troubleshooting Guide for OpenVPN Access Server


OpenVPN Access Server can look up users in directory services using Lightweight Directory Access Protocol (LDAP). You configure LDAP authentication with the Admin Web UI or the command-line interface.

This document provides troubleshooting help for various error messages and use cases customers have encountered. Feel free to reach out to support for help as well.

Enable verbose debugging

You can enable verbose authentication debugging to help troubleshoot connection issues with an LDAP configuration for your specific directory service.

To enable verbose authentication debugging, sign in to the terminal or connect via SSH to your Access Server and execute the following commands:

sudo echo "DEBUG_AUTH=true" >> /usr/local/openvpn_as/etc/as.conf
sudo service openvpnas restart

Once enabled, Access Server logs verbose authentication messages to the standard OpenVPN Access Server log file at /var/log/openvpnas.log. You can send the file to our support team, and they’re more than happy to assist you further.

Once you’ve finished debugging, we recommend that you turn off authentication verbose logging to prevent your logs from growing too fast.

To turn off authentication verbose logging, simply comment out the line by putting a pound/hash sign before the DEBUG_AUTH line and save the file (you can also delete the line altogether). Afterward, restart the service using the restart command mentioned above.

nano /usr/local/openvpn_as/etc/as.conf

Delete or comment out “DEBUG_AUTH=true”.

sudo service openvpnas restart

User Not Found

A common error message related to LDAP authentication issues is user not found (that meets specified requirements). Follow these tips for troubleshooting:

  • Simplify your query to just the base DN with ‘DC=example,DC=com’, substituting “example” and “com” with the domain information for your server. The issue is often caused by the user not found in the search, based on the attributes expected. To put it simply, the user may not be where you told it to look. Widening the search can be helpful in determining if this is the case.
  • If a directory-wide search still returns the error, the LDAP attribute you’re searching for that should contain the username could be different. Try “sAMAccountName” or “uid”; those are usually the attributes that contain the username. Refer to your LDAP server documentation on what attribute to use.
  • Check for case sensitivity on containers and objects. For example, the LDAP server may only accept “cn=example” and not “CN=example”. Refer to your LDAP server documentation for specifics.
  • If you encounter this error message because your LDAP query narrows it down to specific groups, it may fail. Ensure that your additional query is the full query such as this: memberOf=CN=VPN Users, OU=Security Groups, DC=company, DC=com. If you only use the query memberOf=CN=VPN Users, it could fail.

Access denied or invalid creds with Okta

If you encounter an error message, Access denied, or invalid creds, it may be that you haven’t completed the multifactor configuration in the security section of your Okta admin panel. Also, if you check the logging in your RADIUS app, you’ll see the error message, “User does not have a valid factor enrolled.”

This is because the RADIUS app has a requirement to use multifactor, through a default sign on rule.

To resolve the error, you can either set up Multifactor for users or create a new sign-on rule with a higher priority.

Setup Okta Multifactor (option 1)

  1. In your Okta admin panel, go to Security > Multifactor.
  2. Setup and configure the MFA factor of your choice.

Create a rule that doesn’t require MFA for signing in (option 2)

  1. From the Sign On tab for your RADIUS application, scroll to the bottom and click on Add Rule.
  2. Enter the new rule without the Multifactor box checked and click Save.
  3. Ensure your new rule is a higher priority than the default rule and your users will no longer be prompted for an additional authorization.

MFA causes user to get locked out

If your user receives a ‘LOCKOUT’ error message when attempting to sign in, it may be due to the steps it takes to enroll in MFA through their OpenVPN Client UI. This is tied to Access Server's lockout policy. Refer to Authentication failure lockout policy for the default values and how to adjust settings. 

If your user hasn’t enrolled in MFA yet, when they first sign in, they’re prompted with challenges to enroll. Each challenge is seen as login attempts in your Access Server logs.

If the user waits 15 minutes, they can sign on again. They should no longer be locked out.

Error with bind user

Incorrect credentials for bind

An error message related to LDAP authentication issues and the bind user is AcceptSecurityContext error: Invalid credentials, facility=admin_bind. This indicates that the credentials for the bind user to the LDAP server are incorrect. The following tips may help:

  • If connecting to Active Directory, create a separate user in the domain and use this user to bind.
  • Try resetting the password for the bind user - the issue might be that the password for the bind user expired and requires resetting. You might want to configure this account not to expire its password.
  • Use a format like username@domain.tld as the username in the Access Server’s bind username field. Ensure you use your server’s domain information for the “domain.tld” part.
  • Check for issues with the SSL certificate. We’ve seen cases where the SSL client certificate used for communicating between Access Server and the LDAP server has expired.

Unsuccessful bind

Another possible error message related to LDAP authentication issues and the bind is To perform this operation, a successful bind must be completed on the connection. These tips may help:

  • Check to see if you’re using an anonymous bind and, if so, whether your LDAP server allows an anonymous bind. You may need to create a user for the bind and give the user read access to the LDAP objects you search for user authentication.
  • You could enable anonymous LDAP binding on the LDAP server. Refer to your LDAP server documentation for this. We don't recommend anonymous binding, as the directory becomes visible to anyone without credentials. We recommend using a bind user, as it is more secure.

Permissions for specific attributes in Active Directory

A bind user for connecting with Active Directory via LDAP doesn't necessarily need admin rights but does need permission to browse the directory. The bind user also needs permissions for specific attributes for certain use cases. These use cases may include adding the optional LDAP filter or using a post_auth script for mapping groups from Active Directory to Access Server. If you need to look for specific attributes such as "memberof", add the Read MemberOf permission:

  1. Open Active Directory Users and Computers.
  2. Right-click on domain and click Properties.
  3. On the Security tab, click Advanced and click Add.
  4. Enter the bind user’s name and click the Properties tab.
  5. Select User objects in the Apply onto drop-down.
  6. Click the Read MemberOf checkbox, then click OK.

Test OpenSSL connection

You can test the SSL connection from your Access Server to the LDAP server of your directory service with the OpenSSL command-line tool. As a root user, run this command on your Access Server (replacing the LDAP URL with the specific URL for your directory service):

openssl s_client -connect ldap.google.com:636

If the connection is successful, the last line should read “Verify return code: 0 (ok)”. If you see anything else, investigate your network settings and firewall settings on devices that stand between your Access Server instance and the LDAP server for your directory service. A failure to verify the certificate could mean a local problem where your root CA certificate bundle is outdated, or it could indicate that the certificate offered by the server is not valid for ldap.google.com, for example. The latter usually means that a firewall or antivirus solution intercepts your connection and presents its certificate instead.

Use ldapsearch for troubleshooting

You can test using the ldapsearch, which is an LDAP utility.

  1. Install the LDAP utilities:
    apt install ldap-tools
  2. Run this command (you’ll need to adjust to match your specific configuration settings—our example uses a Google LDAP setup):
    LDAPTLS_CIPHER_SUITE='NORMAL:!VERS-TLS1.3' LDAPTLS_CACERT=/usr/local/openvpn_as/etc/cacert.pem LDAPTLS_CERT=/etc/ssl/certs/gldap.crt LDAPTLS_KEY=/etc/ssl/private/gldap.key ldapsearch -H ldaps://ldap.google.com:636 -b ‘dc=domaingoes,dc=here’ '(mail=*)’
  3. Where it says “dc=domaingoes,dc=here” you should put your baseDN. The last part, “mail=*” should return all user object results—but you may specify a primary email address instead.
    In the cipher suite setting within the command, we specify to disallow TLS 1.3 in the test. If you use TLS 1.3, it is necessary to use SNI, and ldapsearch does not have SNI support at the time of writing. Lowering it to TLS 1.2 bypasses this issue in the test. The parameter LDAPTLS_CERT is for an LDAP client certificate if you have a setup with this for your directory service (such as using Google LDAP). LDAPTLS_KEY points to a private key used with a Google LDAP setup. These are available from your Google admin console, where your LDAP connector is set up.
  4. You should get back a search result with something like this at the end:
    # search result
    search: 3
    result: 0

If you do not return search results, you can send us a support ticket for help.

Active Directory example with ldapsearch

As another example, we provide the steps below to use ldapsearch for a configuration of Access Server authenticating via Active Directory and verifying group membership. Our example uses the following configuration:

  • Bind user: ovpnuser
  • Primary server:
  • Base DN: CN=Users,DC=domain,DC=com
  • Username: qa
  • Optional LDAP filter: memberOf=CN=groupa,CN=Users,DC=domain,DC=com
  1. Run the following command where ovpnuser is the bind user from auth.ldap.0.bind_dn:
    ldapsearch -d 11 -x -D ovpnuser -h -b "CN=Users,DC=domain,DC=com" "(&(sAMAccountName=qa)(memberOf=CN=groups,CN=Users,DC=domain,DC=com))" -W
  2. This example message displays upon successful server connection:
    root@as-test-server:/usr/local/openvpn_as/scripts# ldapsearch -x -D ovpnuser -h -b "CN=Users,DC=domain,DC=com" "(&(sAMAccountName=qa)(memberOf=CN=groupa,CN=Users,DC=domain,DC=com))" -W
  3. Enter the LDAP password, and a message similar to the following displays after successful authentication:
# extended LDIF
# LDAPv3
# base <CN=Users,DC=domain,DC=com> with scope subtree
# filter: (&(sAMAccountName=qa)(memberOf=CN=groupa,CN=Users,DC=domain,DC=com))
# requesting: ALL
# qa, Users, domain.com
dn: CN=qa,CN=Users,DC=domain,DC=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
cn: qa
givenName: qa
distinguishedName: CN=qa,CN=Users,DC=domain,DC=com
instanceType: 4
whenCreated: 20200910151712.0Z
whenChanged: 20220113143206.0Z
displayName: qa
uSNCreated: 12813
memberOf: CN=groupa,CN=Users,DC=domain,DC=com
memberOf: CN=Guests,CN=Builtin,DC=domain,DC=com
uSNChanged: 59527
name: qa
objectGUID:: /+Yw3iN9i0iSSoJ3DGAlPw==
userAccountControl: 66048
badPwdCount: 0
codePage: 0
countryCode: 0
badPasswordTime: 132798900954136782
lastLogoff: 0
lastLogon: 132798901083824436
pwdLastSet: 132735959943991164
primaryGroupID: 513
accountExpires: 9223372036854775807
logonCount: 0
sAMAccountName: qa
sAMAccountType: 805306368
userPrincipalName: qa@domain.com
lockoutTime: 0
objectCategory: CN=Person,CN=Sc

Using authcli tool for troubleshooting

You can use authcli, the authentication testing tool available in the command line, to run tests and get useful debugging information. To run authcli, ensure you are in the /usr/local/openvpn_as/scripts/ directory and run the commands as a root user.

Verify user authentication:

./authcli --user <USER_NAME> --pass <PASSWORD>

Sample output of a successful authentication:

API METHOD: authenticate
  status : SUCCEED
  user : lauren
  reason : LDAP auth succeeded on ldaps://ldap.jumpcloud.com
  proplist : {'prop_autogenerate': 'true', 'conn_group': 'JumpCloud LDAP', 'prop_force_lzo': 'false', 'prop_superuser': 'false', 'prop_autologin': 'false', 'prop_deny': 'false', 'user_auth_type': 'ldap', 'type': 'user_connect', 'pvt_password_digest': '$P$87plT0hvFSptcZ8S3GOc7Q==$MvUV55h1t6deYIrgGpAMCY2f/dIOmfC+K53P2fMH9As='}
  session_id : AS_+QN3bybHYCnWr12e2iM3QA==
  expire : 1645832973

If you use multi-factor authentication (MFA), verify authentication with this command:

./authcli --user <USER_NAME> --pass <PASSWORD> --sr=<MFA_CODE_HERE>

If you get the error user not found for a setup with JumpCloud, ensure that you’ve enabled your user in the JumpCloud LDAP directory. Refer to Using Access Server with JumpCloud for steps to assign the user to the directory.

Troubleshooting certificate issues

Issue from invalid certificates or configurations

It’s a known issue that Access Server can freeze if you input invalid certificates or incorrect connection settings for the secure LDAP connection, such as Google LDAP. If this occurs, restart the Access Server service. Then, attempt configuration again. 

If a connection is made to a port on the LDAP server that uses plain text authentication but also supports the start_tls command to encrypt the authentication, then you should configure this:

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

Certificate can’t properly validate for Active Directory

An error can occur with an Active Directory configuration when the LDAP certificate doesn’t match the hostname or IP address. For example, if the certificate is issued for the hostname of the domain controller (e.g.: dc1.company.local), but you use the IP address of the LDAP server as the primary server on the LDAP page in the Admin Web UI, the certificate can’t validate properly.

You can resolve this in one of two ways:

  • Replace the IP address with the hostname of the domain controller: sign in to the Admin Web UI, click Authentication > LDAP, replace the primary server, then click Save Settings and Update Running Server.
  • Or, disable certificate verification with the following command:
    ./sacli --key “auth.ldap.0.ssl_verify” --value “never” ConfigPut

Certificate verify failed for Google LDAP

The following error can occur with the LDAP server has an untrusted or self-signed certificate in the certificate chain:

Cannot connect to LDAP server: {'info': 'error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed (self signed certificate in certificate chain)

Access Server version 2.6.1 and later check to see if this certificate is valid by default. This ensures that the LDAP server you’re talking to is what you should be talking to and helps ward against a Man-in-the-Middle attack. The auth.ldap.0.ssl_verify key controls this behavior and can have the following values:

  • never — no peer certificate required.
  • allow — if a peer certificate is provided, it must pass validation; if no peer certificate is provided, the session will continue.
  • demand — a valid peer certificate is required, and the session aborts if it’s not.
  • internal — a valid peer certificate is required and must validate successfully against an internal Mozilla root CA bundle.

You can upload your own CA certificate bundle to verify an LDAP server certificate with manually:

./sacli --key "auth.ldap.0.ssl_verify" --value "demand" ConfigPut
./sacli --key "auth.ldap.0.ssl_ca_cert" --value <PATH_TO_FILENAME> ConfigPut
./sacli start

The <PATH_TO_FILENAME> must be a full path like “/usr/local/openvpn_as/ca_cert.pem”.

Or you can point to a specific directory to scan for a CA certificate for validating the LDAP server certificate with:

./sacli --key "auth.ldap.0.ssl_verify" --value "never" ConfigPut
./sacli start