Authentication options and command line configuration

Change authentication mode

In the Admin UI under "Authentication" it is possible to select one of 4 methods for authenticating user credentials; LOCAL, PAM, RADIUS or RADIUS. This can be done by changing the configuration key auth.module.type. This configuration key is not optional and is by default set to PAM. With LDAP and RADIUS additional settings are required to be able to authenticate users, for example which server to contact and any required shared secret code to be able to access the external authentication backend.

With the local authentication mode the user names and the passwords are all stored in the configuration database files of the Access Server program itself. This makes Access Server portable and keeps things simple. Portable because you can copy the configuration database files to a new installation and all the users and passwords will be contained in those files. And simple because you can set passwords for users from the Admin UI without having to access any other system to manage users and credentials.

With PAM you can use the user accounts that are present in the operating system that the Access Server program is installed on. Additionally, PAM can be extended to reference other authentication sources as well, and PAM accounts can also be used for other services that are installed on that same operating system as well. Via SSH, for example, it is possible for a user to log in and change his or her own password without intervention from an administrative user. It is not possible for Access Server itself to change passwords for users in PAM.

With RADIUS you can authenticate against a RADIUS server. This can be with an open source program or this can be a Windows Server with Active Directory for example. The Windows Server operating system comes with tools that allow you to manage user and passwords, and if users can log on via Remote Desktop Protocol to a terminal server, they can for example change their own passwords in the directory. The Access Server can check with the RADIUS server to see if the credentials are correct when the user makes a VPN connection.  It is not possible for Access Server itself to change password for users in RADIUS.

With LDAP you can authenticate against a directory server. This can be an open source program or this can be a Windows Server with Active Directory for example. As with RADIUS, tools and methods are available on Windows Server operating system to manage users and password. The Access Server can check with the directory server to see if the credentials are correct when the user makes a VPN connection. It is not possible for Access Server itself to change passwords for users in LDAP.

To set authentication mode to local:

./sacli --key "auth.module.type" --value "local" ConfigPut
./sacli start

To set authentication mode to PAM:

./sacli --key "auth.module.type" --value "pam" ConfigPut
./sacli start

To set authentication mode to RADIUS:

./sacli --key "auth.module.type" --value "radius" ConfigPut
./sacli start

To set authentication mode to LDAP:

./sacli --key "auth.module.type" --value "ldap" ConfigPut
./sacli start

Custom authentication systems

This is not something we actively support in the sense that we do not develop custom code for you, but the Access Server has something called post_auth and it allows you to add your own code to the authentication process. This is a function in the Access Server whereby you can load Python script code that runs after an authentication has successfully been done, but before the user is able to progress to the web interface or establish a VPN tunnel. With such a script you can add for example a requirement for a device to have a specific MAC address before it is able to connect, or to request an OTP (one time password) after the user has already entered his user name and password. The Access Server already has Google Authenticator multi-factor support built in, but other systems can also be supported in this way.

Additionally, you can perform extra checks on users like for example with LDAP authentication you can check in the directory server which LDAP group the user that is trying to log on is a part of, and based on that information, assign the user certain access rules or put the user in a specific group, or even just deny access.

It's also possible to for example set the authentication system to PAM and reconfigure the 'openvpnas' PAM module to allow any and all credentials to be accepted, after which the post_auth script runs and implements its own checks on the credentials entered. This way you can replace the authentication system in Access Server entirely, with your own system. This way you can in theory connect to any authentication system, as long you know how to connect to it from within Python code.

We have a separate page with information about post_auth which you should read if you wish to learn more about the post_auth function. We have sample code there as well for LDAP group mapping and MAC address filtering.

Local authentication

In local authentication mode, the users and passwords are stored in the user_prop.db database file. User specific properties are also stored in that file. The passwords are stored in the database as sha256 hashes, so they are not stored in plain-text and the hashes can only be used to verify if the hash of a password that a user provides matches with what we have stored in the database. The sacli SetLocalPassword function takes a password in plain-text and stores it as a hash in the database. Below are some basic commands that you can run in the command line as root user to manage user accounts and credentials.

To set authentication mode to local:

./sacli --key "auth.module.type" --value "local" ConfigPut
./sacli start

Add a new user from scratch:

./sacli --user <USER_NAME> --key "type" --value "user_connect" UserPropPut

Set password for a user in local authentication mode:

./sacli --user <USER_NAME> --new_pass <PASSWORD> SetLocalPassword

Remove password for a user in local authentication mode:

./sacli --user <USER_NAME> RemoveLocalPassword

Remove all properties on a user to delete the user:

./sacli --user <USER_OR_GROUP> UserPropDelAll

There are more details on user and group properties management on the user and group management page.

An exception to local authentication is the standard administrative user account that is created during the installation of the OpenVPN Access Server product, which always exists in PAM. By default this user is called simply openvpn and always authenticates through PAM. The user name does not necessarily have to be openvpn, another name could have been chosen during installation. It can also be altered or disabled at any time. The function sacli SetLocalPassword has on effect on this user. To set a password for the user see the PAM authentication information below.

PAM authentication

In PAM authentication mode, the users and passwords for authentication are stored in the operating system. User specific properties are stored in the user_prop.db database file. After you created a user in the operating system and set a password for it, and you want to set any user-specific properties on it like auto-login privilege, group assignment, static IP, etcetera, you must also add this user to the "User Permissions" table. This can be done in the Admin UI or via the command line. Once the user is present in Access Server with the exact same name as the user has in the operating system, then when this user logs in, the Access Server looks up this user in User Permissions and the user-specific properties specified there are automatically applied. If you notice that properties are not applied make sure the name is correct. The user name in PAM is leading here.

It is important to note that the user name lookup is case sensitive. That means that if you create a user in the operating system called "justin" and you want to set user-specific properties on it that you use that same spelling in User Permissions or command line as well. If you change it to "Justin" or "JUSTIN" it will not match and therefore not apply the user-specific properties. By default most Linux operating systems prefer that you use only lowercase user names. It is best to adhere to this in PAM authentication mode. Below are some basic commands that you can run in the command line as root user to manage user accounts and credentials.

To set authentication mode to PAM:

./sacli --key "auth.module.type" --value "pam" ConfigPut
./sacli start

Add a new user from scratch, you will be asked to provide a password:

adduser <USER_NAME>
./sacli --user <USER_NAME> --key "type" --value "user_connect" UserPropPut

Set password for an existing user in PAM authentication mode:

passwd <USER_NAME>

Remove a user from both PAM and the Access Server:

deluser <USER_NAME>
./sacli --user <USER_OR_GROUP> UserPropDelAll

There are more details on user and group properties management on the user and group management page.

RADIUS authentication

(this documentation item has not been written yet - UNFINISHED MARKER)

To set authentication mode to RADIUS:

./sacli --key "auth.module.type" --value "radius" ConfigPut
./sacli start

LDAP authentication

In LDAP authentication mode, the users and passwords for authentication are stored in an LDAP server. This could be OpenLDAP, or Windows Server with Active Directory and an LDAP connector, or any other LDAP server program that adheres to the LDAP standard. After you created a user in the directory server and set a password for it, and you want to set any user-specific properties on it like auto-login privilege, group assignment, static IP, etcetera, you must also add this user to the "User Permissions" table. This can be done in the Admin UI or via the command line. Once the user is present in Access Server with the exact same name as the user has in the directory server, then when this user logs in, the Access Server looks up this user in User Permissions and the user-specific properties specified there are automatically applied. If you notice that properties are not applied make sure the name is correct. The user name in the directory is leading here.

All of the configuration parameters that can be found in the Admin UI under "Authentication" and "LDAP" can be configured via the command line as well. There are also settings that can only be set from the command line. All of the available options are listed below.

To set authentication mode to LDAP:

./sacli --key "auth.module.type" --value "ldap" ConfigPut
./sacli start

To set primary LDAP server address:

./sacli --key "auth.ldap.0.server.0.host" --value <FQDN_OR_IP> ConfigPut
./sacli start

To set backup LDAP server address:

./sacli --key "auth.ldap.0.server.1.host" --value <FQDN_OR_IP> ConfigPut
./sacli start

Optionally set bind credentials (usually an admin account):

./sacli --key "auth.ldap.0.bind_dn" --value <USER_NAME> ConfigPut
./sacli --key "auth.ldap.0.bind_pw" --value <PASSWORD> ConfigPut
./sacli start

Use anonymous binding (the default):

./sacli --key "auth.ldap.0.bind_dn" ConfigDel
./sacli --key "auth.ldap.0.bind_pw" ConfigDel
./sacli start

Set a friendly name for the LDAP servers (purely for ease of administration):

./sacli --key "auth.ldap.0.name" --value <FRIENDLY_NAME> ConfigPut

Base DN to search for user entries:

./sacli --key "auth.ldap.0.users_base_dn" --value <BASE_DN> ConfigPut
./sacli start

LDAP Attribute that contains the user name (sAMAccountName in Active Directory):

./sacli --key "auth.ldap.0.uname_attr" --value <ATTRIBUTE_NAME> ConfigPut
./sacli start

Optionally specify an addiitional LDAP expression that must evaluate as true to allow the user to log on. Below is an example where the requirement is that the users trying to log on would need to be members of a built-in LDAP group called "Administrators" on a directory server where the base DN is "DC=myserver,DC=mycompany,DC=tld". Other logic is possible as well, for example AND/OR logic, but for this we refer you to documentation on the LDAP server software you're using.

  • memberOf=CN=Administrators,CN=Builtin,DC=myserver,DC=mycompany,DC=tld

To set this in the configuration database via command line:

./sacli --key "auth.ldap.0.add_req" --value <LDAP_EXPRESSION> ConfigPut
./sacli start

Primary LDAP server timeout before switching to backup LDAP server (default is 4 seconds):

./sacli --key "auth.ldap.0.timeout" --value <SECONDS> ConfigPut
./sacli start

Implicitly chase referrals or not. 0 means no, 1 means yes (default is 0):

./sacli --key "auth.ldap.0.referrals" --value <NUMBER> ConfigPut
./sacli start

Configure using SSL over the connection to the LDAP server or not. There are three possible choices:

  1. never: do not use SSL (the default setting)
  2. adaptive: try using SSL, if that fails, use plain-text
  3. always: always use SSL
./sacli --key "auth.ldap.0.use_ssl" --value <VALUE> ConfigPut
./sacli start

Configure how to verify the SSL certificate when connecting to the LDAP server. There are three possible choices:

  1. never: no peer certificate is required
  2. allow: request a peer certificate, but session will not be aborted if certificate cannot be validated
  3. demand: a valid peer certificate is required, session will be aborted if one is not provided
./sacli --key "auth.ldap.0.ssl_verify" --value <VALUE> ConfigPut
./sacli start

Specify a CA certificate bundle file to use for validating the LDAP server certificate (PEM format):

./sacli --key "auth.ldap.0.ssl_ca_cert" --value_file <FILE_NAME> ConfigPut
./sacli start

Get more debug information by setting debug level (default is 0):

./sacli --key "auth.ldap.0.debug_level" --value <NUMBER> ConfigPut
./sacli start

Get debug information by setting trace level (default is 0):

./sacli --key "auth.ldap.0.openldap_trace_level" --value <NUMBER> ConfigPut
./sacli start

There are a number of important notes to make about some of the above configuration keys. OpenVPN Access Server uses the OpenLDAP library to connect to LDAP servers. A number of the configuration keys above correspond to certain settings known in OpenLDAP under different names. Also, the debug and trace options may be a security issue as these can in some cases output sensitive data to the log file if these values are not set to zero (default is the safe 0 setting which means no debug or trace logging). Below are a few configuration keys and how they relate to parameters in OpenLDAP.

  • auth.ldap.0.referrals: corresponds to LDAP_OPT_REFERRALS setting in OpenLDAP
  • auth.ldap.0.timeout: corresponds to LDAP_OPT_TIMEOUT and LDAP_OPT_NETWORK_TIMEOUT settings in OpenLDAP
  • auth.ldap.0.ssl_ca_cert: corresponds to LDAP_OPT_X_TLS_CACERTFILE setting in OpenLDAP
  • auth.ldap.0.debug_level: corresponds to the LDAP_OPT_DEBUG_LEVEL setting in OpenLDAP
  • auth.ldap.0.openldap_trace_level: corresponds to the trace level setting in OpenLDAP

Troubleshooting authentication problems

For more information please see the authentication troubleshooting page.