VPN Connection Profile API

Introduction

Overview

In this document, we will describe how VPN connection profile configuration can be obtained from the Acreto Ecosystem using the API.

On a technical level, this process consists of the following steps:

  1. IT Admin geneates the device token
  2. IT Admin delivers the device token to the End-User through a secure channel, for example using invitation feature
  3. End-User downloads the VPN Connection Profile Configuration using the device token
  4. End-User uses downloaded VPN Connection Profile Configuration to establish sa ecure connection to Acreto Ecosystem

Prerequisites

Before you start, you will need to:

You should also complete the API Quick start.

Environment variables

All examples in this document are constructed as curl commands. For convenience, the following environment variables are used in these examples:

  • ENDPOINT=https://api-is-rock-solid.acreto.net/v2
  • TOKEN - access token retrieved from /auth/login endpoint
  • customer_uuid - ID of customer (organization) account
  • ecosystem_uuid - ID of the ecosystem to be used
  • DEVICE_TOKEN - device token is needed to obtain VPN connection profile
  • user_uuid - user identifier of the user for which we generate VPN connection profile, which can be retrieved from the GET ​/customers​/{customer_uuid}​/ecosystems​/{ecosystem_uuid}​/users endpoint
  • device_uid - Thing identifier of a thing for which we generate VPN connection profile; can be retrieved from the GET /customers/{customerUUID}/ecosystems/{ecosystemUUID}/devices endpoint

VPN Connection Profile Configuration format

VPN connection profile configuration is a valid OpenVPN config file, and can be used to establish an OpenVPN connection to the Ecosystem.

Things vs Users

Acreto Ecosystem allows the generation of 2 types of VPN connection profiles:

  • Thing, which is authenticated based on a secret key contained inside the VPN Connection Profile Configuration (“something you have” authentication factor)
  • User, which is authenticated based on username and password combination provided by the user during connection (“something you know” authentication factor)

Access and device tokens

Note there are two types of tokens: TOKEN, which is used to authenticate access requests and should be generated based on IT Admin’s username and password, and DEVICE_TOKEN, which can be shared with End Users and used only to download the VPN connection profile.

Device token generation

User

To generate a device token for a user, you should send a POST request to /customers/{customer_uuid}/ecosystems/{ecosystem_uuid}/users/{user_uuid}/token endpoint. This endpoint takes only one optional argument, which is time to live, (ttl) in seconds. If omitted, it will be set to a default value.

Note that ttl is subject to security policies within the Acreto platform, and it is not guaranteed that generated token will have ttl provided in the request. We recommend omitting this parameter and using the default value.

Request:

curl -X POST -d '{}' -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN"  ${ENDPOINT}/customers/${customer_uuid}/ecosystems/${ecosystem_uuid}/users/${user_uuid}/token|jq .

Response:

{"token":"s.iibxqytafX1YvSRk9q7HSaYE"}

Save the value of “token” key into DEVICE_TOKEN variable for future reference:

DEVICE_TOKEN="s.iibxqytafX1YvSRk9q7HSaYE"

Thing

To generate a device token for a Thing, you should send a POST request to /customers/{customer_uuid}/ecosystems/{ecosystem_uuid}/devices/{device_uuid}/token endpoint. This endpoint takes only one optional argument, which is time to live, (ttl) in seconds. If omitted, it will be set to a default value.

Note that ttl is subject to security policies within the Acreto platform, and it is not guaranteed that generated token will have ttl provided in the request. We recommend omitting this parameter and using the default value.

Request:

curl -X POST -d '{}' -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN"  ${ENDPOINT}/customers/${customer_uuid}/ecosystems/${ecosystem_uuid}/devices/${device_uuid}/token|jq .

Response:

{"token":"s.iibxqytafX1YvSRk9q7HSaYE"}

Save the value of “token” key into DEVICE_TOKEN variable for future reference:

DEVICE_TOKEN="s.iibxqytafX1YvSRk9q7HSaYE"

Retrieve VPN Connection Profile Configuration

To retrieve VPN Connection Profile configuration, End-User should send GET request to endpoint /tlsvpn/config/{platform}?_token={DEVICE_TOKEN}. {platform} should be openvpn-udp (other options are not implemented at the time of writing).

Request:

curl ${ENDPOINT}/tlsvpn/config/openvpn-udp?_token=${DEVICE_TOKEN}

Response:

In response, VPN Connection Profile Configuration is returned as a file of type application/x-openvpn-profile.

Note that the End-User should correctly detect and interpret error codes; in particular, if the DEVICE_TOKEN is invalid or expired, the request will return HTTP 403 status.

Summary

In this document, we went through the process of retrieving VPN Connection Profile Configuration from Acreto API.