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
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'}

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.

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

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.