Configure local proxy for devices that use web proxy
You can use local proxy on AWS IoT devices to communicate with AWS IoT secure
tunneling APIs. The local proxy transmits data sent by the device application using
secure tunneling over a WebSocket secure connection. The local proxy can work in
source
or destination
mode. In source
mode, it runs on the same device or network that initiates the TCP connection. In
destination
mode, the local proxy runs on the remote device, along
with the destination application. For more information, see Local proxy.
The local proxy needs to connect directly to the internet to use AWS IoT secure tunneling. For a long-lived TCP connection with secure tunneling, the local proxy upgrades the HTTPS request to establish a WebSockets connection to one of the secure tunneling device connection endpoints.
If your devices are in a network
that
uses a web proxy, the web proxy can
intercept the connections before forwarding them to the internet. To establish a
long-lived connection to the secure tunneling device connection endpoints, configure
your local proxy to use the web proxy as described in the websocket
specification
Note
The AWS IoT Device Client doesn't support devices that use a web proxy. To work with the web proxy, you'll need to use a local proxy and configure it to work with a web proxy as described below.
The following steps show how the local proxy works with a web proxy.
-
The local proxy sends an HTTP
CONNECT
request to the web proxy that contains the remote address of the secure tunneling service, along with the web proxy authentication information. -
The web proxy will then create a long-lived connection to the remote secure tunneling endpoints.
-
The TCP connection is established and the local proxy will now work in both source and destination modes for data transmission.
To complete this procedure, perform the following steps.
Build the local proxy
Open the local proxy source code
Configure your web proxy
The local proxy relies on the HTTP tunneling mechanism described by the HTTP/1.1
specificationCONNECT
method.
How you configure your web proxy depends on the web proxy you're using and the web proxy version. To make sure you configure the web proxy correctly, check your web proxy's documentation.
To configure your web proxy, first identify your web proxy URL and confirm whether your web proxy supports HTTP tunneling. The web proxy URL will be used later when you configure and start the local proxy.
-
Identify your web proxy URL
Your web proxy URL will be in the following format.
protocol
://web_proxy_host_domain
:web_proxy_port
AWS IoT secure tunneling supports only basic authentication for web proxy. To use basic authentication, you must specify the
username
andpassword
as part of the web proxy URL. The web proxy URL will be in the following format.protocol
://username
:password
@web_proxy_host_domain
:web_proxy_port
-
protocol
can behttp
orhttps
. We recommend that you usehttps
. -
web_proxy_host_domain
is the IP address of your web proxy or a DNS name that resolves to the IP address of your web proxy. -
web_proxy_port
is the port on which the web proxy is listening. -
The web proxy uses this
username
andpassword
to authenticate the request.
-
-
Test your web proxy URL
To confirm whether your web proxy supports TCP tunneling, use a
curl
command and make sure that you get a2xx
or a3xx
response.For example, if your web proxy URL is
https://server.com:1235
, use aproxy-insecure
flag with thecurl
command because the web proxy might rely on a self-signed certificate.export HTTPS_PROXY=https:
//server.com:1235
curl -I https://aws.amazon.com --proxy-insecureIf your web proxy URL has a
http
port (for example,http://server.com:1234
), you don't have to use theproxy-insecure
flag.export HTTPS_PROXY=http:
//server.com:1234
curl -I https://aws.amazon.com
Configure and start the local proxy
To configure the local proxy to use a web proxy, you must configure the
HTTPS_PROXY
environment variable with either the DNS domain
names or the IP addresses and port numbers that your web proxy uses.
After you've configured the local proxy, you can use the local proxy as
explained in this README
Note
Your environment variable declaration is case sensitive. We recommend that you define each variable once using either all uppercase or all lowercase letters. The following examples show the environment variable declared in uppercase letters. If the same variable is specified using both uppercase and lowercase letters, the variable specified using lowercase letters takes precedence.
The following commands show how to configure the local proxy that is running on your destination to use the web proxy and start the local proxy.
-
AWSIOT_TUNNEL_ACCESS_TOKEN
: This variable holds the client access token (CAT) for the destination. -
HTTPS_PROXY
: This variable holds the web proxy URL or the IP address for configuring the local proxy.
The commands shown in the following examples depend on the operating system that you use and whether the web proxy is listening on an HTTP or an HTTPS port.
Web proxy listening on an HTTP port
If your web proxy is listening on an HTTP port, you can provide the web
proxy URL or IP address for the HTTPS_PROXY
variable.
Web proxy listening on an HTTPS port
Run the following commands if your web proxy is listening on an HTTPS port.
Note
If you're using a self-signed certificate for the web proxy or if
you're running the local proxy on an OS that doesn't have native OpenSSL
support and default configurations, you'll have to set up your web proxy
certificates as described in the Certificate setup
The following commands will look similar to how you configured your web proxy for an HTTP proxy, with the exception that you'll also specify the path to the certificate files that you installed as described previously.
Example command and output
The following shows an example of a command that you run on a Linux OS and
the corresponding output. The example shows a web proxy that's listening on
an HTTP port and how the local proxy can be configured to use the web proxy
in both source
and destination
modes. Before you
can run these commands, you must have already opened a tunnel and obtained
the client access tokens for the source and destination. You must have also
built the local proxy and configured your web proxy as described
previously.
Here's an overview of the steps after you start the local proxy. The local proxy:
-
Identifies the web proxy URL so that it can use the URL to connect to the proxy server.
-
Establishes a TCP connection with the web proxy.
-
Sends an HTTP
CONNECT
request to the web proxy and waits for theHTTP/1.1 200
response, which indicates that connection has been established. -
Upgrades the HTTPS protocol to WebSockets to establish a long-lived connection.
-
Starts transmitting data through the connection to the secure tunneling device endpoints.
Note
The following commands used in the examples use the
verbosity
flag to illustrate an overview of the
different steps described previously after you run the local proxy. We
recommend that you use this flag only for testing purposes.
Running local proxy in source mode
The following commands show how to run the local proxy in source mode.
export AWSIOT_TUNNEL_ACCESS_TOKEN=
${access_token}
export HTTPS_PROXY=http:username
:password
@10.15.10.25:1234
./localproxy -s 5555 -v 5 -r us-west-2
The following shows a sample output of running the local proxy in
source
mode.
... Parsed basic auth credentials for the URL Found Web proxy information in the environment variables, will use it to connect via the proxy. ... Starting proxy in source mode Attempting to establish web socket connection with endpoint wss://data.tunneling.iot.us-west-2.amazonaws.com:443 Resolved Web proxy IP: 10.10.0.11 Connected successfully with Web Proxy Successfully sent HTTP CONNECT to the Web proxy Full response from the Web proxy: HTTP/1.1 200 Connection established TCP tunnel established successfully Connected successfully with proxy server Successfully completed SSL handshake with proxy server Web socket session ID: 0a109afffee745f5-00001341-000b8138-cc6c878d80e8adb0-f186064b Web socket subprotocol selected: aws.iot.securetunneling-2.0 Successfully established websocket connection with proxy server: wss://data.tunneling.iot.us-west-2.amazonaws.com:443 Seting up web socket pings for every 5000 milliseconds Scheduled next read: ... Starting web socket read loop continue reading... Resolved bind IP: 127.0.0.1 Listening for new connection on port 5555
Running local proxy in destination mode
The following commands show how to run the local proxy in destination mode.
export AWSIOT_TUNNEL_ACCESS_TOKEN=
${access_token}
export HTTPS_PROXY=http:username
:password
@10.15.10.25:1234
./localproxy -d 22 -v 5 -r us-west-2
The following shows a sample output of running the local proxy in
destination
mode.
... Parsed basic auth credentials for the URL Found Web proxy information in the environment variables, will use it to connect via the proxy. ... Starting proxy in destination mode Attempting to establish web socket connection with endpoint wss://data.tunneling.iot.us-west-2.amazonaws.com:443 Resolved Web proxy IP: 10.10.0.1 Connected successfully with Web Proxy Successfully sent HTTP CONNECT to the Web proxy Full response from the Web proxy: HTTP/1.1 200 Connection established TCP tunnel established successfully Connected successfully with proxy server Successfully completed SSL handshake with proxy server Web socket session ID: 06717bfffed3fd05-00001355-000b8315-da3109a85da804dd-24c3d10d Web socket subprotocol selected: aws.iot.securetunneling-2.0 Successfully established websocket connection with proxy server: wss://data.tunneling.iot.us-west-2.amazonaws.com:443 Seting up web socket pings for every 5000 milliseconds Scheduled next read: ... Starting web socket read loop continue reading...