Skip to main content

Tutorial: Configure Client-Side Scripting in Access Server

Abstract

Learn how to configure client-side scripting in Access Server — push scripts to OpenVPN Connect clients on Windows, macOS, and Linux that run automatically on VPN connect or disconnect, set via the Admin Web UI or CLI, with working examples.

Overview

Access Server supports client-side scripting, which lets you push scripts to clients to automate actions when a VPN connection starts or ends.

For example, you can use:

  • An on-connect script to open a web page, map a network drive, or launch another workflow when the VPN connects.

  • An on-disconnect script to perform cleanup or other actions when the VPN disconnects.

With supported clients, scripts can use locally available interpreters and tools such as PowerShell, command-line shells, or Python when a Python interpreter is installed.

This tutorial shows you how to configure client-side scripting:

  1. For groups in the Admin Web UI.

  2. For individual users, groups, or default settings from the command line with sacli.

For supported platforms, security considerations, and additional use cases, refer to: Access Server Supports Client-side Scripting

Client-side scripting is commonly used to automate connection workflows in secure remote access deployments.

Important

The end-user must approve scripts pushed by the VPN server to the VPN client. The first time a script runs, the VPN client prompts the user to allow it. The user can choose to remember the selection so they don't need to approve the script each time it runs.

Prerequisites

  • An installed Access Server.

  • A supported VPN client.

  • Admin Web UI access or console access with root privileges.

  • A script appropriate for the operating system where it will run.

  • A locally available script interpreter required by your script.

Important

OpenVPN Connect version 3.x supports client-side script execution on Windows using locally installed interpreters such as cmd.exe and PowerShell.

OpenVPN Connect version 3.x can also run Python scripts on Windows and macOS when a separate Python interpreter is installed.

Step 1: Set up client-side scripts

From the Admin Web UI

Use the Admin Web UI to configure client-side scripting for a group.

Access Server supports:

  • Windows and macOS scripts.

  • Scripts that require user-level or administrator-level privileges.

  • Environment variables available to client-side scripts.

  1. Sign in to the Admin Web UI.

  2. Select Groups.

  3. Select the group name or edit icon for the group you want to configure.

  4. On the Group Settings page, select the Client Scripting tab.

  5. Enable the scripting options required for your environment:

    • Windows environment variables

    • Windows scripts

    • Mac environment variables

    • Mac scripts

  6. Enter the required variables, values, and scripts.

  7. Configure the scripts to run when the VPN connects or disconnects.

    • Connect scripts run after the client establishes a VPN connection.

    • Disconnect scripts run when the user disconnects the VPN.

    Tip

    OpenVPN Connect doesn't wait for an on-disconnect script to finish before closing the VPN tunnel.

  8. Select Save and Restart.

Note

Ensure that the users who should receive the client-side script are assigned to the configured group.

From the command line

The Admin Web UI configures client-side scripting at the group level.

Using the sacli command-line tool, you can configure client-side scripts for:

  • An individual user.

  • A group.

  • __DEFAULT__

The __DEFAULT__ keyword applies the settings as the baseline inherited by users and groups that don't have a more specific value configured.

  1. Connect to the console and get root privileges.

  2. Use the appropriate commands below, replacing <USER_OR_GROUP> with the user, group, or __DEFAULT__ value that should receive the script.

Configure an on-connect script

Use an on-connect script to run a client-side action after the VPN connection is established.

  • Windows

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.win.user.connect" --value_file "./windows-on-connect.txt" UserPropPut

  • macOS

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.mac.user.connect" --value_file "./macintosh-on-connect.txt" UserPropPut

  • Linux

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.linux.user.connect" --value_file "./linux-on-connect.txt" UserPropPut

  • All platforms

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.all.user.connect" --value_file "./all-on-connect.txt" UserPropPut

Remove an on-connect script

Removing a script at one level doesn't prevent inheritance from a higher-level configuration.

  • Windows

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.win.user.connect" UserPropDel

  • macOS

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.mac.user.connect" UserPropDel

  • Linux

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.linux.user.connect" UserPropDel

  • All platforms

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.all.user.connect" UserPropDel

Configure an on-disconnect script

Use an on-disconnect script to run an action when the user disconnects the VPN.

  • Windows

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.win.user.disconnect" --value_file "./windows-on-disconnect.txt" UserPropPut

  • macOS

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.mac.user.disconnect" --value_file "./macintosh-on-disconnect.txt" UserPropPut

  • Linux

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.linux.user.disconnect" --value_file "./linux-on-disconnect.txt" UserPropPut

  • All platforms

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.all.user.disconnect" --value_file "./all-on-disconnect.txt" UserPropPut

Remove an on-disconnect script

Removing a script at one level doesn't prevent inheritance from a higher-level configuration.

  • Windows

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.win.user.disconnect" UserPropDel

  • macOS

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.mac.user.disconnect" UserPropDel

  • Linux

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.linux.user.disconnect" UserPropDel

  • All platforms

    sacli --user <USER_OR_GROUP> --key "prop_cli.script.all.user.disconnect" UserPropDel

Step 2: Set a client-side environment variable

You can configure environment variables that Access Server pushes to the client and makes available to client-side scripts.

In the Admin Web UI, environment variables are configured for groups. From the command line, you can configure them for an individual user, group, or __DEFAULT__.

  1. Connect to the console and get root privileges.

  2. Set the client-side environment variable (example):

    sacli --user <USER_OR_GROUP> --key "prop_cli.script_env.win1.username2" --value "john3" UserPropPut

    1

    win applies the setting to Windows.

    2

    username is the environment variable name.

    3

    john is the value sent to the client.

    • To use another platform, replace win with mac, linux, or all.

    • To configure a different environment variable, replace username in the key. For example, to define a variable called myvariable: prop_cli.script_env.win.myvariable.

Remove an environment variable

  • To remove the environment variable from the example above, run:

    sacli --user <USER_OR_GROUP> --key "prop_cli.script_env.win.username" UserPropDel

Step 3: Test client-side scripts

The following examples provide simple scripts you can use to confirm that client-side scripting works. Configure the appropriate script using the Admin Web UI or command-line procedures above.

Example 1: Open a web page

Use this example to open the OpenVPN website when the VPN connection starts.

Windows

  1. Configure an on-connect script from the Admin Web UI or CLI as described in Step 1: Set up client-side scripts.

  2. Enter one of the following commands as your Windows User Connect Script.

    • To use CMD or PowerShell:

      start https://openvpn.net/

    • To use Python:

      python -m webbrowser -t "https://openvpn.net"

  3. Save the configuration.

  4. Ensure the user receives an updated connection profile.

  5. Connect to Access Server with the VPN client.

  6. Approve the script when prompted.

  7. Confirm that the OpenVPN website opens.

    Note

    Python scripts require a separately installed Python interpreter on the client.

macOS

  1. Configure an on-connect script from the Admin Web UI or CLI as described in Step 1: Set up client-side scripts.

  2. Enter one of the following commands as your User Connect Script.

    • To use Terminal:

      open https://openvpn.net/

    • To use Python:

      python3 -m webbrowser -t "https://openvpn.net"

  3. Save the configuration.

  4. Ensure the user receives an updated connection profile.

  5. Connect to Access Server with the VPN client.

  6. Approve the script when prompted.

  7. Confirm that the OpenVPN website opens.

    Note

    Python scripts require a separately installed Python interpreter on the client.

Example 2: Show a native dialog

Use this example to display a native dialog box titled Client Scripting with the message Working OK.

Windows

  1. Configure an on-connect script from the Admin Web UI or CLI as described in Step 1: Set up client-side scripts.

  2. Enter one of the following commands as your Windows User Connect Script.

    • To use PowerShell:

      powershell -c "Add-Type -A System.Windows.Forms;[System.Windows.Forms.MessageBox]::Show('Working OK.','Client Scripting')"

    • To use Python:

      python -c "import tkinter.messagebox as m,tkinter as t;r=t.Tk();r.withdraw();m.showinfo('Client Scripting','Working OK.')"

  3. Save the configuration.

  4. Ensure the user receives an updated connection profile.

  5. Connect to Access Server with the VPN client.

  6. Approve the script when prompted.

  7. Confirm that the Client Scripting dialog displays.

  8. Select OK.

    Note

    Python scripts require a separately installed Python interpreter on the client.

macOS

  1. Configure an on-connect script from the Admin Web UI or CLI as described in Step 1: Set up client-side scripts.

  2. Enter one of the following commands as your User Connect Script.

    • To use Terminal:

      osascript -e 'display dialog "Working OK." with title "Client Scripting" buttons {"OK"} default button "OK"'

    • To use Python:

      python3 -c "import tkinter.messagebox as m,tkinter as t;r=t.Tk();r.withdraw();m.showinfo('Client Scripting','Working OK.')"

  3. Save the configuration.

  4. Ensure the user receives an updated connection profile.

  5. Connect to Access Server with the VPN client.

  6. Approve the script when prompted.

  7. Confirm that the Client Scripting dialog displays.

  8. Select OK.

    Note

    Python scripts require a separately installed Python interpreter on the client.

See also

In this section: