How session tokens work in Access Server

Since OpenVPN Access Server 1.8.0 a session-token-based authentication system was added. What this does is after successful authentication give the user a unique string of numbers and letters that identifies that user’s session. The purpose of this is to not have to remember the user’s credentials in memory. Normally when a connection gets interrupted and the OpenVPN tunnel has to reconnect, you would have to enter your credentials again to get connected. With a session token instead, this can be automated, without actually storing the user’s credentials. This avoids having to ask the user repeatedly for credentials during the course of an active OpenVPN session and improves security at the same time.

These are the main properties that describe what a session token is and how it behaves on Access Server:

  • Use of a session token avoids having to cache the user’s credentials.
  • A session token is a base64 string constructed from a 128 cryptographically strong random number.
  • A session token is issued to an OpenVPN client after a successful authentication.
  • The session token is locked to the client IP address of the successful authentication (cannot be used from another IP).
  • When a session token and the current encryption key expire, the client will be disconnected until re-authentication.
  • Session tokens (and encryption keys) expire after a configurable amount of time, 24 hours by default.
  • Session tokens expire automatically when left unused for a while, 5 minutes by default.
  • Session tokens expire immediately when the user gracefully disconnects the VPN tunnel with Connect Client over XML-RPC.

It is important to note that auto-login type connection profiles do not use session-based authentication and are not bound by any of the above, and can therefore quite happily stay connected even beyond the default 24 hours time-limit on standard user-locked connection profiles. Also please note that the session tokens are used for server-locked profiles and user-locked profiles. In reality with a server-locked profile what will happen is that a web-based authentication session will take place first, after which a user-locked connection profile and a session token are provided. These are then used to start the actual OpenVPN tunnel connection. If you use a user-locked profile directly, the web-based authentication session is not done and authentication instead goes directly through the OpenVPN tunnel.

Change the session token inactivity timeout

By default the OpenVPN Access Server will give an authenticated user a session token that will expire in 5 minutes if it is not actively used. Or it will be expired immediately if the user is using the OpenVPN Connect Client, and chooses to disconnect, and the web based XML-RPC interface is reachable and the Connect Client can gracefully notify the server of the disconnect request.

When you start a connection to the OpenVPN Access Server with server-locked or user-locked connection profile, and you enter your credentials correctly, you will be given a session token and your OpenVPN tunnel will be established. If for example an hour later your Internet connection drops out for 1 minute for whatever reason (sleep mode, hibernate, bad WiFi signal, etcetera), the OpenVPN client can automatically reconnect to the server without having to ask you for credentials again. It will just use the session token itself. But if the connection drops offline for longer than 5 minutes, then your session token will be considered unused as there is no active OpenVPN tunnel using that token, and so the session token has become invalid, and the user must reauthenticate. This value can be adjusted with the setting below and is usually adjusted to make sessions survive a short sleep or hibernation period on laptops and desktop computers so the connection can automatically resume by itself when the system wakes up.

Change the inactivity timeout of the session tokens in seconds (default 300, 5 minutes):

./sacli --key "vpn.server.inactive_expire" --value <SECONDS> ConfigPut
./sacli start

Restore this value to the default:

./sacli --key "vpn.server.inactive_expire" --value "300" ConfigPut
./sacli start

If you set the value to a ridiculous setting like 99999999999 it effectively disables the session token inactivity expiration. This would not be advisable. If you need session to last forever, use auto-login type connection profiles instead, as they are not session-based connections and therefore not bound by any limitations on sessions.

Change the session token 24 hour timeout

A session token is also limited to a maximum period of time that it is valid even if it is currently actively in use. The default is 24 hours. Beyond that mark, the session token is made invalid. What happens then is that a connection that is using an expired session token will still be permitted to stay online as long as the encryption key they are using for the data channel is still the same. The moment this needs to be renegotiated, the session token is required again, and this would result in an automatic disconnect. By default the session token is set to a limit of 24 hours, and the key renegotiation is set to coincidence with this at 6 hours. So at the 24 hour mark, the session token expires, and the fourth encryption key also expires at the same time, and the connection then gets dropped. We are mentioning this specifically so that you take care to also adjust the key renegotiation setting to a value that coincides with the expiration time of the session token to ensure disconnects occur at the expected time. You can adjust the timeout with the following commands:

Set session token timeout in seconds (default 86400 seconds, 24 hours):

./sacli --key "vpn.server.session_expire" --value <SECONDS> ConfigPut
./sacli start

Restore this value to the default:

./sacli --key "vpn.server.session_expire" --value "86400" ConfigPut
./sacli start

If you set the value to a ridiculous setting like 99999999999 it effectively disables the session token expiration. This would not be advisable. If you need session to last forever, use auto-login type connection profiles instead, as they are not session-based connections and therefore not bound by any limitations on sessions.

Disable the client IP lock on a session token

By default a session token generated after a successful authentication attempt will be locked to the IP address of the original successful authentication. This is a security feature so that if somehow, through means unknown to us, your session token gets stolen or intercepted, it cannot be used from any other IP address than your own. In rare cases this can however lead to problems. For example if your Internet connection changes during the session. For example if you log on at the office, put your laptop to sleep mode, and then take your laptop home and open it up again, the Internet connection and thus the public IP address will be different, and then it cannot use the session token to automatically get you connected again. Aside from having to alter the inactivity timeout to make such a scenario possible, you would also have to remove the IP lock on the session tokens. The commands to do this are given below.

Disable the session token client IP lock:

./sacli --key "vpn.server.session_ip_lock" --value "false" ConfigPut
./sacli start

Restore this value to the default:

./sacli --key "vpn.server.session_ip_lock" --value "true" ConfigPut
./sacli start

In rare cases some company networks have a transparent proxy setup whereby web based traffic goes through a specific IP address, while other traffic goes through another. And in some situations, there are multiple public IP addresses available and your Internet traffic gets sent out over different IP addresses. In such a situation what can happen is that if your OpenVPN Connect Client is installed with a standard server-locked profile, that your authentication first goes over the web-based XML-RPC interface, where a session token is then generated and a user-locked profile is provided, but the subsequent OpenVPN tunnel connection is then established from another IP address. In such a case, the OpenVPN tunnel would be able to get to a point where it offers the session token, which is then not allowed because it doesn’t match the IP address of the original authentication request, and the user is then asked for credentials a second time. This time the authentication request goes through the user-locked OpenVPN tunnel connection, and then the connection finally establishes. In such a scenario, you are asked for authentication twice. If you recognize this phenomenon in your situation, this is one possible explanation, and disabling the session IP lock may help in your case.

Automatic client inactivity disconnect threshold

The Access Server can push a command to a connecting OpenVPN client with the instruction to gracefully disconnect when the connection is idle or inactive. The definition of this is determined by a threshold of amount of bytes transferred over a span of time. The idea behind this is that when the OpenVPN tunnel is not being actively used, the OpenVPN client automatically disconnects itself. This is a setting that can be set on the DEFAULT meta user so it applies to all users and groups, or it can be set on a group or a user. Since even when you do nothing, some traffic may still be transferred, we cannot tell you what your threshold should be set at because we do not know what your normal background bandwidth use is, your best best is to take a look at the Current Users overview in the Admin UI of the Access Server and look at the amount of data transferred to get an idea of what normal background bandwidth use is, and set the threshold just above that. The data is simply added up for both transmit/receive so if you upload 10 kilobytes and download 20 kilobytes the total is 30 kilobytes of traffic. So for example if the connection is not being actively used, and you see 50 kilobytes over a period of 5 minutes, then consider setting the threshold to 100 kilobytes over a period of 5 minutes. Then the connection will be dropped automatically if the connection is transferring less than 100 kilobytes in a 5 minute period. You will obviously need to experiment with this a bit to suit your situation.

  • prop_isec: number of seconds over which to sample bytes in/out
  • prop_ibytes: minimum amount of bytes over prop_isec to allow connection to continue

Disconnect when transmit/receive is below 100000 bytes over a period of 5 minutes:

./sacli --user <USER_OR_GROUP> --key "prop_isec" --value 300 UserPropPut
./sacli --user <USER_OR_GROUP> --key "prop_ibytes" --value 100000 UserPropPut
./sacli start

Please note that this setting does not override a standard user-locked session timeout. So if you have the default timeout of 24 hours set on a user-locked session, and you still transfer more than this threshold, and you reach the end of hour 24, you will still be disconnected – the session timeout takes priority over this activity threshold. Furthermore, there is nothing stopping the user from starting the connection again, and an automated system like in a router may just reconnect automatically when the connection goes down. It is up to the client to respect the disconnect, it may be ignored. And finally, we advise you that if you redirect all client Internet traffic through the VPN that you should keep in mind that this affects bandwidth use predictability considerably compared to simply using a split-tunnel setup where only specific traffic goes through the OpenVPN tunnel.