Authentication options and command line configuration

OpenVPN Access Server authentication modes

OpenVPN Access Server uses one of four methods for authenticating users:

  1. Local
  2. LDAP
  3. RADIUS
  4. PAM

You can configure the first three — Local, LDAP, and RADIUS — directly in the Admin Web UI. Sign in to your Admin Web UI and click on Authentication > General. Alternatively, you can configure this from the command line by changing the configuration key, auth.module.type.

Local authentication

Local authentication is the default authentication for current installations of OpenVPN Access Server. (Previously, OpenVPN Access Server version 2.1.4 and older versions had PAM as the default.) With local authentication enabled Access Server stores usernames and passwords in the configuration database files. Local authentication is a simple and portable authentication system. Should you need to move to a new server installation for Access Server, you can copy the configuration database files to your new installation, keeping the same users and passwords. The simplicity is in the management of users, all done through the Admin Web UI:

  1. Sign in to the Admin Web UI.
  2. Click User Management > User Permissions.

With local authentication, you can allow users to change their passwords from the Client UI. “Allow password change from CWS” is a setting at the user and group level. You can set it in the Admin Web UI.

For an individual user:

  1. Sign in to the Admin Web UI.
  2. Click User Management > User Permissions.
  3. Click More Settings for the specific user.
  4. Set “Allow password change from CWS” to default, yes, or no.
  5. Click Save Settings and Update Running Server.

For a group:

  1. Sign in to the Admin Web UI.
  2. Click User Management > Group Permissions.
  3. Click More Settings for the specific group.
  4. Set “Allow password change from CWS” to default, yes, or no.
  5. Click Save Settings and Update Running Server.

Globally:

  1. Sign in to the Admin Web UI.
  2. Click Configuration > CWS Settings.
  3. Set "Allows Users to change their own password" to show or hide.
  4. Click Save Settings and Update Running Server.

Refer to Adding and Configuring Users for more information.

LDAP authentication

Lightweight directory access protocol (LDAP) is a protocol used for directory service authentication. You can use LDAP to integrate OpenVPN Access Server with directory services such as Active Directory, JumpCloud, Okta, and others.

LDAP requires additional settings in the Admin Web UI — or beyond the auth.module.type configuration key — to authenticate users. These settings include which server to contact, and any required shared secret code to access the authentication backend.

Once configured, Access Server then checks the LDAP server to validate credentials when a user makes a VPN connection. Access Server cannot make password changes for users in LDAP. Access Server does this using whatever tools came with the LDAP-credential solution.

RADIUS authentication

Remote authentication dial-in user service (RADIUS) is another protocol used for directory service authentication. You can use RADIUS to integrate OpenVPN Access Server with directory services such as Active Directory, Okta, open-source programs, and others.

RADIUS requires additional settings in the Admin Web UI — or beyond the auth.module.type configuration key — to authenticate users. These settings include which server to contact, and any required shared secret code to access the authentication backend.

Once configured, Access Server then checks the RADIUS server to validate credentials when a user makes a VPN connection. Access Server cannot make password changes for users in RADIUS. Access Server does this using whatever tools come with the RADIUS-credential solution.

PAM authentication

When you select Pluggable Authentication Modules (PAM), Access Server uses the operating system of the Unix host running the server for authenticating users. That means that user accounts in the operating system where Access Server is installed are the user accounts for VPN clients. You must manage PAM user accounts in the OS. The Admin Web UI doesn’t have configuration options for PAM. However, you can extend PAM to reference other authentication sources, and other services installed on the same appliance can use PAM accounts. While Access Server can’t change passwords for users in PAM, a user can sign in over SSH, for example, and change their password.

Changing authentication modes

Change the authentication mode in the Admin Web UI

  1. Sign in to the Admin Web UI.
  2. Click Authentication > General.
  3. Select the authentication mode desired and click Save.
  4. Click Update running server.

Alternatively, you can enable each authentication mode from their specific page in the Admin Web UI.

  • For LDAP, click Authentication > LDAP and Use LDAP, then save and update the server.
  • For RADIUS, click Authentication > RADIUS and Use RADIUS, then save and update the server.
  • For PAM, click Authentication > PAM and Use PAM, then save and update the server.

Note: LDAP and RADIUS require additional configuration steps to define the directory services connection information.

Change the authentication mode in the command line

The following commands require that you connect directly to your server with root privileges and run them from /usr/local/openvpn_as/scripts/.

Set the authentication mode:

./sacli --key "auth.module.type" --value "<MODE>" ConfigPut
./sacli start

<MODE> can have these values:

  • local
  • pam
  • radius
  • ldap

Custom authentication systems

If you wish to create a custom authentication system for OpenVPN Access Server, it is possible to use the post_auth functionality of Access Server to write your own code. You can load Python script code, which runs after authentication succeeds and before the user can establish a VPN tunnel.

Refer to the following documentation for example scripts:

Refer to Post_auth programming notes and examples for more details.

Note: Custom authentication systems using post-auth to implement MFA can’t be used with Google Authenticator enabled. You must do one or the other. A post-auth script that doesn’t implement MFA can be used with Google Authenticator enabled.

Local authentication commands

In local authentication mode, 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 — the sacli SetLocalPassword function stores a plain-text password as a hash in the database. Below are basic commands to manage local user accounts and credentials.

The following commands require that you connect directly to your server with root privileges and run them from /usr/local/openvpn_as/scripts/.

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 user properties to delete the user:

./sacli --user <USER_OR_GROUP> UserPropDelAll

Refer to Managing user and group properties from command line for more information.

Note: The openvpn bootstrap user is an exception to the local authentication process. This user is created during the installation of Access Server and uses PAM for authentication. It also displays with your users in the Admin Web UI. This user can be altered or disabled at any time, and the function sacli SetLocalPassword works for this user. To set a password for the user, see the PAM authentication information below.

PAM authentication commands

In PAM authentication mode, user and password authentications are stored in the operating system. User-specific properties are stored in the user_prop.db database file. After you create a user in the operating system and set a password, you must add the user to Access Server. You can add users in the Admin Web UI under User Management. Or you can add users in the command line interface. You must add each user to the “User Permissions” table and set user-specific properties such as auto-login, group assignment, and static IP.

Once the same username exists in Access Server and the operating system, the user can log in. Access Server looks up this user in User Permissions and automatically applies the user-specific properties specified. If you notice that properties are not applied, make sure the name is correct. The user name in PAM is leading here.

Be aware that the username lookup is case-sensitive. For a username in the operating system, “justin”, you must use “justin” in User Permissions or command line to set user-specific properties. By default, most Linux operating systems prefer that you use only lowercase usernames. It is best to adhere to this in PAM authentication mode. Below are some basic commands to manage PAM user accounts and credentials.

The following commands require that you connect directly to your server with root privileges and run them from /usr/local/openvpn_as/scripts/.

Set authentication mode to PAM:

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

Add a new user from scratch:

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 Access Server:

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

Refer to Managing user and group properties from command line for more information.

RADIUS authentication commands

Users and passwords for authentication are stored in a central database, accessed through a RADIUS server in RADIUS authentication mode. You can integrate Access Server with Okta, Active Directory, JumpCloud, and other directory services using RADIUS. After creating a user in the directory server, you must add this user to Access Server to set user-specific properties like auto-login privilege, group assignment, and static IP. You can do this in the Admin Web UI or via the command line. Once the user is present in Access Server with the same name as in the directory server, when this user logs in, Access Server looks up this user in User Permissions and automatically applies the user-specific properties specified there. If you notice that properties aren’t applied, make sure the name is correct. The user name in the directory is leading here.

You can also define all of the configuration parameters in the Admin Web UI under "Authentication" and "RADIUS" via the command line. Some settings can only be set from the command line. All of the available options are listed below.

Access Server supports up to five RADIUS servers. In the Admin Web UI, you configure their settings with a row for each server. When using commands, you can set each setting for server 0, server 1, and so on. Our examples set the values for server 0, the first server displayed in the Admin Web UI list.

Set authentication mode to RADIUS:

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

Set RADIUS authentication method. There are three options (default is mschap2):

  • pap
  • chap
  • mschap2
./sacli --key "auth.radius.0.auth_method" --value <VALUE> ConfigPut
./sacli start

Define the RADIUS server name:

./sacli --key "auth.radius.0.name" --value <FQDN_OR_IP> ConfigPut
.sacli start

Define the shared secret:

./sacli --key "auth.radius.0.server.0.secret" --value <SHARED_SECRET> ConfigPut
./sacli start

Set the authentication port (default is 1812):

./sacli --key "auth.radius.0.server.0.auth_port" --value "1812" ConfigPut
./sacli start

Set the accounting port (default is 1813):

./sacli --key "auth.radius.0.server.0.acct_port" --value "1813" ConfigPut
./sacli start

Enable RADIUS accounting:

./sacli --key "auth.radius.0.acct_enable" --value "true" ConfigPut
./sacli start

Set the number of authentication attempts sent to the RADIUS server (default is 2):

./sacli --key "auth.radius.0.per_server_retries" --value "2" ConfigPut
.sacli start

Set the RADIUS server timeout in seconds (default is 7):

./sacli --key "auth.radius.0.per_server_timeout" --value <SECONDS> ConfigPut
./sacli start

LDAP authentication commands

In LDAP authentication mode, the users and passwords for authentication are stored in an LDAP server such as OpenLDAP, Windows Server with Active Directory and an LDAP connector, JumpCloud, Okta, or any other LDAP server program that adheres to the LDAP standard. After creating a user in the directory server, you must add this user to Access Server to set any user-specific properties like auto-login privilege, group assignment, and static IP. You can do this in the Admin Web UI or via the command line. Once the user is present in Access Server with the same name as in the directory server, when this user logs in, Access Server looks up this user in User Permissions and automatically applies the user-specific properties specified there. If you notice that properties aren’t applied, make sure the name is correct. The user name in the directory is leading here.

You can also define all of the configuration parameters in the Admin Web UI under “Authentication” and “LDAP” via the command line. Some settings can only be set from the command line. All of the available options are listed below.

Set authentication mode to LDAP:

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

Set primary LDAP server address:

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

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

You also have the option to specify an additional LDAP expression that must evaluate as true to allow the user to sign in. Below is an example with the requirement that the users trying to log on must 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".

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

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 the session won’t be aborted if the certificate can’t be validated
  3. demand: a valid peer certificate is required, the session will be aborted if one isn’t 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 <PATH_TO_FILE_NAME> ConfigPut
./sacli start

The <PATH_TO_FILENAME> must be a full path like "/usr/local/openvpn_as/ca_cert.pem".

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 several 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 aren’t 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_LEVELsetting in OpenLDAP
  • auth.ldap.0.openldap_trace_level: corresponds to the trace level setting in OpenLDAP

Troubleshooting authentication problems

For more information, refer to the authentication troubleshooting page.