Troubleshooting Authentication Problems

Debugging / troubleshooting authentication problems

Use the authcli tool

To validate your authentication configuration for Access Server, we recommend using the authcli command-line utility.

The authcli tool runs tests and provides useful debugging information in the process. You can print authentication results to your screen, see user-specific properties applied when authentication succeeds, and verify if expected properties get picked up.

To run authcli, ensure you are in the /usr/local/openvpn_as/scripts/ directory and run the commands as a root user.

Note: Mismatched usernames are one of the most common problems with authentication, where the username in the User Permissions table for Access Server doesn’t precisely match the username in the external authentication system.

Choose from the below commands for debugging or testing with authcli.

Verify authentication for a user:

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

Sample output of a successful local authentication attempt:

API METHOD: authenticate
AUTH_RETURN
 status : SUCCEED
 session_id : AaJkamAuZgjXwsjk+N96eA==
 reason : local auth succeeded
 expire : 1505404548
 user : test
 proplist : {'pvt_password_digest': '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08', 'type': 'user_connect', 'prop_autogenerate': 'true'}

Verify authentication for a user with multi-factor authentication (MFA) enabled:

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

Case-sensitive matters for usernames

Most authentication systems are case-sensitive. Ensure the username case matches between Access Server and the external authentication system. After a successful match, Access Server can apply user-specific properties—auto-login privileges, static IP address, and so on.

For PAM authentication, the username is case-sensitive. Authentication fails if you enter "Gary" to sign in but the actual username is "gary".

Some LDAP servers may not be case sensitive for usernames, such as Active Directory. However, if you sign in to Access Server with "Gary", and the LDAP server returns "gary" as the match, Access Server looks up user-specific properties for "gary". Ensure you match cases for your usernames.

LDAP authentication debugging tips

The most common problems for LDAP authentication relate to the base DN search query. Ensure you enter that carefully, especially where your search query is very specific. When you encounter an LDAP issue related to your search query, you receive an error message such as “user not found that meets specified criteria.” The user isn’t found in that location in the LDAP directory. Try these steps to address this issue:

Broaden your search query to include the entire directory: DC=example,DC=com (adjust to your DC values).
If that works, refine your search query how you like: search in a specific location, or search by a specific group.

When debugging problems with authenticating against an LDAP server, generally, the LDAP debug options are not necessary. Still, you need to use some trial and error and the authcli tool.

For more information on the command-line tools, see the page here.

Reset default openvpn account administrative access

Note: If you are not currently using the latest version of Access Server we recommend reading the notes on older versions.

The administrative account, which is by default called openvpn, may be either a bootstrap account in the operating system or an administrative account within the internal local authentication system of Access Server itself. We recommend a local account which is the default since Access Server version 2.10.

These are common administrative user login problems:

You have lost the username and/or password.
The account is tied to a defunct external authentication system.
The account has the deny login flag set on it.
There is an MFA requirement, and you lost the secret key.
The account is (temporarily) locked out after multiple failed logins.

You can execute the following commands as root user on the command line of the Access Server to create or reset the local administrator account with the username openvpn. It accounts for all of the above cases and should provide you with a local openvpn administrative account that you can use to sign in to the Admin Web UI.

Create/reset openvpn administrative local account with specified password:

cd /usr/local/openvpn_as/scripts
./sacli --user "openvpn" --key "prop_superuser" --value "true" UserPropPut
./sacli --user "openvpn" --key "user_auth_type" --value "local" UserPropPut
./sacli --user "openvpn" --new_pass=<PASSWORD> SetLocalPassword
./sacli start

Disable the deny login flag and reset MFA if required for the account:

./sacli --user "openvpn" --key "prop_deny" --value "false" UserPropPut
./sacli --user "openvpn" --key "prop_google_auth" UserPropDel
./sacli --user "openvpn" --lock 0 GoogleAuthRegen
./sacli start

Reset the password lockout policy just in case it was triggered:

./sacli --key "vpn.server.lockout_policy.reset_time" --value "1" ConfigPut
./sacli start
sleep 2
./sacli --key "vpn.server.lockout_policy.reset_time" ConfigDel
./sacli start

Try signing in to the Admin Web UI again with openvpn and the password you specified. If you still cannot sign in, check the notes on older versions. You can contact us on our support ticket system for further assistance.

Notes on older versions

Access Server 2.9 and older

On Access Server 2.9 and older, the default openvpn administrative account is of the bootstrap account type specified in the as.conf file and exists in the operating system as a PAM authenticated user. This unique account type is automatically granted administrative login rights in Access Server bypasses the post_auth script, bypasses MFA requirements, bypasses the password lockout policy, and always authenticates via PAM to the operating system.

We recommend that you upgrade your Access Server and move away from this type of bootstrap account. However, if you don’t want to upgrade, you can edit the as.conf file to specify a bootstrap user and set the password in the operating system. You can then use that account to sign in to the Admin Web UI.

To use a bootstrap account, the as.conf file must contain a line like this:

boot_pam_users.0=openvpn

Reset the password on that account:

passwd openvpn

Restart the Access Server service for the changes to take effect:

service openvpnas restart

For installations upgraded from version 2.9 and older

After upgrading an older Access Server to version 2.10 or newer the old bootstrap account behavior from the older Access Server version remains. Bootstrap accounts defined in the as.conf file will be reset to authenticate via PAM using the user_auth_type user property each time Access Server starts up so the behavior of these accounts to login via PAM remains.

If you’ve upgraded from an older version to Access Server 2.10 or newer and you still have a bootstrap user account, we recommend that you remove this bootstrap account and then use the reset default openvpn account administrative access instructions to create a local administrative account. To remove the bootstrap account you can follow the steps below.

Comment out the bootstrap openvpn account from the as.conf file:

# boot_pam_users.0=openvpn

Remove the bootstrap account from your operating system:

deluser openvpn

Restart the Access Server service for the changes to take effect:

service openvpnas restart

If you’re using other bootstrap accounts, you can handle them in a similar way.

Next, go through the reset default account administrative access instructions to ensure you have a local administrative openvpn account that you can use to sign in to the Admin Web UI.

Common authentication errors and suggested solutions

Here are some common error messages and causes related to authentication:

password verification failed or authentication failed

The password and/or username provided aren’t correct.

no stored password digest found in authcred attributes

This error occurs with local authentication. The user account exists but doesn’t have a password set.

To set the password in the Admin Web UI:

Sign in to the Admin Web UI.
Click User Management > User Permissions.
Click More Settings for the user.
Enter a password in the Password field.
Click Save Settings and Update Running Server.

To set the password from the command line:

Use the sacli SetLocalPassword command. Refer to the user and group management page for specifics.

Another possibility occurs for a user with local authentication with a user-locked profile but the user enters a different username to sign in. For example, suppose you download a user-locked profile for "John" but enter "Dave" as the username. In that case Access Server tries to verify the credentials for the incorrect "Dave" user and if that doesn't exist or doesn't have a password set then the local authentication will fail with this message. Fix this by using the correct username and password for the user-locked profile.

DENY: user in deny list, or, user account suspended

This error message occurs in one of two situations:

The deny access box is checked for the user in the User Permissions table.
The require user permissions record for VPN access box is checked. The user authenticates with an external system: PAM, LDAP, or RADIUS, and the user doesn’t exist in the User Permissions table or doesn’t match the username in the external system.

To resolve the issue with the deny access box:

Sign in to the Admin Web UI.
Click User Management > User Permissions.
Click Deny Access to uncheck the box for the username.
Click Save Settings and Update Running Server.

To resolve the issue with the require user permissions record for VPN access box:

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.
Uncheck the require user permissions record for VPN access in the User Permissions table.

username-only match fail, client username='dave', DB username='john'

This error message displays when a user tries to sign in with credentials for an existing user "dave" with a user-locked profile for the existing user "john".

To resolve, ensure to use the correct username with a user-locked profile. You can’t mix and match profiles and credentials.

Alternatively, you can replace the user-locked profile with a server-locked connection profile if you need a connection profile that allows any valid Access Server user to connect.

user not found (that meets specified requirements)

This error displays with LDAP authentication configured when the username isn’t found with the specified LDAP query.

Simplify the query to just the base DN, "DC=example,DC=com" to broaden the search. The issue often exists because the user isn’t in the location searched by the LDAP query.

If a directory-wide search still doesn’t return results, it may be due to an incorrect LDAP attribute. Try searching for “sAMAccountName” or “uid”. Refer to the documentation for your LDAP server to determine the correct attribute. The auth.ldap.0.uname_attr sets the attribute for the search.

If changing the LDAP attribute still doesn’t return results, it may be that your LDAP server is case sensitive with containers and objects and that you need to use lowercase names instead (cn=blabla instead of CN=blabla). Refer to the documentation for your LDAP server to find the correct settings.

One significant issue can occur when defining additional query parameters to allow only users from a specific group in the LDAP directory to sign in. For example, the additional query memberOf=CN=VPN Users fails, but the full query should work: memberOf=CN=VPN Users,OU=Security Groups,DC=company,DC=com. Ensure you use the full query.

AcceptSecurityContext error: Invalid credentials, facility=admin_bind

This error may appear in the openvpnas.log log file and indicates that the LDAP server’s credentials entered for the bind are incorrect or don’t allow access to the LDAP directory.

If you're trying to connect to an Active Directory server, it may help to create a separate user in the domain for the bind user. We recommend using a format like username@domain.tld as the username in the Access Server's bind username field.

We’ve also seen the same problem reported with an expired SSL certificate for securing communication between Access Server and the LDAP server.

In order to perform this operation a successful bind must be completed on the connection

This error occurs with LDAP authentication using an anonymous bind, not allowed by the LDAP server. Refer to the documentation for your LDAP server for whether it’s allowed.

To resolve, create a bind user on the LDAP server and give it read access to the LDAP objects you want to search for user authentication. Alternatively, you can enable anonymous LDAP binding on the LDAP server, but this is not as secure as using a special limited bind user account.

user temporarily locked out due to multiple authentication failures

The error message is related to the password lockout policy, implemented automatically by Access Server. The lockout policy temporarily blocks a user from signing in when the password was incorrectly provided a number of times within a specified time. You can adjust the lockout policy to meet your specific needs.

Refer to Authentication failure lockout policy for more details.

Google Authenticator must be set up for VPN access

This error message relates to using Google Authenticator with Access Server. When you enable Google Authenticator to enforce MFA for users, and a user hasn’t completed enrollment on the Client UI, they can’t establish a VPN tunnel connection.

To resolve this, instruct your user to sign in to the Client UI and complete the enrollment. They need to scan the QR code or enter the enrollment code into the Google Authenticator app (or a compatible TOTP app), to save the shared secret and generate the required six-digit one-time password.

Refer to Google Authenticator multi-factor authentication for more details.

Google Authenticator code must be a number

This error message relates to incorrectly entering the six-digit code for MFA with Google Authenticator. When you enable Google Authenticator for Access Server, a user signs in with their username and password and must provide the six-digit code from Google Authenticator (or a compatible TOTP app). Google Authenticator generates a new code every 30 seconds.

To resolve: use the Google Authenticator application and enter the six-digit code into the Google Authenticator field when asked.

Google Authenticator code is incorrect

This error message occurs when the six-digit code for Google Authenticator isn’t correct. This can occur due to entering the wrong code or if the date/time or timezone settings are incorrect on either the server or the client device.

Google Authenticator uses the current date and time and adjusts automatically for time zones. This requires that the server and the device with the Google Authenticator app both have the correct timezone set and the correct time and date set. Time and date, plus a shared secret known by Access Server and Google Authenticator are used to create the unique six-digit codes: shared key + time and date = code. If the date/time or timezone is incorrect on either the server or the client device, the six-digit code won’t match.

The six-digit code is valid for 30 seconds. Access Server accepts the current code as well as the previous and following codes.

If the user entered the correct code and the time and date are set correctly, you can reset the Google Authenticator key for this user and ask them to enroll again.

In most cases, the issue is a drifting system clock on the server, especially on virtual cloud-based hardware. To resolve, install an NTP (Network Time Protocol) client program, which can automatically pull the correct time from the internet. A time difference of more than 30 seconds can already be a problem. Mobile devices usually do time synchronization by themselves. In the past, we have seen a bug with a specific version of iOS which skewed the time by one minute, which upset Google Authenticator. Updating iOS to a newer version resolves the issue.

Auth module max parallel at or above limit

2023-04-13T14:44:49+0000 [stdout#info] Warning: OpenVPN daemon job Queue size (~10) at or above limit (auth.module.max_parallel=8).
2023-04-13T14:44:53+0000 [stdout#info] Warning: OpenVPN daemon job Queue size (~11) at or above limit (auth.module.max_parallel=8).

This error means that your Access Server installation faces high throughput of authentication requests and the default value (8 parallel threads) is not enough to handle all of them. In this case, we recommend increasing the number of parallel authentication threads. Recommended value for this parameter should be equal or more than the prognosed number of VPN clients that try to connect to Access Server at the moment.

It is important to increase the max database connection QueuePool size as well because more authentication threads will cause more simultaneous connections to the database.

Refer to Set maximum number of authentication and database connection QueuePool size for details.

VPN Auth Failed: 'QueuePool limit of size 5 overflow 10 reached

2022-12-13T11:06:24+0000 [stdout#info] VPN Auth Failed: 'QueuePool limit of size 5 overflow 10 reached, connection timed out, timeout 30 (Background on this error at: http://sqlalche.me/e/13/3o7r): ...

This error occurs when Access Server uses all available threads for connection to the database and needs more to handle current activity. The most common reason for this situation is increasing the auth.module.max_parallel parameter but leaving mysql.max_overflow with the default value.