---
title: LDAP Troubleshooting Guide for Access Server
canonical: https://openvpn.net/as-docs/ldap-troubleshooting/
product: Access Server Docs
description: Troubleshoot issues with Access Server and LDAP authentication.
---

# LDAP Troubleshooting Guide for Access Server

Access Server can look up users in directory services using the Lightweight Directory Access Protocol ([LDAP](https://openvpn.net/access-server/ldap/)). You can [configure LDAP](https://openvpn.net/as-docs/ldap.md) authentication with the [Admin Web UI](https://openvpn.net/as-docs/admin-web-ui-user-manual.md) or the [command-line interface](https://openvpn.net/as-docs/tutorials/tutorial--ldap-command-line.md).

This topic provides troubleshooting tips and help for various error messages and use cases customers have encountered. Feel free to reach out to [support](https://support.openvpn.com) for help as well.

## Enable verbose debugging

You can enable verbose authentication debugging to help troubleshoot connection issues with your directory service.

1. Sign in to the terminal or connect via SSH to your Access Server.
2. Execute the following commands:

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

   - Access Server will now log verbose authentication messages to the standard Access Server log file at `/var/log/openvpnas.log`.
3. You can send the file to [our support team](https://support.openvpn.com/); they will assist you further.

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

1. Open the **as.conf** for editing:

   ```
   nano /usr/local/openvpn_as/etc/as.conf
   ```
2. Delete or comment out the line `DEBUG_AUTH=true`.
3. Save and exit the file.
4. Restart the Access Server service:

   ```
   sudo systemctl restart openvpnas
   ```
5. Verbose authentication logging no longer occurs.

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

1. 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 being found in the search based on expected attributes. Simply put, the user may not be where you told it to look. Widening the search can help determine if this is the case.
2. 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.
3. 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.
4. 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.

## 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 required to enroll in MFA through their OpenVPN Client UI. This is tied to Access Server's lockout policy. Refer to [Authentication failure lockout policy](https://openvpn.net/faq/what-is-the-lockout-policy-on-access-server/) 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.

## Errors 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:

1. If connecting to Active Directory, create a separate user in the domain and use this user to bind.
2. 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 to not expire its password.
3. 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.
4. 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:

1. 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.
2. 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 the **Read MemberOf** attribute configured correctly.

Properly configuring the AD bind user is important for configuring the optional LDAP filter or using a post-auth script for mapping groups from Active Directory to Access Server.

Refer to this tutorial to create an AD bind user: [Create and configure a bind user](https://openvpn.net/as-docs/tutorials/tutorial--active-directory-ldap/#step-1--create-and-configure-a-bind-user-112238).

## "The server requires binds to turn on integrity checking..."

When configuring Access Server to authenticate against Active Directory (AD) using LDAP in Windows Server AD 2025, you might find the LDAP authentication module not starting or failing due to an error and the following message on the Access Server logs:

```
2025-03-24T18:48:18+0000 [stdout#info] AUTH_LDAP: is_service_alive caught exception LDAPStrongerAuthRequiredResult - 8 - strongerAuthRequired - None - 00002028: LdapErr: DSID-0C090347, comment: The server requires binds to turn on integrity checking if SSL\TLS are not already active on the connection, data 0, v65f4 - bindResponse - None
```

For resolution, refer to our support article: [Access Server: Error — "The server requires binds to turn on integrity checking if SSL\\TLS are not already active on the connection"](https://support.openvpn.com/hc/en-us/articles/35287994059035-Access-Server-Error-The-server-requires-binds-to-turn-on-integrity-checking-if-SSL-TLS-are-not-already-active-on-the-connection).

## 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.

1. Connect to your console and get root privileges.
2. Run this command:

   ```
   openssl s_client -connect ldap.google.com:636
   ```

   Replace the LDAP URL with the specific URL for your directory service.
3. If the connection is successful, the last line should read, `Verify return code: 0 (ok)`. If you see anything else, refer to the tips below.

If the connection doesn't succeed, investigate these things:

1. Check network and firewall settings on devices that stand between your Access Server instance and the LDAP server for your directory service.
2. 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 isn't valid for the domain.
3. A firewall or antivirus solution may intercept the connection and present its certificate instead.

## Use ldapsearch for troubleshooting

You can test using the **ldapsearch**, which is an LDAP utility. Use the information below for help with installing the utility and to find example commands to use for your own troubleshooting.

### Install ldapsearch

Install the LDAP utilities:

1. Sign in to your console and get root privileges.
2. Run the install command for your Linux OS:

   ```
   apt install ldap-tools ## For Ubuntu and Debian
   ```

   ```
   yum install openldap-clients ## For RHEL and Centos
   ```

   - You can now use the **ldapsearch** tool.

### Basic ldapsearch command

Below is the syntax of the **ldapsearch** command:

```
ldapsearch -x -D "Bind User" -b "Base DN" -H "Primary Server" -w
```

When you use the **ldapsearch** utilities, you enter your LDAP settings as the values. For our examples below, we use the following LDAP settings in our Access Server:

|  |  |
| --- | --- |
| **Bind user:** | ovpnuser |
| **Primary server:** | 203.0.113.30 |
| **Base DN:** | CN=Users,DC=domain,DC=com |
| **Username** | qa |
| **Optional LDAP filter:** | mbmerOf=CN=groupa,CN=Users,DC=domain,DC=com |

> **Note**
>
> In our documentation, we use example IPv4 addresses and subnets [reserved for documentation](https://en.wikipedia.org/wiki/Reserved_IP_addresses#IPv4), such as `192.0.2.0/24`, `198.51.100.0/24`, and `203.0.113.0/24`.
>
> Ensure you replace them with valid IPv4 addresses and subnets for your network(s).

### Example commands

Use the following example commands to input your specific LDAP settings for troubleshooting.

- Check all the LDAP users under the base DN:

  ```
  ldapsearch -x -D "ovpnuser" -b "CN=users,DC=domain,DC=com" -H ldap://203.0.113.30 -W
  ```

  - When prompted, enter your bind user password to return the results.
- Check if a specific LDAP user exists under the base DN:

  ```
  ldapsearch -x -D "ovpnuser" -b "CN=users,DC=domain,DC=com" -H ldap://203.0.113.30 "sAMAccountName=specific-user" -W
  ```

  - When prompted, enter your bind user password to return the results with user information.
- Check if a specific LDAP user is a member of one specific LDAP group ("memberOf=CN=groupa,CN=Users,DC=domain,DC=com"):

  ```
  ldapsearch -x -D "ovpnuser" -b "CN=users,DC=domain,DC=com" -H ldap://203.0.113.30 "(&(sAMAccountName=specific-user)(memberOf=CN=groupa,CN=Users,DC=domain,DC=com))" -W
  ```

  - When prompted, enter your bind user password to return the results with user information.

If you don't return search results, send us a [support ticket](https://support.openvpn.com/hc/en-us) for help.

### Active Directory example with ldapsearch

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

|  |  |
| --- | --- |
| **Bind user:** | ovpnuser |
| **Primary server:** | 192.0.2.30 |
| **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 ldap://192.0.2.30:389 -b "CN=Users,DC=domain,DC=com" "(&(sAMAccountName=qa)(memberOf=CN=groups,CN=Users,DC=domain,DC=com))" -W
   ```

   - This example message displays upon successful server connection:

     ```
     root@as-test-server:/usr/local/openvpn_as/scripts# ldapsearch -x -D ovpnuser -H ldap://192.0.2.30:389 -b "CN=Users,DC=domain,DC=com" "(&(sAMAccountName=qa)(memberOf=CN=groupa,CN=Users,DC=domain,DC=com))" -W
     ```
2. Enter the LDAP password.
   - After successful authentication, a message similar to the following displays:

     ```
     # 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
     userParameters:: bTogICAgICAgICAgICAgICAgICAgIGQJICAgICAgICAgICAgICAgICAgICAgICAg
     objectSid:: AQUAAAAAAAUVAAAA8pokOI993RR3pmMhWgQAAA==
     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
    AUTH_RETURN
      status : SUCCEED
      user : ovpnuser
      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 Access Server built-in multi-factor authentication (MFA), verify authentication with this command:

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

> **Caution**
>
> Using `--sr` in the above commands works only with Access Server's built-in MFA. It doesn't work if you have MFA through another provider.

> **Tip**
>
> 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 the [JumpCloud with Access Server LDAP tutorial](https://openvpn.net/as-docs/tutorials/tutorial--jumpcloud-ldap.md) for steps to assign the user to the directory.

## Troubleshoot 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 that matches the certificate common name (CN):
  1. Sign in to the Admin Web UI.
  2. Click **Authentication \> LDAP**.
  3. Replace the primary server.
  4. Select **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 provide your own CA certificates to verify the LDAP server certificate.

**Specify your own CA bundle file and demand verification:**

1. Connect to your console and get root privileges.
2. Switch to the scripts directory:

   ```
   cd /usr/local/openvpn_as/scripts/
   ```
3. Run these commands:

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

   The \<PATH\_TO\_FILENAME\> must be a full path like “/usr/local/openvpn\_as/ca\_cert.pem”. Ensure the certificate is in PEM format.

## LDAP Explorer with Access Server

LDAP Explorer is an API method in the server agent that allows LDAP searches against the LDAP database defined in Access Server. LDAP Explorer should function when you've configured LDAP authentication with Access Server.

### Using LDAP Explorer

You can access the LDAP Explorer API method through the **sacli** command line tool.

> **Tip**
>
> Run **sacli** commands from the scripts directory: **/usr/local/openvpn\_as/scripts/**.

The following commands use `sacli [arguments] ldapexp` with one or more of the following arguments passed for your LDAP configuration:

|  |  |
| --- | --- |
| **--dn** | Your bind DN configuration — simple example: **dc=domain,dc=com**. |
| **--scope** | Set the LDAP search scope parameter to base, level, subtree, or subnode. This specifies the portion of your target to consider for the search. |
| **--key** | Include a key in your search and define the key with a value (below) — example: `--key 'uid' --value 'username'` or -`k 'uid' -v 'username'`. |
| **--value** | Define a value for an included key (above) in your search. |
| ***--ldap\_config*** | Search using an LDAP config file instead of the server — example query: `sacli --dn='cn=users, dc=domain, dc=com' --scope=subnode --ldap_config ldap.config -k sAMAccountName -v 'VPN Users' ldapexp` |

Using the above table, you can compose your LDAP Explorer commands. Here's an example that includes scope, key, and value:

```
./sacli --dn='ou=test test,dc=domain,dc=com' --scope 'subnode' -k 'objectClass' -v 'top' ldapexp
```

### LDAP Explorer configuration error message — "LDAP explorer can only be used without a configuration…"

You may encounter an error message due to a bug in some Access Server versions: "LDAP explorer can only be used without a configuration when LDAP is selected as the authentication method." This bug occurs because LDAP Explorer doesn't see that LDAP is turned on as the auth method.

We resolved the bug in Access Server 2.13.0. [Update to the latest Access Server version](https://openvpn.net/as-docs/upgrading.md) to resolve the issue.

## DENY: user in deny list, account suspended, or access denied

**Issue:** You encountered one of these error messages:

- **DENY: user in deny list**
- **user account suspended**
- **User access denied**

**Reason:** This error message occurs in one of two situations:

1. The **deny access** box is checked for the user in the **User Permissions** table.
2. The **Deny access to unlisted accounts by default** is set to **Yes**. The user authenticates with an external system (PAM, LDAP, RADIUS, or SAML) and doesn't exist in the **User Permissions** table or match the username in the external system.

### Resolution for deny access box

1. Sign in to the Admin Web UI.
2. Click **User Management \> User Permissions**.
3. Click **Deny Access** to uncheck the box for the username.
4. Select **Save Settings** and **Update Running Server**.

### Resolution for Deny access to unlisted accounts by default

You can resolve the issue by adding the user to Access Server's user permissions table or by allowing Access Server to add users automatically by setting **Deny access to unlisted accounts by default** to **No**.

Follow the steps below for your preferred option.

#### Add the user:

1. Sign in to the Admin Web UI.
2. Click **User Management \> User Permissions**.
3. Add the user to the **User Permissions** table if it doesn't exist.
   - Ensure the spelling and case match between Access Server and the external authentication server.
4. Select **Save Settings** and **Update Running Server**.

#### Allow Access Server to add users:

##### Via the Admin Web UI

1. Sign in to the Admin Web UI.
2. Click **Authentication \> Settings**.
3. Under **External User Registration**, set **Deny access to unlisted accounts by default** to **No**.
4. Select **Save Settings** and **Update Running Server**.

##### Via the command-line interface (CLI)

1. Connect to the console and get root privileges.
2. Switch to the scripts directory:

   ```
   cd /usr/local/openvpn_as/scripts/
   ```
3. Run the blow command to change the value to "false" (Default) or "true":

   ```
   ./sacli --user "__DEFAULT__" --key "def_deny" --value "false" UserPropPut
   ./sacli start
   ```

---

Prev: [Common Auth Errors](https://openvpn.net/as-docs/auth-errors---fixes.md)
Next: [SAML](https://openvpn.net/as-docs/saml-troubleshooting.md)
Index: https://openvpn.net/as-docs/llms.txt