OpenThings Framework - Request Proxy

This service forwards HTTP requests to IoT devices running the OTF firmware library, enabling them to be accessed over the internet. The service opens a websocket server that devices can connect to, and a webserver that handles HTTP requests. When an HTTP request is received, it will be sent to the appropriate device over the websocket connection and the response generated by the device will be sent as the response to the request.

Running the service

Prerequisites: Git, Node.js and NPM, MySQL server (if using MySQL authentication plugin)

# Clone the repo and install dependencies
git clone https://github.com/openthingsio/OTF-Request-Proxy.git
cd OTF-Request-Proxy
npm install
npm run build
# Make sure you configure the service (see below) before starting it
npm start

Configuration

You must pick an authentication plugin and configure it through some environment variables specific to each plugin. Additionally, there are some environment variables that can optionally be specified to override default values for global options:

Name	Description	Default
AUTHENTICATION_PLUGIN	Specifies which authentication plugin to use (see below).
HOST	The address that the HTTP and websocket servers should bind to.	127.0.0.1
HTTP_PORT	The port that the HTTP server should listen on.	3000
WEBSOCKET_PORT	The port that the websocket server should listen on.	8080

Authentication plugins

Devices will only be allowed to connect to the server if they provide a valid device key. There are 2 plugins available for validating device keys.

MySQLAuthenticationPlugin

This plugin queries a MySQL database and accepts device keys if a specified table contains a row with a matching value in the device_key column. The plugin can be configured through the following environment variables:

Name	Description	Example
AUTHENTICATION_PLUGIN	Must be set to MySQLAuthenticationPlugin to use this plugin.	MySQLAuthenticationPlugin
MYSQL_CONNECTION_URL	The URL of the MySQL server to connect to.	mysql://username:password@localhost:3306/otf
MYSQL_TABLE	The table in the database that stores valid device keys.	registered_devices

EnvironmentVariableAuthenticationPlugin

This plugin accepts device keys if they're specified in an environment variable. This is the suggested plugin to use if you're self-hosting the service for personal usage since it's the easiest to setup. The plugin can be configured through the following environment variables:

Name	Description	Example
AUTHENTICATION_PLUGIN	Must be set to EnvironmentVariableAuthenticationPlugin to use this plugin.	EnvironmentVariableAuthenticationPlugin
DEVICE_KEYS	A comma-separated list of valid device keys.	super_secret_key,0123456789ABCDEF,opendoor