Access Server API

Abstract

The Access Server REST API allows programmatic download of OpenVPN connection profiles.

Overview

The Access Server REST API allows programmatic download of OpenVPN connection profiles. This is the same API used by OpenVPN Connect and is compatible with other clients and tools.

  • Supports userlogin and autologin profiles.

  • Uses HTTP Basic Authentication.

  • Returns connection profiles as .ovpn files.

  • Can be accessed via command-line tools like curl.

Base URL

https://<ACCESS_SERVER>/rest/<METHOD>

Prerequisites

  • Access Server is deployed and accessible.

  • XML-RPC/REST API is enabled under: Admin Web UI > Configuration > CWS Settings.

  • A valid username and password for an Access Server user.

  • Access Server’s HTTPS port is typically 443, unless configured otherwise.

Authentication

The API uses HTTP Basic Authentication. Include the username:password pair in your request header or via the -u option in curl.

TLS certificate validation is required. If using a self-signed certificate, pass it with --cacert. Avoid using -k unless testing.

Example 1. Request

If your credentials contain special characters (e.g., @), wrap them in single quotes.

curl -u 'username:password' https://<ACCESS_SERVER>/rest/<METHOD>

Profile Parameters

Parameter

Description

USERNAME

The username of the Access Server user for whom the connection profile is requested.

PASSWORD

The specified user's password.

CWS_PORT

(Optional) The port on which the client web server listens. This is set to 443 by default, but you can specify a different port if needed.

tls-cryptv2

Indicates support for TLS Crypt V2, a more secure encryption mechanism for protecting control channel traffic in OpenVPN.

deviceID

Specify the device for which the connection profile is being generated. (It helps associate a particular connection profile with a specific device, ensuring the generated profile corresponds to the right device.)

Endpoints

GetUserlogin

Retrieves a user-based OpenVPN connection profile (requires username/password at connection time).

Optional query parameters

  • tls-cryptv2=1: Enables TLS Crypt V2 (recommended for enhanced security).

  • action=import: Triggers direct import in some clients.

Optional headers (to prevent multiple 2FA prompts)

VPN-Session-User: <base64_encoded_user>

VPN-Session-Token: <base64_encoded_token>

Success response

  • Content-Type: application/x-openvpn-profile

Error response:

  • Content-Type: text/xml

Request

curl -u 'username:password' "https://<ACCESS_SERVER>/rest/GetUserlogin?tls-cryptv2=1&action=import"

GetAutologin

Retrieves a client-certificate-based profile suitable for unattended clients (no password prompt).

Important

Ensure the user has autologin permission enabled in the Admin Web UI under User Permissions.

Success response

  • Content-Type: application/x-openvpn-profile

Error response

  • Content-Type: text/xml

Request

curl -u 'username:password' https://<ACCESS_SERVER>/rest/GetAutologin

Challenge/Response Authentication

Overview

The REST API supports challenge/response authentication for cases requiring additional user verification. This method is used when the server needs to verify a user's identity through a challenge that the user must respond to before the requested OpenVPN configuration file can be returned.

Here's an overview of how the process works:

  1. The client sends an authentication request with the user's credentials (username and password) to the Access Server:

    curl -u test:mypass https://ACCESS_SERVER/rest/GetUserlogin

  2. When additional verification is required (e.g., a Turing test), the server responds with a challenge message instead of the requested configuration file. This response includes the challenge details, formatted as CRV1.

  3. The client presents the challenge to the user (e.g., "What is 1 x 3?"). The user enters the response.

  4. The client then resubmits the request with the challenge response in the format specified by the server.

  5. If the server validates the response, the requested connection profile is returned.

Challenge/response authentication details

  1. Receiving a challenge: When the client requests a connection profile (e.g., GetUserlogin), but the server needs further validation, it responds with a challenge.

  2. Understanding the challenge message: The challenge message follows the format CRV1: <flags>:<state_id>:<username_base64>:<challenge_text>, where:

    • flags: A series of optional, comma-separate flags specifying additional behavior:

      • E: Echo the response as the user types it.

      • R: Indicates that a response is required.

    • state_id: An opaque string to be returned along with the response.

    • username_base64: The base64-encoded username of the user requesting the connection profile.

    • challenge_text: The challenge text (e.g., the Turing question) presented to the user.

  3. Responding to the challenge: After displaying the challenge text to the user, the client waits for the user's response. If the R flag is present, the response is required. The response may be an empty string if the flag isn't present.

  4. Resubmitting the response: Once the user responds, the client resubmits the request to the server.

  5. Validating the response: If the server successfully validates the response (e.g., '3' as the answer to the Turing test), it returns the requested connection profile, and the client can proceed with the VPN connection.

Example 2. Example Challenge
<Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>CRV1:R,E:miwN39AlF4k40Fd8X8r9j74FuOoaJKJM:dGVzdA==:Turing test: what is 1 x 3? (9007)</Message>
</Error>
Example 3. Example resubmit with the challenge response
curl -u "test:CRV1::miwN39AlF4k40Fd8X8r9j74FuOoaJKJM::3" https://ACCESS_SERVER/rest/GetUserlogin

Here, the username is decoded from the username_base64, and the state_id and response_text (the user's answer) are appended.

Example workflow

  1. Initial request:

    curl -u test:mypass https://ACCESS_SERVER/rest/GetUserlogin

  2. Server response (challenge):

    <Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>CRV1:R,E:miwN39AlF4k40Fd8X8r9j74FuOoaJKJM:dGVzdA==:Turing test: what is 1 x 3? (9007)</Message>
</Error>

  3. The user responds to the challenge question, "What is 1x3?" with the answer 3.

  4. The client resubmits the request:

    curl -u "test:CRV1::miwN39AlF4k40Fd8X8r9j74FuOoaJKJM::3" https://ACCESS_SERVER/rest/GetUserlogin

  5. The server verifies the response and returns the connection profile.

Certificate Verification

When using curl, ensure that the Access Server web server employs a trusted certificate, such as a commercial web certificate. If you use a self-signed CA, ensure this certificate is available to curl or any HTTPS client you're using.

The Access Server web CA certificate can be found at /usr/local/openvpn_as/etc/web-ssl/ca.crt.

You can specify it with a curl option:

--cacert ca.crt

Caution

While you can disable web server certificate verification using the -k option, we discourage this practice for security reasons.

Error Handling

The REST API will return errors in an XML format (in contrast to typical REST JSON responses). These are some common error responses:

  • Authentication failed (invalid username/password):

    <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>AUTH_FAILED: Server Agent XML method requires authentication (9007)</Message>
</Error>

  • Permission denied (user lacks autologin privileges):

    <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Type>Internal Server Error</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>NEED_AUTOLOGIN: User 'USERNAME' lacks autologin privilege (9000)</Message>
</Error>

  • User not enrolled for authentication:

    <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Type>Access denied</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>You must enroll this user in Authenticator first before you are allowed to retrieve a connection profile. (9008)</Message>
</Error>

  • WebAuth fallback: An error will occur if the server is configured for web-based authentication (SAML) but a user attempts to use the REST API instead. The client should offer the option to proceed with SAML authentication.

    <Error>
  <Type>Authorization Required</Type>
  <Synopsis>REST method failed</Synopsis>
  <Message>Ovpn-WebAuth: providername,flags</Message>
</Error>