Troubleshooting authentication related problems

Debugging / troubleshooting authentication problems

There is an authentication testing tool available in the command line called authcli. Using this you can quickly run tests and get some useful debugging information in the process. For example any authentication results on the command line are reported to your screen and if the authentication is successful you can see what user-specific properties are applied on this user, if any. This way you can verify for example if an expected property is actually being picked up. If it isn't then the most common problem here is that the user name that you are entering does not match what is known in the Access Server. This problem can occur if the user name known in an external authentication system doesn't match with what's configured in the Access Server "User Permissions" table for a given user name. All command line tools that come with Access Server are assumed to be run as root user in the /usr/local/openvpn_as/scripts/ folder. For more information on the command line tools see the page here.

To use authcli on the command line:

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

Sample output of a successful local authentication attempt:

API METHOD: authenticate
 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'}

When debugging problems for a user in which you need to enforce multi-factor authentication (MFA), you can do so by entering:

./authcli --user <USER_NAME> --pass <PASSWORD> --sr=<MFA CODE HERE>

Most authentication systems are case-sensitive and should not have a problem with matching the user name that the user enters against the user name entry in the User Permissions table in the Access Server for applying user-specific properties like auto-login privileges, static IP address, etcetera. With PAM the user name is almost always case-sensitive, meaning that when you enter as user name "Gary" at the log in prompt, but the user name is actually "gary" it just won't accept the user name. So you are forced to consistently use the correct case everywhere, which avoids ambiguity. but LDAP on Active Directory for example does not have to be case sensitive with user names. What can happen then is that the user enters "andrew" at the log in prompt, but it is known in the LDAP directory as "Andrew", and this correct name is then sent back to the Access Server and used there for looking up user-specific properties for "Andrew", not "andrew". So you have to be sure to use the correct case in the user name.

When debugging problems with authenticating against an LDAP server generally the LDAP debug options are not necessary, but you just need to use some trial and error and the authcli tool. The most commonly encountered problems are related to the base DN search query. Especially in cases where your search query is very specific, you may have problems getting authentication to work initially. You will usually receive an error like "user not found that meets specified criteria". What that means is that the user was not found in that location in the LDAP directory. The user name could very well exist, but not in that place. It helps to broaden the query by looking only in DC=example,DC=com (adjust to your DC values) which searches the whole directory. If that works, then you can work on refining your search query to look in a specific location, or add an LDAP expression that must evaluate to try using the additional LDAP requirements in the Access Server configuration.

Reset default openvpn account administrative access

By default, the OpenVPN Access Server comes with a default openvpn user account that has full admin access to the Admin UI and has special user privileges that let it bypass the requirement for Google Authenticator, and does not adhere to the password lockout policy, and is bootstrapped or tied to the PAM authentication system so that it can always log on. We designed it this way so that if for example you are setting up LDAP authentication, and you make a mistake, you can still log on to the Admin UI and make corrections. As per our security recommendations we recommend that administrators disable this account after initial setup, and to make your own administrative users instead, that do adhere to Google Authenticator and password policy lockouts.

Of course, there may come a time when you absolutely need to get back in, and you may have forgotten your administrative username or password. The steps below restore the openvpn administrative user account, set a new password on it, unblock the account in case it was blocked, disable Google Authenticator requirement for this user, and make it an admin user for access to the Admin UI again. In other words, with the steps below, you should definitely be able to login to the Admin UI again. Afterwards when you're done with your administrative tasks, we recommend you secure the openvpn administrative user account again. Start by opening a console session or an SSH session to your OpenVPN Access Server, and obtain root privileges. If you have lost root privileges, see online for instructions on resetting your operating system's root password, and then come back here to continue the reset procedure for the openvpn administrative user account.

Ensure that the user account openvpn exists:

adduser openvpn

If the user doesn't exist you will have to provide the password, twice, the rest you can leave empty:

Adding user `openvpn' ...
Adding new group `openvpn' (1002) ...
Adding new user `openvpn' (1002) with group `openvpn' ...
Creating home directory `/home/openvpn' ...
Copying files from `/etc/skel' ...
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
Changing the user information for openvpn
Enter the new value, or press ENTER for the default
 Full Name []:
 Room Number []:
 Work Phone []:
 Home Phone []:
 Other []:
Is the information correct? [Y/n]

But if you see this result, then this user exists already, and you can move on to the next steps:

adduser: The user `openvpn' already exists.

If the user already exists, and you need to set a new password for it, do this:

passwd openvpn

If in the past you locked the account you need to unlock it:

passwd -u openvpn

Now that we know for certain that the user account openvpn exists and has a password set on it that we know, you can now try to login at the Admin UI with the username openvpn and the password you have just reset. If that didn't work, the next step is going into the configuration file as.conf and making sure the bootstrap user is set to openvpn as well.

Open the text file as.conf in the nano text editor:

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

Look up the boot_pam_users.0 line and make sure the username is openvpn here. If it's not, change it so it looks like this:


Press ctrl+x, press y, and then press enter, to save and exit the file.
Restart the OpenVPN Access Server service for the changes to take effect:

service openvpnas restart

If the bootstrap user line wasn't set right and you have corrected it now, then it is worth a try to log in with the username openvpn and the password you have set on that account. If that still didn't work, it is possible that the user account has not been granted admin access in the user properties database, or that the user is blocked from logging in, or that it requires a Google Authenticator code. In the case of a Google Authenticator requirement, that shouldn't be a problem, it should accept any code for the openvpn user because it is a special bootstrap user. But Google Authenticator requirement can also be disabled. With the steps below we can take care of all these 3 items in one go:

Unblock openvpn user, make it an admin, and disable Google Authenticator requirement for it:

cd /usr/local/openvpn_as/scripts/
./sacli --user "openvpn" --key "prop_deny" --value "false" UserPropPut
./sacli --user "openvpn" --key "prop_superuser" --value "true" UserPropPut
./sacli --user "openvpn" --key "prop_google_auth" --value "false" UserPropPut
./sacli start

Try logging in at the Admin UI now. On all the systems we've ever encountered so far where the administrator was locked out, some or all of these instructions together, were successful in gaining administrative access again. If it still fails, contact us on our support ticket system and explain your situation and what you have tried so far, and we'll try to work with you to figure out how to restore access.

Common authentication errors and suggested solutions

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

password verification failed or authentication failed
Speaks for itself of course; the password and/or user name that were provided are not correct.

no stored password digest found in authcred attributes
You're using the local authentication method, and the user account you are trying to log on with does exist, but there is no password set for this user yet. Use the sacli SetLocalPassword function to do this. More information on how to use this function can be found on the user and group management page.

One other possibility exists here as well, if you're using the local authentication mode. If you are specifically using a user-locked profile for connecting to the Access Server, but you are using another user name than the one this user-locked profile is locked to and meant for, then you can also see this problem. For example if you download the user-locked profile for the user called "johan" but instead enter as user name "andrew", then the Access Server assumes that because you have a valid client certificate that the user name you are providing must also exist and tries to authenticate with it. This fails of course and in local authentication mode this error can then be produced. The solution here is to use the correct user name and password with the correct user-locked profile. You cannot mix and match profiles and credentials.

DENY: user in deny list, or, user account suspended
There are a few possible reasons for this. One of them is that in the User Permissions table, the checkbox deny access has been checked on this user. In that case the solution is simply to uncheck that box and save settings, to restore this user's access to the server. Another possible option is that you are using an external authentication system like PAM, LDAP, or RADIUS, and that in the User Permissions page all the way at the bottom, you have checked the restriction require user permissions record for VPN access, but this user is not correctly spelled or not at all present in the User Permissions table. This restriction is designed so that only those user names that you have created and have present in the User Permissions table in the Access Server can log on, even if the user account exists and is valid in your external authentication system. To resolve this simply make sure the exactly correct spelling of the user name is present in the User Permissions table and doesn't have the deny access checkbox set on it, or, to simply disable the restriction by unchecking the require user permissions record for VPN access option in the User Permissions table.

username-only match fail, client username='andrew', DB username='johan'
This is what happens when you use credentials for an existing user called "andrew" on your Access Server with a user-locked profile locked to and meant for the user account "johan". These don't match. The solution here is to use the correct user name and password with the correct user-locked profile. You cannot mix and match profiles and credentials. If you are going to use the user-locked profile for the user account "johan" you must use the user name "johan" and his password to log on to the VPN server successfully.

If you are looking for a more universal type of connection profile that lets any valid user on the Access Server log on then what you are looking for is the server-locked connection profile which works only in combination with the OpenVPN Connect Client for Windows and Macintosh. All other clients must have a connection profile that is specific to the user account. If you download OpenVPN Connect Client from your Access Server's web interface with a user account that does not have the auto-login privilege, then this is the type of OpenVPN Connect Client + server-locked connection profile installation that you will get.

user not found (that meets specified requirements)
You're using the LDAP authentication method, and the user name you entered could not be found with the LDAP query you specified. Try simplifying the query to just the base DN with for example DC=example,DC=com (adjust to your situation) and nothing else, thereby broadening the search. Often the issue is caused by the user not being known in the place you're searching or the attributes are different than you expected, and the LDAP server then reports this message. If even a directory wide search yields no results then the LDAP attribute you are searching may be different in your directory server. Try "sAMAccountName" or "uid" or otherwise look up documentation of your LDAP server to find out which attribute to use. The auth.ldap.0.uname_attr controls which attribute to search for. Another possibility is that your LDAP server is case sensitive with containers and objects and that you need to use lowercase name instead (cn=blabla instead of CN=blabla). Again we refer to documentation for your LDAP server to find out which settings work on your server.

One notable issue people have been found running into is seeing this error message when trying to provide the additional query parameters, to allow only users from a specific group in the LDAP directory to log on. If for example the additional query memberOf=CN=VPN Users is specified, it may fail. But if you make it the full query, it should work in most cases: memberOf=CN=VPN Users,OU=Security Groups,DC=company,DC=com.

AcceptSecurityContext error: Invalid credentials, facility=admin_bind
The above error may appear in the openvpnas.log log file and indicates that the credentials entered for the bind to the LDAP server were incorrect or won'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 and using this to bind. Use a format like username@domain.tld as username in the Access Server's bind username field. We have also seen the same problem reported when an SSL certificate was used for communication between Access Server and the LDAP server, and the SSL certificate had expired.

In order to perform this operation a successful bind must be completed on the connection
You're using LDAP authentication while trying to bind (connect) anonymously to the LDAP service, while the LDAP service does not allow anonymous binding. The solution is to create a bind user on the LDAP server and giving 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 a solution as using a special limited bind user account for the purpose of binding to the LDAP server and then looking up user credentials for authentication purposes.

user temporarily locked out due to multiple authentication failures
Access Server implements an automatic lockout policy, which is described in the lockout policy section on the additional security options page. This automatically temporarily blocks a user account from log on attempts when the password was incorrectly provided a number of times within a specified time. The lockout policy can be adjusted to meet requirements.

Google Authenticator must be set up for VPN access
When you have enabled the requirement for users to use Google Authenticator multi-factor authentication, but this user has not yet completed the Google Authenticator enrollment process on the client web service of the Access Server, then the Access Server will not allow the user to establish a VPN tunnel connection and warns the user about this. The solution in this case is to have the user go to the client web service and switch the "CONNECT" option to "LOGIN" and log on. A list of available files will be shown that this user can download and use. Below that a Google Authenticator code and QR code will be shown. The user can either manually type this code into the Google Authenticator application, or use a camera to scan the QR code. Once this is done, click the button "I scanned the QR code" to confirm that the code has been stored in the Google Authenticator application. Now the user can start a VPN tunnel connection and the OpenVPN client will then ask for user name, password, and the Google Authenticator code.

Google Authenticator code must be a number
After the Google Authenticator shared secret code has been typed or scanned into the Google Authenticator application, it will generate a new 6 digit code every 30 seconds. If instead you enter something unexpected like your password instead of that 6 digit code, then you will see this error message. The solution is to use the Google Authenticator application and enter the 6 digit code into the Google Authenticator field when asked.

Google Authenticator code is incorrect
This means that the 6 digit code that was entered is not correct. To understand why is it going wrong there are a few things to note first. Google Authenticator uses the current date and time, and adjusts automatically for time zones. This assumes of course that the server and the device with the Google Authenticator app both have the correct timezone set, and the correct time and date set. That information plus a shared secret key that is known by the Access Server and the Google Authenticator application which was agreed upon when you initially typed/scanned the code during Google Authenticator enrollment is all that is used to create the unique 6 digit codes that are valid for 30 seconds.

So to oversimplify this: secret shared key + current time in correct timezone = 6 digit code.
Such a code is valid for 30 seconds. We allow the immediate previous and following code as well to give a bit of a leeway in the timing. What all of this means is that there are really only two possibilities when you get the error message that the Google Authenticator code is incorrect. Either the date/time or timezone setting is wrong on the server or the device running the Google Authenticator application, or the shared secret key is wrong.

You can try resetting the Google Authenticator key for this user and completing enrollment again. In most cases though the issue is a drifting system clock on the server, especially on virtual cloud-based hardware, which can be solved by installing an NTP (Network Time Protocol) client program which can automatically pull the correct time for time servers on the Internet and ensure the time doesn't drift. A time difference of more than 30 seconds can already be a problem. Mobile devices usually already do time synchronization by themselves. In the past though we have seen a bug with a specific version of iOS which skewed the time by one minute, which upset Google Authenticator. That issue was resolved by updating iOS to a newer version.