Connect Azure Sphere through a proxy server
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
You can configure an Azure Sphere device to connect to the Internet through a proxy server using the Azure Sphere SDK Application Libraries (Applibs) or the CLI. When this feature is enabled all device traffic flows through the proxy. The device can be configured to identify the proxy server to be used, the type of server, and the authentication method.
Only HTTP proxies are currently supported.
Authentication methods
The following authentication methods are supported:
- Basic: Prompts the user for a user name and password to authenticate the connection.
- Anonymous: Allows users to connect anonymously so that user name and password are not required when using the proxy server connection.
Proxy configuration using the CLI
The following commands manage proxy address use for network connection. For more information, see azsphere device network proxy.
| Operation | Description |
|---|---|
| proxy apply | Configures the network proxy on the attached device. |
| proxy delete | Deletes the proxy connection on the attached device. |
| proxy show | Shows proxy connection on the attached device. |
Proxy configuration using Applibs
To set up proxy configuration, your application must use the Applibs networking API, which includes support for getting and setting proxy configuration properties.
Include this header file in your application:
#include <applibs/networking.h>
If you are using cURL in your application and connecting to the Internet through a proxy server, you must also include this header file:
#include <applibs/networking_curl.h>
For more information about using cURL, see Connect to web services.
Supported Applibs for proxy configuration
The following AppLibs are supported:
- Networking_Curl_SetDefaultProxy
- Networking_Proxy_Create
- Networking_Proxy_Destroy
- Networking_Proxy_Apply
- Networking_Proxy_Get
- Networking_Proxy_SetProxyOptions
- Networking_Proxy_SetProxyAddress
- Networking_Proxy_SetAnonymousAuthentication
- Networking_Proxy_SetBasicAuthentication
- Networking_Proxy_SetProxyNoProxyAddresses
- Networking_Proxy_GetProxyOptions
- Networking_Proxy_GetProxyAddress
- Networking_Proxy_GetProxyPort
- Networking_Proxy_GetProxyType
- Networking_Proxy_GetProxyUsername
- Networking_Proxy_GetProxyPassword
- Networking_Proxy_GetAuthType
- Networking_Proxy_GetNoProxyAddresses
- Networking_Proxy_GetProxyStatus
- Networking_ProxyConfig
- Networking_ProxyOptions
- Networking_ProxyType
- Networking_ProxyAuthType
- Networking_ProxyStatus
Application manifest requirements
The application manifest must include the NetworkConfig or the ReadNetworkProxyConfig capability. The capability determines the degree of access your application has to the proxy settings.
The NetworkConfig capability grants full access to all network configuration settings. It allows your application to configure, retrieve, and enable or disable proxy settings.
"Capabilities": {
"NetworkConfig": true
}
The ReadNetworkProxyConfig capability only allows your application to retrieve proxy settings. This capability is used for applications that are denied general access to network settings, but require proxy configuration information.
"Capabilities": {
"ReadNetworkProxyConfig": true
}
Use MQTT to connect to Azure IoT Hub
Azure IoT applications use TCP/IP-based MQTT to connect to an Azure IoT hub. You must configure your application to use MQTT over WebSockets so that traffic is properly redirected through the proxy.
You can configure your application to communicate with an IoT Hub directly, or use the Azure Device Provisioning Services (DPS):
To configure your application to communicate with an IoT hub directly, use the proxy sample code in the READMEStartWithIoTHub.md sample and modify it as described in Connect to AzureIoT hub directly.
To configure your application to use Azure DPS, use the proxy sample code in the READMEAddDPS or READMEStartWithIoTCentral sample and modify it as described in Connect via Azure IoT Hub device provisioning service.
For more information on adding proxy support, see READMEAddWebProxy.md.
Samples
The proxy code snippets demonstrate the following:
- The Configure Proxy Settings code snippet demonstrates how to configure the proxy settings on an Azure Sphere device.
- The Get Proxy Settings code snippet demonstrates how to retrieve the proxy settings on an Azure Sphere device.
- The Enable/Disable Configured Proxy code snippet demonstrates how to enable/disable an already configured proxy on an Azure Sphere device.
The HTTPS samples demonstrate using the HTTPS_Curl_Easy and HTTPS_Curl_Multi APIs to fetch content over HTTPS. By default, they configure the cURL handle to use a proxy.
The AzureIoT sample contains instructions and code for adding web proxy support to the sample.