Authentication Options And Command Line Configuration

OpenVPN Access Server authentication modes

OpenVPN Access Server supports five methods for authenticating users:

You can configure the first four — local, LDAP, RADIUS, and SAML — directly in the Admin Web UI. PAM is handled by the operating system. Sign in to your Admin Web UI and click on Authentication > Settings. Alternatively, you can configure this from the command line by changing the configuration key, auth.module.type.

OpenVPN Access Server 2.10 and newer supports more than one authentication system at the same time. For instance, you can set up your end users with LDAP authentication integrated with Active Directory, and create your administrator accounts on local authentication. For more information, refer to OpenVPN Access Server’s User Authentication System.

Local authentication

Local authentication is the default authentication for current installations of OpenVPN Access Server. With local authentication enabled Access Server stores usernames and password hashes in the user properties database. 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 your configuration 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:

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

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

For a user: Click User Management > User Permissions > More Settings and set “allow password change from CWS” to yes.
For a group: Click User Management > Group Permissions > More Settings and set “allow password change from CWS” to yes.
At the global level: Click Authentication > Settings and set “allow local users to change password” to yes (default).

Refer to Adding and Configuring Users and Authentication options and command line configuration 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, Google, and others.

LDAP requires configuration in the Admin Web UI before it can be used to authenticate users. These settings include which server to contact, any required bind user credentials to access the authentication backend, and the search query and user ID attribute to search for.

Once configured, Access Server then checks the LDAP server to validate credentials when a user makes a VPN connection. Access Server can authenticate against an LDAP server, but cannot make password changes for users in LDAP. That should be done with the tools that come with the LDAP 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 configuration in the Admin Web UI before it can be used 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 can authenticate against an RADIUS server, but cannot make password changes for users in RADIUS. That should be done with the tools that come with the RADIUS solution.

SAML authentication

Security Assertion Markup Language (SAML) is a standard for authenticating users by single sign-on (SSO) providers. Access Server 2.11 enables federated SSO with SAML 2.0, an industry standard used for securely exchanging SAML assertions that pass information about a user between a SAML authority (called an Identity Provider, or IdP) and a SAML consumer (called a Service Provider, or SP).

You can use a third-party SAML IdP to establish SSO access to the Admin and Client Web UIs and to authenticate before a VPN connection. SAML requires additional settings in the Admin Web UI — or beyond the auth.module.type configuration key — to authenticate users. We provide how-to documentation for some, but not all, identity providers, including Azure AD, Google Workspace, Okta, OneLogin, Keycloak, JumpCloud, AWS, and Auth0.

PAM authentication

When you select Pluggable Authentication Modules (PAM), Access Server uses the operating system running the server for authenticating users. That means that user accounts in the operating system where Access Server is installed are possible user accounts for VPN access. You must manage PAM user accounts in the OS. The Admin Web UI doesn’t have configuration options for PAM, this is done in the operating system. It is possible to 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

Sign in to the Admin Web UI.
Click Authentication > Setting.
Under Default Authentication System, select the authentication mode desired as the default authentication system and click Save.
Click Update running server.

For OpenVPN Access Server 2.10.2 and newer, you can enable LDAP and RADIUS authentication as additional authentication options for users and groups, and you can enable SAML with 2.11.0 and newer. Ensure you configure these authentication methods before you enable them.

For LDAP, click Authentication > LDAP and set Enable LDAP authentication to Yes, then save and update the server.
For RADIUS, click Authentication > RADIUS and set Enable RADIUS Authentication to Yes, then save and update the server.
For SAML, click Authentication > SAML and set Enable SAML Authentication to Yes, then save and update the server.

You can then choose LDAP, RADIUS, or SAML as the authentication methods for users and groups:

For users, click User Management > User Permissions, click More Settings for the user, select the authentication method under Configure user authentication method, then save and update the server.
For groups, click User Management > Group Permissions, click More Settings for the group, select the authentication method under Configure user authentication method, then save and update the server.

Note: LDAP, RADIUS, and SAML require additional configuration steps. You can’t enable them as the default authentication method or for users or groups if they aren’t configured.

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
saml

Note: Ensure you configure RADIUS, LDAP, or SAML prior to setting them as the authentication mode.

OpenVPN Access Server 2.10 and newer supports multiple authentication systems. For instance, your admin users can sign in with credentials stored in the local database while your end users authenticate against an LDAP server. The above command sets the default authentication mode. You can allow LDAP or RADIUS authentication for defined users or group with the below commands:

Allow LDAP authentication for users and groups:

./sacli --key "auth.ldap.0.enable" --value "True" ConfigPut
./sacli start

Allow RADIUS authentication for users and groups:

./sacli --key "auth.radius.0.enable" --value "True" ConfigPut
./sacli start

Allow SAML authentication for user and groups:

./sacli --key "auth.saml.0.enable" --value "True" ConfigPut
./sacli start

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

For local authentication mode, Access Server by default stores user and group properties in the /usr/local/openvpn_as/etc/db/userprop.db file.

Access Server 2.10.1 and newer supports reading hashed passwords in the user properties database in the format of SHA256, PBKDF2, or SCrypt, and new password hashes are written as PBKDF2 by default. PBKDF2 is implemented with 16-byte random salt, SHA256 hash, 32 length, and 100000 iterations. Versions of Access Server older than 2.10.1 store the hashes in SHA256 format. During upgrades of Access Server, existing local user password hashes remain the same. To retain backward compatibility, the other hash formats will still be read, but when a local user's password is updated, the password hash will be replaced with a new PBKDF2 hash.

Access Server 2.11.0 and newer introduces optional support to use the OpenSSL SCrypt function instead of PBKDF2 to create new hashes for local user passwords. It’s slightly more secure and efficient than PBKDF2, but isn’t compatible with FIPS mode nor is it available on all platforms, therefore we didn’t enable it by default. You can enable it on the command line with the auth.local.0.prefer_scrypt parameter.

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

Set the authentication mode for the user (on Access Server 2.10 and newer):

./sacli --user <USER> --key "user_auth_type" --value "local" UserPropPut

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: On OpenVPN Access Server 2.9 and older, 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, but the function sacli SetLocalPassword doesn’t work for this user. To set a password for the user, see the PAM authentication information below. On OpenVPN Access Server 2.10 and newer, the openvpn user is created as an administrative user in Access Server’s local database.

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 pap):

pap
chap
mschap2

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

Define the friendly RADIUS server name:

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

Define the RADIUS hostname or IP address:

./sacli --key "auth.radius.0.server.0.host" --value <FQDN_OR_IP_ADDRESS> 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 1):

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

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

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

Enable case-sensitive account name matching (the user admin is different from Admin):

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

Enable RADIUS authentication once you’ve finished configuration:

./sacli --key "auth.radius.0.enable" --value True 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

You can enable an additional LDAP check when using auto-login profiles. Previous to Access Server 2.10, we didn’t have a check in place for LDAP authentication with these profiles. Instead, Access Server authenticated against the client certificate in the .ovpn profile. This could lead to a use case where you’ve removed or disabled the user in LDAP, but they can still connect to the VPN. Resolving this prior to 2.10 required manually revoking the autologin certificate for the user. Using the LDAP check is much more user friendly.

Access Server 2.10 and newer has an LDAP check to ensure the user exists with the LDAP server before successfully connecting. Use the following commands to configure this.

Enforce LDAP authorization for users connecting with auto-login profiles:

./sacli --key "auth.ldap.0.user_exists_check" --value "true" ConfigPut
./sacli start

Disregard LDAP authorization for users connecting with auto-login profiles:

./sacli --key "auth.ldap.0.user_exists_check" --value "false" ConfigPut
./sacli start

The following table helps clarify how to use the LDAP check for your use cases:

LDAP Check Enabled	User Account Present on LDAP	Authorized
Yes	No	No
Yes	Yes	Yes
No	Yes	Yes
No	No	Yes; only if previously imported autologin profile when the user account was present on LDAP.

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:

never: do not use SSL (the default setting)
adaptive: try using SSL; if that fails, use plain-text
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:

never: no peer certificate is required
allow: request a peer certificate, but the session won’t be aborted if the certificate can’t be validated
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

Enable case-sensitive account name matching (the user admin is different from Admin):

./sacli --key "auth.ldap.0.case_sensitive" --value "true" ConfigPut
./sacli start

Enable LDAP authentication once you've finished configuration:

./sacli --key "auth.ldap.0.enable" --value True 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

SAML authentication commands

In SAML authentication mode, users authenticate with an SSO provider. We provide documentation for some, but not all, providers:

You can also define all of the configuration parameters in the Admin Web UI under “Authentication” and “SAML” via the command line.

Set authentication mode to SAML:

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

Define the IdP entity ID:

./sacli --key "auth.saml.0.idp_entityid" --value <IDP ENTITY ID> ConfigPut
./sacli start

Define the IdP sign-on endpoint:

./sacli --key "auth.saml.0.idp_signon_endpoint" --value <IDP SIGNON ENDPOINT> ConfigPut
./sacli start

Define the SAML service provider hostname (optional, if you want to set a separate hostname for SAML from the hostname used by your Admin and Client Web UIs):

./sacli --key "auth.saml.0.sp_hostname" --value <HOSTNAME> ConfigPut
./sacli start

Troubleshooting authentication problems

For more information, refer to the authentication troubleshooting page.

Questions

Questions

Authentication options and command line configuration

OpenVPN Access Server authentication modes

Local authentication

LDAP authentication

RADIUS authentication

SAML authentication

PAM authentication

Changing authentication modes

Change the authentication mode in the Admin Web UI

Change the authentication mode in the command line

Custom authentication systems

Local authentication commands

PAM authentication commands

RADIUS authentication commands

LDAP authentication commands

SAML authentication commands

Troubleshooting authentication problems

Updates & Announcements

Cyber Shield Released

Release Notes 2.11.3