IMD SolutionComputing LibraryShop main store

Troubleshooting

Fixing X.509 certificate auth to Azure IoT Hub over MQTT

Edge computing and IIoT Published 8 min read

Short answer

The controller fails because the selected .key file is only half an X.509 credential: TLS client authentication must present the device certificate and its chain, so the key passes file validation and the handshake still has nothing to send. Convert the test certificates to PEM, import the leaf-plus-chain with its matching key as one pair, make the hub's device ID or thumbprint match, and verify with a real MQTT connection.

On this page
  1. Why does the private key pass validation but the connection still fails?
  2. Which certificate files does the controller actually need?
  3. How do I convert the generated certificates to PEM?
  4. What must be registered in Azure IoT Hub first?
  5. Azure mode or native MQTT mode on the controller?
  6. How do I check the pair matches before uploading it?
  7. What does a working X.509 setup look like end to end?
  8. How do I verify the fix with a real connection?
  9. Questions asked

Selecting only the private key is why the connection fails: a .key file passes file validation because it is a well-formed key, but X.509 client authentication requires the controller to present the device certificate and its chain, and a key alone leaves the TLS handshake with nothing to send. The fix is to convert the generated test certificates to PEM, import the device certificate with its full chain and the matching key as one pair, make the hub-side device identity match the certificate, and prove the result with a real MQTT connection — file validation is never verification. The sections below separate what each symptom proves, give the conversions and checks with commands and numbers, and end with the decision for every failure stage.

Why does the private key pass validation but the connection still fails? #

Because file validation only checks that the uploaded file is a parseable private key; X.509 client authentication needs the controller to present the device certificate and its chain during the TLS handshake, and a key alone gives it nothing to send.

During the handshake the hub asks for a certificate, the controller answers with the leaf certificate and the chain behind it, and the hub maps that answer to a registered device. Only after the certificate is accepted does the controller sign anything with the private key. No certificate selected means the handshake never reaches the signing step, so the connection drops after the file check has already passed.

Separate what each symptom actually proves:

  • SAS token connection worked: the network path, DNS, NTP and routing to the hub are proven. They are not the fault.
  • CA certificate accepted by the hub: cloud-side registration of the CA is under way. It says nothing about the controller's client credential files.
  • Certificate files rejected at upload: a file-format or import-workflow fault on the controller, before any TLS happens.
  • Key accepted, connection fails: the key parses; the credential set is incomplete.

Which certificate files does the controller actually need? #

Two matched files: the device certificate in PEM — the leaf plus the chain up to the CA you registered — and the private key for exactly that leaf; nothing else authenticates, and the key alone never will.

Microsoft's test-certificate tutorial (Create and upload certificates for testing) ships PowerShell and Bash scripts that build a root CA and device certificates signed by it; the root file those scripts produce is azure-iot-test-only.root.ca.cert.pem. For CA-signed enrollment the client must send the entire chain up to the registered CA — the Azure SDK certificate tools state that the device must send all chain certificates, not just the leaf.

That makes the import set:

  • the device (leaf) certificate in PEM,
  • the private key belonging to exactly that leaf,
  • the chain — leaf first, then every CA above it — as one concatenated PEM file or in the chain slot the controller's import offers.

Extensions vary (.cer, .crt, .cert, .pem); the content decides. A .cert file can be PEM text or DER binary, and a controller that rejects it is usually rejecting the encoding, not the certificate. The generated key file is PEM, so it parses while the certificate files can still fail. One limit matters: the tutorial certificates are test-only, with effectively public keys — production devices need certificates from your own secured PKI or a purchased CA.

How do I convert the generated certificates to PEM? #

Check the encoding first, then convert: openssl x509 -inform DER -in device.cert -out device.pem turns a binary DER certificate into PEM, and the chain file is the leaf PEM with the root CA PEM appended below it.

Test before converting, with device.cert standing for whatever your generator named the file (illustrative name):

openssl x509 -in device.cert -noout -text

If the certificate fields print, the file is already PEM. If the command cannot load it, the file is DER and one line fixes it:

openssl x509 -inform DER -in device.cert -out device.pem

Build the chain by concatenation, leaf first:

cat device.pem azure-iot-test-only.root.ca.cert.pem > device-fullchain.pem

PEM is printable text: a certificate block starts with a BEGIN CERTIFICATE line. Open the chain file and count two blocks — that is the visual check that the concatenation worked before you import anything.

What must be registered in Azure IoT Hub first? #

One of two enrollments: CA-signed — upload the root CA, prove ownership with a verification certificate, and register each device with its ID equal to the leaf certificate's CN — or self-signed, where the leaf itself is registered by its SHA-1 thumbprint, 40 hexadecimal characters.

CA accepted is not the finish line. The CA also has to be verified by proof of possession: the hub issues a verification code, you generate a certificate whose subject is exactly that code, sign it with the same CA, and upload it. Until the CA's status shows verified, every CA-signed device is refused. Microsoft's Authenticate with X.509 certificates reference sets out both enrollment types.

  • CA-signed: verify the CA once, then register devices by ID; at connect time the device presents the full chain and the hub matches the leaf CN to the registered device ID.
  • Self-signed: register the leaf certificate itself by thumbprint. The hub uses the SHA-1 hash of the certificate: 160 bits ÷ 4 bits per hexadecimal character = 40 characters. A SHA-256 fingerprint is 256 ÷ 4 = 64 characters — if your paste is 64 characters, you copied the wrong digest.

Azure mode or native MQTT mode on the controller? #

Use the vendor's Azure-specific mode: it builds the hub's expected client identity, username and topic structure for you, while a generic native-MQTT mode makes you supply those strings by hand and turns certificate problems into topic problems.

The usual test matrix covers an Azure-specific mode, a generic cloud mode and a native-MQTT mode. Stay in the Azure mode until the certificate path works: it derives the client identity and the message topics the hub expects from the device ID. Generic modes need those strings typed by hand, and one wrong string produces failures that masquerade as certificate faults. Revisit native mode after the X.509 connection is proven, not during.

How do I check the pair matches before uploading it? #

Compare the public keys: the SHA-256 digest of the certificate's public key and of the private key's public key must be identical — one command pair, and any mismatch means the key belongs to a different certificate.

openssl x509 -in device.pem -noout -pubkey | openssl sha256
openssl pkey -in device.key -pubout | openssl sha256

Both commands must print the same digest; if they differ, the key opens a different certificate and no hub-side setting will fix it. Read the validity window too:

openssl x509 -in device.pem -noout -dates

The controller clock must sit between notBefore and notAfter. With NTP configured and working this check is a formality, but it costs one command and it removes the one clock error that looks exactly like a credential fault.

What does a working X.509 setup look like end to end? #

A complete example: device ID edge-gw-07 (illustrative), leaf CN edge-gw-07, CA-signed enrollment with the verified test root, and a handshake that presents 2 certificates — the leaf plus the root — over TLS.

Numbered walkthrough with the arithmetic:

  1. Generate the test PKI; the root file is azure-iot-test-only.root.ca.cert.pem.
  2. Upload the root to the hub and complete proof of possession with the verification-code certificate until the status shows verified.
  3. Generate the device certificate with CN edge-gw-07; register the device in the hub with device ID edge-gw-07. CA-signed enrollment authenticates when the leaf CN equals the device ID: edge-gw-07 = edge-gw-07, match.
  4. Chain length: the tutorial's basic chain signs the device certificate directly with the root, so the handshake carries 1 leaf + 1 root = 2 certificates. Add an intermediate CA and it becomes 1 + 1 + 1 = 3.
  5. Convert to PEM, concatenate the chain, and confirm the two public-key digests match as above.
  6. Self-signed alternative for the same leaf: paste the SHA-1 thumbprint — 160 ÷ 4 = 40 hexadecimal characters — into the primary thumbprint field; the 64-character SHA-256 value is the wrong digest.
  7. Import the chain PEM and key on the controller as one pair, select the Azure mode, connect.

Decisions: CA-signed means chain file plus key, leaf CN equal to device ID. Self-signed means leaf plus key, 40-character thumbprint registered. Key-only selection is never a working credential.

How do I verify the fix with a real connection? #

Only a completed MQTT connection over TLS to the hub verifies the setup — connect, publish one telemetry message, and confirm the message lands in the device's event stream; every earlier step is preparation, not proof.

If it still fails, capture the exact stage; each stage has one decision:

Stage where it stops What it means The move
Certificate file rejected at upload Encoding or import-slot mismatch Convert DER to PEM; import chain and key as the pair the dialog asks for
Pair rejected at selection Certificate and key not matched, or chain malformed Re-run the digest check; rebuild the chain leaf-first
Validation passes, connection fails Controller files parse; hub identity or chain is wrong Check leaf CN against device ID, or the 40-character thumbprint; confirm the CA status is verified
Handshake fails immediately Chain not sent, or hub cannot build trust to it Send the full chain; complete proof of possession

Immediate handshake failures on controllers come down to the same chain-trust mechanics as fixing CODESYS MQTT TLS peer verification handshake failure — a missing chain certificate or a clock outside the validity window. To separate a client-side credential fault from a cloud-enrollment fault, prove the same pair against a broker you control first: the steps to run a secure Mosquitto MQTT lab broker with Node-RED give you a TLS listener with no cloud variables in the way.

Once the X.509 path connects, the payload flow is the same as sending PLC data to an IoT hub without custom software — moving from SAS tokens to certificates changes the authentication, not the data. Keep the SAS device as the fallback until the certificate connection has run for real.

Questions asked

Can I keep the SAS token connection running while I set up X.509?

Yes. Authentication type is a property of each device identity, so register a second device ID for the X.509 test and leave the SAS device as the working baseline. Telemetry keeps flowing through the token device while you fix certificates, and the two configurations sit side by side for comparison until the certificate connection is proven.

What happens when the device certificate expires?

The handshake starts failing on every connection once the controller clock passes the certificate's notAfter date. Generate a new certificate and key, import the new pair, and update the hub: with self-signed enrollment paste the new 40-character thumbprint; with CA-signed enrollment the CA registration stays valid and only the files change. Device Provisioning Service group enrollments follow the same renewal pattern.

Do DNS and NTP settings affect certificate authentication?

Both matter, differently. A DNS failure stops the connection before TLS starts. A wrong clock is nastier: certificate validation checks notBefore and notAfter against controller time, so a clock outside the validity window fails the handshake in a way that looks exactly like a credential fault. With NTP configured and working, both variables are off the table.

Should the root CA certificate travel inside the chain file?

For CA-signed enrollment, yes: the Azure SDK tools state the device must send every chain certificate up to the registered CA, and with the tutorial's basic chain that means leaf plus root. For self-signed enrollment the hub matches the leaf's thumbprint directly, so the leaf alone carries the identity.

Keep reading

  • How-to

    Bridging OPC UA PLC data to MQTT with an edge PC

    Keep the OPC UA server on the PLC side and give MQTT publishing its own role on a separate edge PC that acts as the OPC UA client and MQTT publisher. Commission the two links independently — first a verified tag read, then a verified subscriber message — and only then widen the tag set.

    Edge computing and IIoT

  • How-to

    Sending PLC data to an IoT hub without custom software

    You do not need custom software to move PLC data to an IoT hub: a configurable edge package with an S7, Modbus TCP or EtherNet/IP driver, a channel mapping and an MQTT publisher replaces hand-written acquisition code. Verify two things before you commit: the driver covers the protocol your controller actually speaks, and the publisher covers the destination's authentication and message format. Software still does the work — you configure it instead of writing it.

    Edge computing and IIoT

  • How-to

    Run Python and Node-RED beside PLC code on an edge PC

    Keep the IEC 61131-3 program in the controller runtime and run Python and Node-RED as separate Docker containers on the same edge PC. Exchange data over one MQTT interface with a fixed publish period, and declare data stale after three missed periods. One container per workload, and nothing from Python or Node-RED inside the control project.

    Edge computing and IIoT

Selecting a gateway to publish Modbus data to Azure IoT Hub