How to fix module identity authentication issue while IoTEdge device is registered via X509 self signed certificate

Question

How to fix module identity authentication issue while IoTEdge device is registered via X509 self signed certificate

Vishnu Priya 5

I have registered an edge device[gateway] to Azure IoTHub using x509 self signed certificate. The device got registered fine and modules [edgeAgent,edgeHub] got deployed along with some custom edge modules- with deployment status 200, device and modules status reporting. The modules are running on the edge device but the modules keep restarting as they couldnt authenticate.

edge Device registration is through x509 self signed certificate, with below properties in config.toml

# Manual provisioning with x.509 certificates

[provisioning]

source = "manual"

iothub_hostname = "REQUIRED_IOTHUB_HOSTNAME"

device_id = "REQUIRED_DEVICE_ID_PROVISIONED_IN_IOTHUB"

[provisioning.authentication]

method = "x509"

identity_cert = "REQUIRED_URI_OR_POINTER_TO_DEVICE_IDENTITY_CERTIFICATE"

identity_pk = "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY"

Logs from edgeHub:

[INF] - Unable to authenticate client <deviceid>/<custom_edge_module> with cached service identity <deviceid>/<custom_edge_module> (Found: False). Resyncing service identity... <4> 2025-09-19 00:29:56.415 +00:00 [WRN] - Error while refreshing the service identity: <deviceid>/<custom_edge_module> OnBehalfOf: <deviceid> System.Collections.Generic.KeyNotFoundException: The given key '<deviceid>/<custom_edge_module>' was not present in the dictionary.    at Microsoft.Azure.Devices.Edge.Hub.Core.DeviceScopeIdentitiesCache.RefreshServiceIdentityInternal(String refreshTarget, String onBehalfOfDevice, Boolean invokeServiceIdentitiesUpdated) in /mnt/vss/_work/1/s/edge-hub/core/src/Microsoft.Azure.Devices.Edge.Hub.Core/DeviceScopeIdentitiesCache.cs:line 187

device twin status:

  "deviceScope": "ms-azure-iot-edge://<devicescope>",
    "modelId": "",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00.0000000Z",
    "lastActivityTime": "2025-09-19T00:47:10.0840495Z",
    "connectionState": "Connected",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "selfSigned",
    "x509Thumbprint": {
        "PrimaryThumbprint": "<thumbprint>"
    }

Module identity twin of edgeHub:

  "modelId": "",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00.0000000Z",
    "lastActivityTime": "2025-09-19T00:42:23.4967322Z",
    "connectionState": "Connected",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {}

module identity twin of edgeAgent and other modules:

"modelId": "",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00.0000000Z",
    "lastActivityTime": "2025-09-19T00:54:15.6085296Z",
    "connectionState": "Disconnected",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {}

The modules couldnt communicate to hub as they couldnt authenticate, where as the same modules works fine when the edge device is registered via shared access signature and send telemetry to iot hub.

Please let me know where could the issue be for modules not able to communicate with iotHub

VSawhney 1,295 Reputation points Microsoft External Staff Moderator

2025-09-19T11:21:29.2966667+00:00
Hello Vishnu Priya,

Hey there! It seems like you're experiencing issues with module identity authentication for your IoT Edge device that's using an X.509 self-signed certificate. This is a common troubleshooting area, so let's break it down.

Given that your edge device is registered correctly and the modules are deployed, yet you're encountering restarts due to authentication issues, here are a few steps you can take:

Check Certificate Configuration:

Ensure that the device identity certificate used for provisioning has been correctly uploaded and registered in IoT Hub.

Validate that the thumbprint provided in your device’s configuration matches the registered thumbprint in IoT Hub. Use the OpenSSL command mentioned in your documentation:
openssl x509 -in <path_to_your_certificate> -noout -fingerprint -sha256

Trust Bundle:

Since you're using a self-signed certificate, ensure that the root CA certificate is installed on your device. This establishes a trust relationship so that the device can authenticate against IoT Hub.

Review Module Identity Configuration:

The log suggests that the edgeHub module is attempting to refresh the service identity but failing. Verify the identity configurations for each module, especially ensure that the modules are configured to use SAS tokens derived from the edge device’s identity certificate.

Module Communication:

As modules use SAS keys generated by the IoT Edge runtime, check if those keys are correctly set up and valid. If the underlying device identity certificate is incorrect or expired, the modules may struggle to authenticate to IoT Hub.

Check for Errors in Logs:

Review the full IoT Edge device logs for any additional error messages unrelated to the edgeHub to pinpoint any issues with connectivity or registration.

Hope this helps!
Thank you!
VSawhney 1,295 Reputation points Microsoft External Staff Moderator

2025-09-22T12:19:21.6466667+00:00

Hello Vishnu Priya,

Following up to see if the response was helpful. Please feel free to reach us if you have any further query.

Thank you!
Vishnu Priya 5 Reputation points

2025-09-23T00:36:32.0033333+00:00
@VSawhney Still no luck :(

I have validated as below for the steps your provided.

Check Certificate Configuration:

It is Self signed certificate and primary thumbprint was genererated using below command and matches the same in azure portal.

https://dori-uw-1.kuma-moon.com/en-us/azure/iot-edge/how-to-authenticate-downstream-device#x509-self-signed-authentication

openssl x509 -in <path to primary device certificate>.cert.pem -text -fingerprint

Trust Bundle:

root-ca has been installed to os-cert store as per link below:

https://dori-uw-1.kuma-moon.com/en-us/azure/iot-edge/how-to-manage-device-certificates?tabs=ubuntu#install-root-ca-to-os-certificate-store

using commands:

sudo cp /var/aziot/certs/my-root-ca.pem /usr/local/share/ca-certificates/my-root-ca.pem.crt sudo update-ca-certificates

added below in config.toml

trust_bundle_cert = "file:///var/aziot/certs/root-ca.pem"

sudo iotedge config apply

Review Module Identity Configuration:

module identity twin settings for all modules is as below:

"authenticationType": "sas",

Module Communication:

Requesting to provide guidelines on how to verify the same.

but in module code, it is initialized as below,

IoTHubModuleClient.create_from_edge_environment()
Manas Mohanty 13,340 Reputation points Moderator

2025-09-23T10:39:26.3766667+00:00

Hey Vishnu Priya

Does your device id contain special character like underscores or hashes by any chance. There are reporting managed identity breaking if Device ID contains underscore or any special character.

Thank you
Vishnu Priya 5 Reputation points

2025-09-24T03:39:16.62+00:00

@Manas Mohanty Thank you for the reply.
The device id contains alphabets [small and caps],numbers and hiphen

Does this cause any issue?

1 answer

Your answer

VSawhney 1,295 Reputation points Microsoft External Staff Moderator

2025-09-19T11:21:29.2966667+00:00

Hello Vishnu Priya,

Hey there! It seems like you're experiencing issues with module identity authentication for your IoT Edge device that's using an X.509 self-signed certificate. This is a common troubleshooting area, so let's break it down.

Given that your edge device is registered correctly and the modules are deployed, yet you're encountering restarts due to authentication issues, here are a few steps you can take:

Check Certificate Configuration:

Ensure that the device identity certificate used for provisioning has been correctly uploaded and registered in IoT Hub.

Validate that the thumbprint provided in your device’s configuration matches the registered thumbprint in IoT Hub. Use the OpenSSL command mentioned in your documentation:
openssl x509 -in <path_to_your_certificate> -noout -fingerprint -sha256

Trust Bundle:

Since you're using a self-signed certificate, ensure that the root CA certificate is installed on your device. This establishes a trust relationship so that the device can authenticate against IoT Hub.

Review Module Identity Configuration:

The log suggests that the edgeHub module is attempting to refresh the service identity but failing. Verify the identity configurations for each module, especially ensure that the modules are configured to use SAS tokens derived from the edge device’s identity certificate.

Module Communication:

As modules use SAS keys generated by the IoT Edge runtime, check if those keys are correctly set up and valid. If the underlying device identity certificate is incorrect or expired, the modules may struggle to authenticate to IoT Hub.

Check for Errors in Logs:

Review the full IoT Edge device logs for any additional error messages unrelated to the edgeHub to pinpoint any issues with connectivity or registration.

Hope this helps!
Thank you!
VSawhney 1,295 Reputation points Microsoft External Staff Moderator

2025-09-22T12:19:21.6466667+00:00

Hello Vishnu Priya,

Following up to see if the response was helpful. Please feel free to reach us if you have any further query.

Thank you!
Vishnu Priya 5 Reputation points

2025-09-23T00:36:32.0033333+00:00

@VSawhney Still no luck :(

I have validated as below for the steps your provided.

Check Certificate Configuration:

It is Self signed certificate and primary thumbprint was genererated using below command and matches the same in azure portal.

https://dori-uw-1.kuma-moon.com/en-us/azure/iot-edge/how-to-authenticate-downstream-device#x509-self-signed-authentication

openssl x509 -in <path to primary device certificate>.cert.pem -text -fingerprint

Trust Bundle:

root-ca has been installed to os-cert store as per link below:

https://dori-uw-1.kuma-moon.com/en-us/azure/iot-edge/how-to-manage-device-certificates?tabs=ubuntu#install-root-ca-to-os-certificate-store

using commands:

sudo cp /var/aziot/certs/my-root-ca.pem /usr/local/share/ca-certificates/my-root-ca.pem.crt sudo update-ca-certificates

added below in config.toml

trust_bundle_cert = "file:///var/aziot/certs/root-ca.pem"

sudo iotedge config apply

Review Module Identity Configuration:

module identity twin settings for all modules is as below:

"authenticationType": "sas",

Module Communication:

Requesting to provide guidelines on how to verify the same.

but in module code, it is initialized as below,

IoTHubModuleClient.create_from_edge_environment()
Manas Mohanty 13,340 Reputation points Moderator

2025-09-23T10:39:26.3766667+00:00

Hey Vishnu Priya

Does your device id contain special character like underscores or hashes by any chance. There are reporting managed identity breaking if Device ID contains underscore or any special character.

Thank you
Vishnu Priya 5 Reputation points

2025-09-24T03:39:16.62+00:00

@Manas Mohanty Thank you for the reply.
The device id contains alphabets [small and caps],numbers and hiphen

Does this cause any issue?

Answer 1

Vishnu Priya

Sorry for the delay in response

Hyphens are allowed and below format is valide

The device id contains alphabets [small and caps],numbers and hiphen

Your device is using X.509 authentication, but the module identities (including edgeAgent and edgeHub) are showing sas as their authentication type in the twin properties.

Fix:

Ensure that all modules are configured to use X.509 authentication if the device is using X.509.
Update the deployment manifest to explicitly set the authentication type for each module.

Reference: https://github.com/Azure/iotedge/issues/7380

If the issue persists even with x509 authentication (instead of SAS ) for module, Please share iot edge logs in private chat

sudo iotedge check
sudo iotedge system set-log-level debug
sudo iotedge system logs -- -f

Thank you

Share via

How to fix module identity authentication issue while IoTEdge device is registered via X509 self signed certificate

1 answer

Your answer