What Is The Token URL? | OpenVPN Access Server (2024)

Introduction

A new feature introduced with Access Server 2.11 is the token URL. It is a method of providing a connection profile to a user’s OpenVPN client. This document provides details and some use cases.

Access Server token URL

A token URL contains an authentication token valid for a specific time and/or a number of usages and grants access to a connection profile. Accessing this token URL triggers the OpenVPN Connect VPN client to download and import the connection profile. The token URL has these characteristics:

1. An HTTPS URL with an authentication token for a connection profile.
2. The profile can be of user-locked, auto-login, or server-locked type.
3. A number of authentication token usages (defaults to 1 use).
4. Authentication token expiration time (defaults to 1 hour).
5. Prefixed with openvpn://import-profile/ to trigger client import process.

Supported software for client import process

When a token URL with openvpn://import-profile/ prefix is opened on a system with a supported OpenVPN client program installed, the user is offered the option to import the connection profile into the OpenVPN client. You need Access Server 2.11.0 or newer and OpenVPN Connect 3.3.6 or newer for this feature.

The process looks like this:

1. The user has OpenVPN Connect v3.3.6 or newer.
2. They click or open the token URL.
3. The browser asks to open OpenVPN Connect, and they click OK.
4. OpenVPN Connect asks to import the profile, and they click OK.
5. The connection profile can now be used in OpenVPN Connect.

Note: If your VPN client doesn’t support client import, you can still download and import the connection profile manually, as described below.

Manually download a profile using a token URL

You can download the connection profile using just the HTTPS URL without the openvpn://import-profile/ URL prefix. You can send such a URL to a user without needing to send username and password credentials. Opening the URL downloads the connection profile to the user’s device, and the user can import it into an OpenVPN client.

To manually download a profile with the token URL:

1. Create the token URL on the Access Server using either the Admin Web UI or CLI.
2. Copy the URL and remove the ‘openvpn://import-profile/’ prefix.
3. Use the resulting ‘https://’ URL to download the profile like any normal file.
4. Import the resulting .ovpn file into your VPN client.

Creating a token URL in the Admin Web UI

Follow these steps to create a token URL for an Access Server user:

1. Sign in to your Admin Web UI.
2. Click User Management > User Profiles.
3. Click New Token URL next to the desired user.
4. Select the profile type (Autologin is not available without permissions), the length of time the token is valid in hours, and click Create Token Download URL.
5. Copy the generated token URL and provide it to your user.

Manage token URLs on CLI

With the following commands, you can manage token URLs from the command line interface (CLI) with the following commands. Ensure you sign in to your Access Server with root privileges and run them from the /usr/local/openvpn_as/scripts/ directory.

The following provides commands for user, auto-login, and server-locked profiles. Refer to Understanding connection profiles on OpenVPN Access Server to read about the differences.

Generate a token URL to get a user profile:

./sacli --user <USER> AddProfileToken

The command adds a new token and provides the URL to download the profile, for example:

Added token, import URL openvpn://import-profile/https://123.456.78.90/rest/GetProfileViaToken?token=VKIn2qMCyGHgOjBVstqbh1foSNnsUBhK

When you paste the token URL into a browser, it pops up a message to open OpenVPN Connect. OpenVPN Connect confirms you want to import a profile from the provided domain. When confirmed, it imports the profile for your user.

Generate a token URL to get an auto-login user profile:

Run the appropriate command for your Access Server version.

Command for Access Server 2.12 and newer:

./sacli --user <USER> --profile_type="autologin" AddProfileToken

Command for Access Server 2.11.x and older:

./sacli --user <USER> --token_profile="autologin" AddProfileToken

If the user has auto-login permissions, the command adds a new token and provides the URL to download the profile.

If the user doesn’t have auto-login permissions, the command returns an error message, “need autologin”.

Generate a token URL to get a server-locked profile:

Run the appropriate command for your Access Server version.

Command for Access Server 2.12 and newer:

./sacli --user <USER> --profile_type="server-locked" AddProfileToken

Command for Access Server 2.11.x and older:

./sacli --user <USER> --token_profile="server-locked" AddProfileToken

The command adds a new token and provides the URL to download the server-locked profile.

Generate a token URL with a specific expiration time:

./sacli --user <USER> --token_expire="1200" AddProfileToken

The command adds a new token with an expiration of 1200 minutes from creation and provides the URL to download the profile.

If a user tries to enter the URL in their browser after the expiration, they will still be prompted by the browser to open OpenVPN Connect and import the profile but then receive an error. You can find an error message in your log database that the token isn’t found in the database.

Generate a token URL with more than one usage:

./sacli --user <USER> --token_usage_count="3" AddProfileToken

The command adds a new token with three allowable usages and provides the URL to download the profile.

Each time a user downloads a profile with the provided URL, the usage number counts down until it reaches zero, and you can no longer use the token to download a profile.

List the current profile tokens:

sacli ListProfileTokens

You should see any newly generated tokens in the list. The list includes the token, type, usages, expiration, and username — only currently valid tokens display. Once a token expires, you must issue a new token, and the expired token won’t be in the list anymore.

Delete a token URL:

For the following command, you must copy the generated token from the list of current profile tokens and paste it as the <token>.

./sacli --id <token> DeleteProfileToken

Troubleshooting

AUTH ERROR: token not found in DB

If you try to use a token URL after it’s expired, you’ll receive an auth error message that the token isn’t in the database. Once a token URL expires, it’s no longer saved in ListPofileTokens.

ERROR: NEED_AUTOLOGIN — user lacks autologin privilege

You can’t generate an auto-login profile for a user if they don’t have the privilege. To grant that, sign in to the Admin Web UI, click User Management > User Permissions, and click Allow Autologin for the user. Ensure you save and update the running server.