Tunneling with Pelion Direct Connect Client

Pelion Direct Connect Client acts as a local TCP server that accepts local TCP connections and establishes corresponding websocket connections to the Pelion Edge tunneling service through a TCP connection on the Pelion cloud.

This diagram shows Pelion Direct Connect Client has a local TCP server ready to accept any TCP-based connection locally. Pelion Direct Connect Client establishes the websocket connection to the exposed websocket API on Pelion Device Management's cloud per TCP-based connection and proxies the bytes back and forth between the local TCP connections and cloud websocket connections.

Websocket API

For details about the exposed websocket API, please see the Swagger documentation.

Configuration of parameters

Using Pelion Direct Connect Client

1. Deploy a TCP-based container service to the gateway.

2. Install Go.

3. Build the client by running:

   $ go build
   

4. Launch pelion-direct-connect-client locally by providing parameters - listen-uri, cloud-uri and api-key:

   $ ./pelion-direct-connect-client -listen-uri=<LOCAL_ADDRESS> -cloud-uri=<CLOUD_URI> -api-key=<API_KEY>
   

5. Open a browser by pointing to the address with the above listen-uri.

Note: The browser is one of the example local clients and the choice of local client depends on the container service deployed on the gateway.

Application access management with JWT keys

JSON Web Token (JWT) keys are one of two types of keys you can use to manage an application's access to Pelion Device Management.

Similarly, you can use a JWT key to manage a cloud application's access with Pelion Edge.

If you use the API endpoint /v3/devices/{id}/services/{address}/connection for tunneling, you can use a JWT key to manage access to a cloud application. Creation of the JWT is up to the client, but a public certificate that signed the JWT needs to be uploaded into Pelion Device Management.

As with Pelion Device Management, the steps to manage access to your application using JWT keys in Pelion Edge are:

1. Create a verification key.
2. Upload the verification key.
3. Create the JWT key.
4. Deploy the JWT key.

An example flow is provided below.

Example flow

1. Create a private key-public key certificate pair:

   $ openssl req -newkey rsa:2048 -nodes -keyout private.key -x509 -days 365 -out public.crt

2. Upload the public certificate to the Pelion Device Management verification keys API with an administrator application access key created from Pelion Device Management:

   curl -0 -v -X POST https://api.us-east-1.mbedcloud.com/v3/applications/{application-id}/verification-keys \
   2-H 'Authorization: Bearer ak_2MD...' \
   3-H 'content-type: application/json' \
   4--data-binary @- << EOF
   5{
   6    "name": "JWT-test",
   7    "certificate": "-----BEGIN CERTIFICATE-----
   8    ...
   9    -----END CERTIFICATE-----"
   10}
   11EOF
   

3. Create a JWT in RSA SHA-256 format.

   1. Sign it with the private key and certificate, which you can do with jwt.io.

      The supported signing algorithms are:

      • RS256.
      • RS384.
      • RS512.
      • ES256.
      • ES384.
      • ES512.

   2. Make sure the exp expiration claim exists and is valid.

4. Access /v3/devices/{id}/services/{address}/connection with a header "X-Application-ID" corresponding to the same {application-id} (where the verification keys are created), and set Authorization header with value Bearer {JWT}. Using JWT as a bearer token without this header causes the client not to be authenticated. {id} is the device ID or gateway ID, and {address} is the tunnel_ip:tunnel_port format.

JWT claims

Required claim

• exp: JWT expiration date in number of seconds since Epoch format.

Optional claims

The JWT key can specify one or all of the claims below to restrict access to the application:

• pelion.edge.tunnel.device_id: The only device ID that can be used to open the tunnel, if specified.
• pelion.edge.tunnel.ip: The only IP that can connect over the tunnel, if specified.
• pelion.edge.tunnel.port: The only port that can connect over the tunnel, if specified.