Skip to content

Commit 18e1c6f

Browse files
committed
fix: update CA handling info in Azure IoT Hub migration guide
1 parent 1f0f4e7 commit 18e1c6f

File tree

1 file changed

+38
-1
lines changed

1 file changed

+38
-1
lines changed

en_US/migration/migrate-from-azure-iot-hub.md

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,35 @@ The connection should fail without a client certificate.
144144

145145
The final phase is to update device client code to connect to EMQX instead of Azure IoT Hub.
146146

147+
### Prepare EMQX Server CA Certificate
148+
149+
Before updating device code, you need to obtain the EMQX server's CA certificate. This is the CA that signed the EMQX server's TLS certificate.
150+
151+
**For self-signed EMQX server certificates**, you must add the server CA to your device's trusted certificate store:
152+
153+
**On Linux**:
154+
```bash
155+
# Copy CA to system trust store
156+
sudo cp emqx-server-ca.pem /usr/local/share/ca-certificates/emqx-ca.crt
157+
sudo update-ca-certificates
158+
```
159+
160+
**On macOS**:
161+
```bash
162+
# Add to system keychain
163+
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain emqx-server-ca.pem
164+
```
165+
166+
**On Windows**:
167+
```powershell
168+
# Import certificate to Trusted Root CA store
169+
Import-Certificate -FilePath emqx-server-ca.pem -CertStoreLocation Cert:\LocalMachine\Root
170+
```
171+
172+
::: tip
173+
If your EMQX server uses a certificate from a public CA (like Let's Encrypt), this step is not needed as the CA is already trusted by the system.
174+
:::
175+
147176
### Update Device Client Code
148177

149178
The Azure IoT SDK for Python (and other languages) supports connecting to custom MQTT brokers through the `server_verification_cert` and custom `hostname` parameters. This allows for minimal code changes.
@@ -159,19 +188,27 @@ x509 = X509(
159188
key_file="certs/device-001.key.pem"
160189
)
161190

191+
# Read EMQX server CA certificate content
192+
with open("certs/emqx-server-ca.pem", "r") as f:
193+
emqx_server_ca = f.read()
194+
162195
# Create client pointing to EMQX
163196
client = IoTHubDeviceClient.create_from_x509_certificate(
164197
x509=x509,
165198
hostname="mqtt.example.com", # EMQX hostname instead of Azure
166199
device_id="device-001",
167-
server_verification_cert="certs/emqx-server-ca.pem" # EMQX server CA
200+
server_verification_cert=emqx_server_ca # CA cert content as string
168201
)
169202

170203
# Connect and use as before
171204
client.connect()
172205
client.send_message("Hello from migrated device")
173206
```
174207

208+
::: tip
209+
The `server_verification_cert` parameter expects the certificate **content as a string**, not a file path. If you've added the EMQX server CA to your system's trusted certificate store (recommended), you can omit this parameter and let the system handle verification.
210+
:::
211+
175212
**C# Example**:
176213

177214
```csharp

0 commit comments

Comments
 (0)