Skip to content

Commit e825907

Browse files
gsteve88gsteve88
committed
Added device connect with X509 information
1 parent 7edb881 commit e825907

7 files changed

+173
-3
lines changed

‎includes/iot-hub-howto-auth-device-cert-dotnet.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: How to connect a device to IoT Hub using a certificate (.NET)
3+
titleSuffix: Azure IoT Hub
4+
description: Learn how to connect a device to IoT Hub using a certificate and the Azure IoT Hub SDK for .NET.
5+
author: kgremban
6+
ms.author: kgremban
7+
ms.service: iot-hub
8+
ms.devlang: csharp
9+
ms.topic: include
10+
ms.manager: lizross
11+
ms.date: 11/19/2024
12+
ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
13+
---
14+
15+
1. Use [DeviceAuthenticationWithX509Certificate](/dotnet/api/microsoft.azure.devices.client.deviceauthenticationwithx509certificate) to create an object that contains certificate information that will be passed to `Create` (step 2).
16+
17+
2. Use [Create](https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.devices.client.deviceclient.create?#microsoft-azure-devices-client-deviceclient-create(system-string-microsoft-azure-devices-client-iauthenticationmethod)) to connect the device to IoT Hub using a X.509 certificate.
18+
19+
This example shows certificate input parameter values as local variables for clarity. In a production system, store sensitive input parameters in environment variables or another more secure storage location. For example, use `Environment.GetEnvironmentVariable("HOSTNAME")` to read the host name environment variable.
20+
21+
```csharp
22+
RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.cer";
23+
Intermediate1CertPath = "";
24+
Intermediate2CertPath = "";
25+
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
26+
DevicePfxPassword = "1234";
27+
DeviceName = "MyDevice";
28+
HostName = "xxxxx.azure-devices.net";
29+
30+
var chainCerts = new X509Certificate2Collection();
31+
chainCerts.Add(new X509Certificate2(RootCertPath));
32+
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
33+
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
34+
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
35+
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);
36+
37+
using var deviceClient = DeviceClient.Create(
38+
HostName,
39+
auth,
40+
TransportType.Amqp);
41+
```
42+
43+
For more information about certificate authentication, see:
44+
45+
* [Authenticate identities with X.509 certificates](/azure/iot-hub/authenticate-authorize-x509)
46+
* [Create and upload certificates for testing](/azure/iot-hub/tutorial-x509-test-certs)
47+
48+
##### Code samples
49+
50+
For a working sample of device X.509 certificate authentication, see [x509 device certificate with chain sample](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples/how%20to%20guides/X509DeviceCertWithChainSample).

‎includes/iot-hub-howto-auth-device-cert-java.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: How to connect a device to IoT Hub using a certificate (Java)
3+
titleSuffix: Azure IoT Hub
4+
description: Learn how to connect a device to IoT Hub using a certificate and the Azure IoT Hub SDK for Java.
5+
author: kgremban
6+
ms.author: kgremban
7+
ms.service: iot-hub
8+
ms.devlang: java
9+
ms.topic: include
10+
ms.manager: lizross
11+
ms.date: 11/19/2024
12+
---
13+
14+
To connect a device to IoT Hub using an X.509 certificate:
15+
16+
1. Build the [SSLContext](https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html) object using [buildSSLContext](https://hc.apache.org/httpcomponents-core-4.4.x/current/httpcore/apidocs/org/apache/http/ssl/SSLContextBuilder.html)
17+
1. Add the `SSLContext` information to a [ClientOptions](/java/api/com.microsoft.azure.sdk.iot.device.clientoptions) object.
18+
1. Call [DeviceClient](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient?view=azure-java-stable#com-microsoft-azure-sdk-iot-device-deviceclient-deviceclient(java-lang-string-com-microsoft-azure-sdk-iot-device-iothubclientprotocol-com-microsoft-azure-sdk-iot-device-clientoptions)) using the `ClientOptions` information to create the device-to-IoT Hub connection.
19+
20+
This example shows certificate input parameter values as local variables for clarity. In a production system, store sensitive input parameters in environment variables or another more secure storage location. For example, use `Environment.GetEnvironmentVariable("PUBLICKEY")` to read a public key certificate string environment variable.
21+
22+
```java
23+
private static final String publicKeyCertificateString =
24+
"-----BEGIN CERTIFICATE-----\n" +
25+
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
26+
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
27+
"-----END CERTIFICATE-----\n";
28+
29+
//PEM encoded representation of the private key
30+
private static final String privateKeyString =
31+
"-----BEGIN EC PRIVATE KEY-----\n" +
32+
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
33+
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
34+
"-----END EC PRIVATE KEY-----\n";
35+
36+
SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
37+
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
38+
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);
39+
```
40+
41+
For more information about certificate authentication, see:
42+
43+
* [Authenticate identities with X.509 certificates](/azure/iot-hub/authenticate-authorize-x509)
44+
* [Create and upload certificates for testing](/azure/iot-hub/tutorial-x509-test-certs)
45+
46+
##### Code samples
47+
48+
For working samples of device X.509 certificate authentication, see:
49+
50+
* [Send-receive x509 sample](https://github.com/Azure/azure-iot-sdk-java/tree/main/iothub/device/iot-device-samples/send-receive-x509-sample)
51+
* [Send event x509](https://github.com/Azure/azure-iot-sdk-java/blob/main/iothub/device/iot-device-samples/send-event-x509/src/main/java/samples/com/microsoft/azure/sdk/iot/SendEventX509.java)

‎includes/iot-hub-howto-auth-device-cert-node.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: How to connect a device to IoT Hub using a certificate (Node.js)
3+
titleSuffix: Azure IoT Hub
4+
description: Learn how to connect a device to IoT Hub using a certificate and the Azure IoT Hub SDK for Node.js.
5+
author: kgremban
6+
ms.author: kgremban
7+
ms.service: iot-hub
8+
ms.devlang: python
9+
ms.topic: include
10+
ms.manager: lizross
11+
ms.date: 12/06/2024
12+
---
13+
14+
Using the Node.js SDK, the X.509 certificate is attached to the device-to-IoT Hub connection transport.
15+
16+
To configure a device-to-IoT Hub connection using an X.509 certificate:
17+
18+
1. Call [fromConnectionString](/javascript/api/azure-iothub/client?view=azure-node-latest#azure-iothub-client-fromconnectionstring) to add the device connection string and transport type.
19+
1. Configure a JSON variable with certificate details and pass it to [DeviceClientOptions](/javascript/api/azure-iot-device/deviceclientoptions).
20+
1. Call [setOptions](/javascript/api/azure-iot-device/client?#azure-iot-device-client-setoptions-1) to add an X.509 certificate and key (and optionally, passphrase) to the client transport.
21+
1. Call [open](/javascript/api/azure-iothub/client?view=azure-node-latest#azure-iothub-client-open) to open the connection from the device to IoT Hub.
22+
23+
This example shows certificate configuration information within a JSON variable. The certification configuration `options` are passed to `setOptions` and the connection is opened using `open`.
24+
25+
```javascript
26+
var options = {
27+
cert: myX509Certificate,
28+
key: myX509Key,
29+
passphrase: passphrase,
30+
http: {
31+
receivePolicy: {
32+
interval: 10
33+
}
34+
}
35+
}
36+
client.setOptions(options, callback);
37+
client.open(connectCallback);
38+
```
39+
40+
For more information about certificate authentication, see:
41+
42+
* [Authenticate identities with X.509 certificates](/azure/iot-hub/authenticate-authorize-x509)
43+
* [Create and upload certificates for testing](/azure/iot-hub/tutorial-x509-test-certs)
44+
45+
##### Code samples
46+
47+
For a working sample of device X.509 certificate authentication, see [Simple sample device X.509](https://github.com/Azure/azure-iot-sdk-node/blob/main/device/samples/javascript/simple_sample_device_x509.js).

‎includes/iot-hub-howto-auth-device-cert-python.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ device_id = "MyDevice"
2929
# The X.509 certificate file name
3030
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
3131
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
32-
# The certificate pass phrase is optional
32+
# The optional certificate pass phrase
3333
pass_phrase = "1234"
3434

3535
x509 = X509(

‎includes/iot-hub-howto-file-upload-dotnet.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,17 @@ Follow this procedure to upload a file from a device to IoT hub:
3131

3232
### Connect to the device
3333

34+
A device app can authenticate with IoT Hub using the following methods:
35+
36+
* X.509 certificate
37+
* Shared access key
38+
39+
#### Authenticate using an X.509 certificate
40+
41+
[!INCLUDE [iot-hub-howto-auth-device-cert-dotnet](iot-hub-howto-auth-device-cert-python.md)]
42+
43+
#### Authenticate using a shared access key
44+
3445
Call [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.client.deviceclient.createfromconnectionstring?#microsoft-azure-devices-client-deviceclient-createfromconnectionstring(system-string)) to connect to the device. Pass the device primary connection string.
3546

3647
`AMQP` is the default transport protocol.

‎includes/iot-hub-howto-file-upload-java.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,18 @@ File upload operations always use HTTPS, but [DeviceClient](/java/api/com.micros
3737
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
3838
```
3939

40-
### Connect to the device
40+
### Connect a device to IoT Hub
41+
42+
A device app can authenticate with IoT Hub using the following methods:
43+
44+
* X.509 certificate
45+
* Shared access key
46+
47+
#### Authenticate using an X.509 certificate
48+
49+
[!INCLUDE [iot-hub-howto-auth-device-cert-java](iot-hub-howto-auth-device-cert-java.md)]
50+
51+
#### Authenticate using a shared access key
4152

4253
Instantiate the `DeviceClient` to connect to the device using the device primary connection string.
4354

‎includes/iot-hub-howto-file-upload-python.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ from azure.storage.blob import BlobClient
4747

4848
### Connect a device to IoT Hub
4949

50-
A device app can authenticate using the following methods:
50+
A device app can authenticate with IoT Hub using the following methods:
5151

5252
* X.509 certificate
5353
* Shared access key

0 commit comments

Comments
 (0)