Skip to content

Commit beca54d

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #291704 from gsteve88/add-entra-upload-files
Updated how to upload file to add cert auth include file
2 parents 8e8cceb + e65e6f3 commit beca54d

9 files changed

+486
-72
lines changed

‎articles/iot-hub/how-to-file-upload.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ms.author: kgremban
77
manager: lizross
88
ms.service: azure-iot-hub
99
ms.topic: how-to
10-
ms.date: 07/01/2024
10+
ms.date: 12/12/2024
1111
zone_pivot_groups: iot-hub-howto-c2d-1
1212
ms.custom: [amqp, mqtt, "Role: Cloud Development", "Role: IoT Device"]
1313
---

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
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: 12/12/2024
12+
ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
13+
---
14+
15+
To connect a device to IoT Hub using an X.509 certificate:
16+
17+
1. Use [DeviceAuthenticationWithX509Certificate](/dotnet/api/microsoft.azure.devices.client.deviceauthenticationwithx509certificate) to create an object that contains device and certificate information. `DeviceAuthenticationWithX509Certificate` is passed as the second parameter to `DeviceClient.Create` (step 2).
18+
19+
1. Use [DeviceClient.Create](/dotnet/api/microsoft.azure.devices.client.deviceclient.create?&#microsoft-azure-devices-client-deviceclient-create(system-string-microsoft-azure-devices-client-iauthenticationmethod-microsoft-azure-devices-client-transporttype)) to connect the device to IoT Hub using an X.509 certificate.
20+
21+
In this example, device and certificate information is populated in the `auth` `DeviceAuthenticationWithX509Certificate` object that is passed to `DeviceClient.Create`.
22+
23+
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.
24+
25+
```csharp
26+
RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
27+
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
28+
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
29+
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
30+
DevicePfxPassword = "1234";
31+
DeviceName = "MyDevice";
32+
HostName = "xxxxx.azure-devices.net";
33+
34+
var chainCerts = new X509Certificate2Collection();
35+
chainCerts.Add(new X509Certificate2(RootCertPath));
36+
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
37+
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
38+
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
39+
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);
40+
41+
using var deviceClient = DeviceClient.Create(
42+
HostName,
43+
auth,
44+
TransportType.Amqp);
45+
```
46+
47+
For more information about certificate authentication, see:
48+
49+
* [Authenticate identities with X.509 certificates](/azure/iot-hub/authenticate-authorize-x509)
50+
* [Tutorial: Create and upload certificates for testing](/azure/iot-hub/tutorial-x509-test-certs)
51+
52+
##### Code samples
53+
54+
For working samples of device X.509 certificate authentication, see:
55+
56+
* [Connect with X.509 certificate](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples/how%20to%20guides/X509DeviceCertWithChainSample)
57+
* [DeviceClientX509AuthenticationE2ETests](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/e2e/test/iothub/DeviceClientX509AuthenticationE2ETests.cs)
58+
* [Guided project - Provision IoT devices securely and at scale with IoT Hub Device Provisioning Service](/training/modules/provision-iot-devices-secure-scale-with-iot-hub-dps/)

‎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: 12/12/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?#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+
* [Tutorial: 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: node
9+
ms.topic: include
10+
ms.manager: lizross
11+
ms.date: 12/12/2024
12+
---
13+
14+
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?#azure-iothub-client-fromconnectionstring) to add the device connection string and transport type. Add `x509=true` to the device connection string to indicate that a certificate is added to `DeviceClientOptions`. For example: `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`.
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?#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 sample
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: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: How to connect a device to IoT Hub using a certificate (Python)
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 Python.
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+
To connect a device to IoT Hub using an X.509 certificate:
15+
16+
1. Use [create_from_x509_certificate](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-create-from-x509-certificate) to add the X.509 certificate parameters
17+
1. Call [connect](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-connect) to connect the device client
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 `os.getenv("HOSTNAME")` to read the host name environment variable.
20+
21+
```python
22+
# The Azure IoT hub name
23+
hostname = "xxxxx.azure-devices.net"
24+
25+
# The device that has been created on the portal using X509 CA signing or self-signing capabilities
26+
device_id = "MyDevice"
27+
28+
# The X.509 certificate file name
29+
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
30+
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
31+
# The optional certificate pass phrase
32+
pass_phrase = "1234"
33+
34+
x509 = X509(
35+
cert_file,
36+
key_file,
37+
pass_phrase,
38+
)
39+
40+
# The client object is used to interact with your Azure IoT hub.
41+
device_client = IoTHubDeviceClient.create_from_x509_certificate(
42+
hostname=hostname, device_id=device_id, x509=x509
43+
)
44+
45+
# Connect to IoT Hub
46+
await device_client.connect()
47+
```
48+
49+
For more information about certificate authentication, see:
50+
51+
* [Authenticate identities with X.509 certificates](/azure/iot-hub/authenticate-authorize-x509)
52+
* [Tutorial: Create and upload certificates for testing](/azure/iot-hub/tutorial-x509-test-certs)
53+
54+
##### Code samples
55+
56+
For working samples of device X.509 certificate authentication, see the examples whose file names end in x509 at [Async hub scenarios](https://github.com/Azure/azure-iot-sdk-python/tree/main/samples/async-hub-scenarios).

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

Lines changed: 49 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ms.author: kgremban
77
ms.service: azure-iot-hub
88
ms.devlang: csharp
99
ms.topic: include
10-
ms.date: 07/01/2024
10+
ms.date: 12/12/2024
1111
ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
1212
---
1313

@@ -29,7 +29,18 @@ Follow this procedure to upload a file from a device to IoT hub:
2929
1. Upload the file to Azure storage
3030
1. Notify IoT hub of the file upload status
3131

32-
### Connect to the device
32+
### Connect a device to IoT Hub
33+
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-dotnet.md)]
42+
43+
#### Authenticate using a shared access key
3344

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

@@ -109,21 +120,47 @@ You can create a backend service to receive file upload notification messages fr
109120

110121
The [ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) class contains methods that services can use to receive file upload notifications.
111122

112-
To receive file upload notification:
123+
### Add service NuGet Package
113124

114-
1. Call [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.serviceclient.createfromconnectionstring) to connect to IoT hub. Pass the IoT hub primary connection string.
115-
1. Create a [CancellationToken](/dotnet/api/azure.core.httpmessage.cancellationtoken?#azure-core-httpmessage-cancellationtoken).
116-
1. Call [GetFileNotificationReceiver](/dotnet/api/microsoft.azure.devices.serviceclient.getfilenotificationreceiver?#microsoft-azure-devices-serviceclient-getfilenotificationreceiver) to create a notification receiver.
117-
1. Use a loop with [ReceiveAsync](/dotnet/api/microsoft.azure.devices.receiver-1.receiveasync?#microsoft-azure-devices-receiver-1-receiveasync(system-threading-cancellationtoken)) to wait for the file upload notification.
125+
Backend service applications require the **Microsoft.Azure.Devices** NuGet package.
126+
127+
### Connect to IoT hub
128+
129+
You can connect a backend service to IoT Hub using the following methods:
130+
131+
* Shared access policy
132+
* Microsoft Entra
133+
134+
[!INCLUDE [iot-authentication-service-connection-string.md](iot-authentication-service-connection-string.md)]
135+
136+
#### Connect using a shared access policy
137+
138+
Connect a backend application to a device using [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.registrymanager.createfromconnectionstring). Your application needs **service connect** permission. Supply this shared access policy connection string as a parameter to `fromConnectionString`. For more information about shared access policies, see [Control access to IoT Hub with shared access signatures](/azure/iot-hub/authenticate-authorize-sas).
118139

119140
For example:
120141

121142
```csharp
122143
using Microsoft.Azure.Devices;
123144
static ServiceClient serviceClient;
124-
static string connectionString = "{IoT hub connection string}";
145+
static string connectionString = "{Shared access policy connection string}";
125146
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
147+
```
148+
149+
#### Connect using Microsoft Entra
150+
151+
[!INCLUDE [iot-hub-howto-connect-service-iothub-entra-dotnet](iot-hub-howto-connect-service-iothub-entra-dotnet.md)]
152+
153+
### Receive file upload notification
126154

155+
To receive file upload notification:
156+
157+
1. Create a [CancellationToken](/dotnet/api/azure.core.httpmessage.cancellationtoken?#azure-core-httpmessage-cancellationtoken).
158+
1. Call [GetFileNotificationReceiver](/dotnet/api/microsoft.azure.devices.serviceclient.getfilenotificationreceiver?#microsoft-azure-devices-serviceclient-getfilenotificationreceiver) to create a notification receiver.
159+
1. Use a loop with [ReceiveAsync](/dotnet/api/microsoft.azure.devices.receiver-1.receiveasync?#microsoft-azure-devices-receiver-1-receiveasync(system-threading-cancellationtoken)) to wait for the file upload notification.
160+
161+
For example:
162+
163+
```csharp
127164
// Define the cancellation token
128165
CancellationTokenSource source = new CancellationTokenSource();
129166
CancellationToken token = source.Token;
@@ -144,3 +181,7 @@ while (true)
144181
await notificationReceiver.CompleteAsync(fileUploadNotification);
145182
}
146183
```
184+
185+
### SDK file upload receiver sample
186+
187+
The SDK includes this [file upload receiver sample](https://github.com/Azure/azure-iot-sdk-csharp/blob/86065001a92fedb42877722c6a57ae37e45eed30/iothub/service/samples/getting%20started/FileUploadNotificationReceiverSample/FileUploadNotificationReceiverSample.cs).

0 commit comments

Comments
 (0)