Authentication Options And Command Line Configuration

Access Server authentication modes

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

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

Local authentication

Local authentication is Access Server's default authentication method where Access Server stores usernames and passwords in the configuration database files. Local authentication is a simple and portable authentication system. You can copy the configuration database — keeping the same usernames and passwords — to a new installation if you need to move to a new Access Server server.

You can manage local authentication 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. You can set it in the Admin Web UI. Sign in to the Admin Web UI and make the changes depending on the access control level you want:

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 for more information.

LDAP authentication

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

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 checks the LDAP server to validate credentials when a user connects to the VPN.

Note: Access Server can't make password changes for users in LDAP.

RADIUS authentication

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

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 checks the RADIUS server to validate credentials when a user connects to the VPN.

Note: Access Server can't make password changes for users in RADIUS.

SAML authentication

Security assertion markup language (SAML) is a standard for authenticating users by single sign-on (SSO) providers. Access Server 2.11 and newer 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 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, and AWS.

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

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

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, RADIUS, or SAML 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

You can create a custom authentication system for Access Server using the post_auth functionality to write your code. You load a Python script, which runs after successful authentication and before the user establishes a VPN tunnel.

Refer to the following documentation for example scripts:

Refer to Post_auth programming notes and examples for more details.

Note: You can't use post-auth scripts to implement MFA if you've enabled TOTP MFA in the Admin Web UI. You must do one or the other. You can use a post-auth script that doesn’t implement MFA with Access Server's TOTP MFA functionality.

Local authentication commands

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

Access Server 2.10.1 and newer supports hashed passwords in the user properties database in SHA256, PBKDF2, or SCrypt format. New password hashes are stored as PBKDF2 by default. PBKDF2 is implemented with 16-byte random salt, SHA256 hash, 32 length, and 100000 iterations. During Access Server upgrades, currently stored local user password hashes remain the same. To retain backward compatibility, the older hash formats still work, but when local user passwords are updated, they are replaced with PBKDF2 hashes.

Access Server 2.11.0 and newer introduces optional support to use the OpenSSL SCrypt function to create hashes for local user passwords. It’s slightly more secure and efficient than PBKDF2, but it isn’t compatible with FIPS mode, or 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

Prefer the SCrypt password hashing method (on Access Server 2.11 and newer):

./sacli --key "auth.local.0.prefer_scrypt" --value "true" 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

For more information, refer to Managing user and group properties from command line.

Note: On Access Server 2.9 and older, the openvpn bootstrap user is an exception to the local authentication process. This user is created during installation and uses PAM for authentication. It also displays with your users in the Admin Web UI. You can alter or disable this user 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 Access Server 2.10 and newer, Access Server creates the openvpn user as an administrative user in the 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.

The user can sign in once the same username exists in Access Server and the operating system. Access Server looks up this user in User Permissions and automatically applies the user-specific properties specified. If you notice that properties aren't applied, ensure the name is correct. The username in PAM is leading here.

Important: 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 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

For more information, refer to Managing user and group properties from command line.

RADIUS authentication commands

Usernames and passwords are stored in a central database and 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 via the Admin Web UI or 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, ensure the name is correct. The user name in the directory is leading here.

You can define all configuration parameters in the Admin Web UI under "Authentication" and "RADIUS" via the command line. You can only set some settings from the command line. We list all available options below.

Access Server supports up to five RADIUS servers. In the Admin Web UI, you configure their settings with a row for each server. You can set each setting for server 0, server 1, and so on when using commands. 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 (the 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 user-specific properties like auto-login privilege, group assignment, and static IP. You can do this via the Admin Web UI or 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 the configuration parameters in the Admin Web UI under “Authentication” and “LDAP” via the command line. You can only set some settings from the command line. We list all of the available options below.

Note: Current Access Server versions use the LDAP3 library. We recommend upgrading if your Access Server is an older version using the OpenLDAP library.

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. Before Access Server 2.10, we didn’t have a check 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 before 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 levels (default is 0):

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

Note: Access Server 2.13.0 and newer supports these debug levels:

off=0 — nothing is logged
error=10 — only exceptions are logged
basic=20 — library activity is logged, only operation result is shown
protocol=30 — LDAPv3 operations are logged, sent requests and received responses are shown
network=40 — socket activity is logged
extended=50 — LDAP messages are decoded and properly printed

Refer to LDAP documentation for specific information about the debug levels.

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

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

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