Cloud Remote Access API

Overview

The diagram above illustrates the end-to-end integration between a user’s client and the corresponding external server via Cloud Remote Access (CRA). In such a setup, we distinguish between the following participants and components:

• A Cumulocity user, who wants to access an external service like a web server or SSH that is only reachable from a remote device.
• The client. This often is a shell in the Cumulocity UI; alternatively it can be a forwarding proxy like C8Y Cli or even a custom client application seeking access to the external service.
• The Cloud Remote Access (CRA) microservice at /service/remoteaccess.
• The Cumulocity Core platform (see also the Cumulocity OpenAPI Specification ).
• The device agent. A common open-source agent is thin-edge.io.
• An arbitrary external endpoint, typically a SSH, HTTP, Telnet or VNC server.

In the following, we now describe both how to implement a device-side agent and a client application that connects to the device-side agent via CRA.

Client implementation

Each device supporting Cloud Remote Access uses a fragment called c8y_RemoteAccessList to hold a list with the configured endpoints that can be accessed via this device.

An entry in the c8y_RemoteAccessList fragment holds the following fragments:

Example

"c8y_RemoteAccessList": [
        {
            "hostname": "localhost",
            "protocol": "PASSTHROUGH",
            "credentials": {
                "privateKey": null,
                "password": null,
                "certificate": null,
                "publicKey": null,
                "hostKey": null,
                "type": "NONE",
                "username": null
            },
            "port": 33123,
            "name": "My HTTP Echo Server",
            "id": "1"
        }
    ]

In the example above a local HTTP echo server is reachable from the device at http://localhost:33123. The configuration ID is 1. To connect a client application, the client must open a WebSocket to the following URL.

wss://<tenant domain>/service/remoteaccess/client/<device id>/configurations/<configuration id>

WebSocket HTTP headers

The Cloud Remote Access service uses the binary WebSocket subprotocol, regardless of which protocol is requested by the client. Hence, we recommend pinning the WebSocket subprotocol to binary using the Sec-WebSocket-Protocol header. Additionally, a valid authorization header is required, see Authentication in the Cumulocity OpenAPI Specification.

Sec-WebSocket-Protocol: binary 
Authorization: <auth header>

Sending and receiving traffic

Once the WebSocket connection is established, traffic for the endpoint can simply be sent to the WebSocket. Data from the endpoint can be consumed by reading from the WebSocket. To implement a local forwarding proxy, data from a local server socket must be written to the WebSocket and vice versa.

Device agent implementation

This section describes how to implement a device agent deployed on a gateway. The device agent is responsible for creating the device part of the tunnel between a TCP/IP connection at private network and the secure device WebSocket endpoint.

Supported operation

A device agent that implements an integration with Cloud Remote Access must consume c8y_RemoteAccessConnect operations. They are used to inform the device about tunnel connections it should establish. In order to mark your device being capable of handling them, it needs to include c8y_RemoteAccessConnect as a supported operation in its managed object:

"c8y_SupportedOperations" : [
...
"c8y_RemoteAccessConnect",
...
]

Connect operation

This operation is created when the application generates a connect request. The operation is then sent to the device agent, which establishes a connection between the WebSocket endpoint at the server and the local network endpoint.

Example of an c8y_RemoteAccessConnect operation:

{
  ...
  "c8y_RemoteAccessConnect": {
    "hostname": "10.0.0.67",
    "port": 5900,
    "connectionKey": "eb5e9d13-1caa-486b-bdda-130ca0d87df8"
  }
  ...
}

Connecting to a new endpoint

For each c8y_RemoteAccessConnect operation the device agent receives, it opens a TCP client socket to the provided hostname and port. Using the provided ConnectionKey the agent also securely connects to the WebSocket endpoint on server side.

The following steps need to be implemented by the device agent when it receives a c8y_RemoteAccessConnect operation.

• The device sets the operation status to EXECUTING.
• The device establishes a connection to the Cumulocity Cloud Remote Access WebSocket at the following URL:

  wss://<hostname>/service/remoteaccess/device/<connectionKey>
  

• The device sets up a TCP connection to the given hostname and port. Depending on the protocol (VNC, Telnet, SSH) the device will initiate a protocol-specific handshake. All data should be forwarded directly to the WebSocket endpoint (if already established).
• The operation status is set to SUCCESSFUL or FAILED based on the status of the previous steps.

Operating a connected endpoint

When both connections are established and fully functional the agent simply must forward all binary packets between the TCP connection and the WebSocket in both directions.

Disconnecting an endpoint

Whenever one of the connections is terminated (WebSocket or TCP) the device agent should consider the session as ended and should also terminate both connections associated with the tunnel.

Recommendations

It is highly recommended to implement a small buffer especially for bootstrapping when one connection is already functional while the other is not setup yet.