Set up EAP-TLS network from CLI

To set up an EAP-TLS network using the az sphere 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 az sphere 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 az sphere device certificate add command with the following parameters:

Parameter	Type	Description	Supported version
-c, --certificate	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:

az sphere device certificate add --certificate 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 az sphere device certificate add command with the following parameters:

Parameter	Type	Description	Supported version
-c, --certificate	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:

az sphere device certificate add --certificate 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 az sphere 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:

az sphere 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 az sphere device wifi reload-config command.

For example:

az sphere device wifi reload-config

Step 5. Verify that the network is connected

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

az sphere device wifi show-status

The az sphere 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:

az sphere device wifi show --id 1