Share via

Set up EAP-TLS network from CLI

  • Article

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.

To set up an EAP-TLS network using the azsphere command, you'll need the Root CA certificate for your network's RADIUS server and the client certificate for your device. The certificates must be in the .pem format in either PKCS1 or PKCS8 syntax. See Acquire and deploy certificates for EAP-TLS networks to learn about the certificates and where to get them. You can use OpenSSL to convert a PFX file to .pem format on Linux and on the Windows subsystem for Linux.

Caution

Because certificate IDs are system-wide, an azsphere command or a function call that adds a new certificate can overwrite a certificate that was added by an earlier command or function call, potentially causing network connection failures. We strongly recommend that you develop clear certificate update procedures and choose certificate IDs carefully.

See Certificate IDs for more information about how Azure Sphere uses certificate IDs.

Follow these steps to set up the network from the command line.

Step 1. Install the client certificate on the device

Install the client certificate information, including the public certificate and private key and password, if they're required on your network. Use the azsphere device certificate add command with the following parameters:

Parameter Type Description Supported version
-i, --cert-id String Specifies the identifier of the client certificate to add. A string identifier (up to 16 characters). Valid characters include uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), underscore (_), period (.), and hyphen (-). This identifier is also used in Wi-Fi configurations for EAP-TLS networks. Azure Sphere CLI
--cert-type String Specifies the type of client certificate to add. Enter "client". Azure Sphere CLI
--private-key-file String Specifies the path to a client private key certificate .pem file. Required when adding a certificate of type "client". You can provide a relative or absolute path. Azure Sphere CLI
-w, --private-key-password String Specifies an optional password for the client private key. The password is required when adding a client certificate private key that is encrypted. Azure Sphere CLI

For example:

azsphere device certificate add --cert-id myClientCert --cert-type client --public-key-file C:\User\MyCerts\MyClientCert.pem --private-key-file C:\User\MyCerts\privkey.pem --private-key-password 1234

To add a client certificate, both the public key file path and the private key file path are required on every network. You need the private key password only if the private key is encrypted; check with your network administrator.

Step 2. Install the Root CA certificate

Install the Root CA certificate for your RADIUS server, if your network requires mutual authentication. Use the azsphere device certificate add command with the following parameters:

Parameter Type Description Supported version
-i, --cert-id String Specifies the identifier of the root CA certificate to add. A string identifier (up to 16 characters). Valid characters include uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), underscore (_), period (.), and hyphen (-). This identifier is also used in Wi-Fi configurations for EAP-TLS networks. Azure Sphere CLI
--cert-type String Specifies the root CA certificate to add. Enter "rootca". Azure Sphere CLI
--private-key-file String Specifies the path to a rootca private key certificate .pem file. You can provide a relative or absolute path. Azure Sphere CLI

For example:

azsphere device certificate add --cert-id myRootCA --cert-type rootca --public-key-file C:User\MyCerts\MyRootCACert.pem

Step 3. Add the Wi-Fi network

After you install the certificates, add the EAP-TLS network on your device. Use the azsphere device wifi add command with the following parameters:

Parameter Type Description Supported version
-s, --ssid String Specifies the SSID of the network. Network SSIDs are case-sensitive. Azure Sphere CLI
--client-cert-id String [EAP-TLS] Specifies the identifier (up to 16 characters) that identifies the client certificate (containing both the public and private key). Required to set up an EAP-TLS network. Azure Sphere CLI
--client-id <user@domain> String [EAP-TLS] Specifies the ID recognized for authentication by the network's RADIUS server. Azure Sphere CLI
--config-name String Specifies a string (up to 16 characters) that specifies the name for the network configuration. Azure Sphere CLI
--root-ca-cert-id String [EAP-tLS] Specifies the identifier (up to 16 characters) that identifies the server's root CA certificate for EAP-TLS networks where the device authenticates the server. Azure Sphere CLI

For example:

azsphere device wifi add --ssid myEapTlsSsid --client-cert-id myClientCert --client-id user@domain.com --root-ca-cert-id myRootCA --config-name Network1

Step 4. Reload the network configuration

After you've installed the certificates and set up the EAP-TLS network, you need to reload the network configuration to ensure that it uses the most recent contents of the certificate store. Use the azsphere device wifi reload-config command.

For example:

azsphere device wifi reload-config

Step 5. Verify that the network is connected

To verify that your device has connected to the network, use the azsphere device wifi show-status command. Check the output to see that the network you created is listed, enabled, and connected.

azsphere device wifi show-status

The azsphere device wifi show command displays the details of a particular network. Use this command with the --id parameter to list the client certificate, root CA certificate, and client identity that are configured for the network. For example:

azsphere device wifi show --id 1

 azsphere device wifi show-status
 ----- ------------------ --------------- ------------- --------- ------- ------------- --------- ------------- -----------------
 SSID  ConfigurationState ConnectionState SecurityState Frequency Mode    KeyManagement WpaState  IpAddress     MacAddress
 ================================================================================================================================
 <value> enabled            connected       psk           2412      station WPA2-PSK      COMPLETED <value>      <value>
 ----- ------------------ --------------- ------------- --------- ------- ------------- --------- ------------- -----------------