Merge pull request #190564 from dominicbetts/central-connectivity-reorg

IoT Central reorg connectivity guide

Author: PMEds28

articles/iot-central/.openpublishing.redirection.iot-central.json

@@ -182,12 +182,12 @@
     },
     {
       "source_path_from_root": "/articles/iot-central/core/concepts-connectivity-pnp.md",
-      "redirect_url": "/azure/iot-central/core/concepts-get-connected",
+      "redirect_url": "/azure/iot-central/core/overview-iot-central-developer/",
       "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-central/preview/overview-iot-central-get-connected.md",
-      "redirect_url": "/azure/iot-central/core/concepts-get-connected/",
+      "redirect_url": "/azure/iot-central/core/overview-iot-central-developer/",
       "redirect_document_id": false
     },
     {
@@ -1329,6 +1329,11 @@
       "source_path_from_root": "/articles/iot-central/core/concepts-scalability-availability.md",
       "redirect_url": "/azure/iot-central/core/concepts-faq-scalability-availability",
       "redirect_document_id": true
+    },
+    {
+      "source_path_from_root": "/articles/iot-central/preview/concepts-get-connected.md",
+      "redirect_url": "/azure/iot-central/core/overview-iot-central-developer/",
+      "redirect_document_id": false
     }
   ]
 }

articles/iot-central/TOC.yml

@@ -85,8 +85,10 @@
     - name: Device connectivity guide
       href: core/overview-iot-central-developer.md
       items:
-      - name: Device connectivity concepts
-        href: core/concepts-get-connected.md
+      - name: Device implementation and best practices
+        href: core/concepts-device-implementation.md
+      - name: Device authentication
+        href: core/concepts-device-authentication.md
       - name: Device templates
         href: core/concepts-device-templates.md      
       - name: Connect IoT Edge devices

articles/iot-central/core/concepts-architecture.md

@@ -24,7 +24,7 @@ Key capabilities in an IoT Central application include:
 
 IoT Central lets you manage the fleet of [IoT devices](#devices) that are sending data to your solution. For example, you can:
 
-- Control which devices can [connect](concepts-get-connected.md) to your application and how they authenticate.
+- Control which devices can [connect](overview-iot-central-developer.md#how-devices-connect) to your application and how they authenticate.
 - Use [device templates](concepts-device-templates.md) to define the types of device that can connect to your application.
 - Manage devices by setting properties or calling commands on connected devices. For example, set a target temperature property for a thermostat device or call a command to trigger a device to update its firmware. You can set properties and call commands on:
   - Individual devices through a [customizable](concepts-device-templates.md#views) web UI.
@@ -44,7 +44,7 @@ In an IoT Central application, you can view and analyze data for individual devi
 
 In an IoT Central application you can manage the following security aspects of your solution:
 
-- [Device connectivity](concepts-get-connected.md): Create, revoke, and update the security keys that your devices use to establish a connection to your application.
+- [Device authentication](concepts-device-authentication.md): Create, revoke, and update the security keys that your devices use to establish a connection to your application.
 - [App integrations](howto-authorize-rest-api.md#get-an-api-token): Create, revoke, and update the security keys that other applications use to establish secure connections with your application.
 - [Data export](howto-export-data.md#connection-options): Use managed identities to secure the connection to your data export destinations.
 - [User management](howto-manage-users-roles.md): Manage the users that can sign in to the application and the roles that determine what permissions those users have.
@@ -58,7 +58,7 @@ A device can use properties to report its state, such as whether a valve is open
 
 IoT Central can also control devices by calling commands on the device. For example, instructing a device to download and install a firmware update.
 
-The [telemetry, properties, and commands](concepts-telemetry-properties-commands.md) that a device implements are collectively known as the device capabilities. You define these capabilities in a model that's shared between the device and the IoT Central application. In IoT Central, this model is part of the device template that defines a specific type of device. To learn more, see [Associate a device with a device template](concepts-get-connected.md#associate-a-device-with-a-device-template).
+The [telemetry, properties, and commands](concepts-telemetry-properties-commands.md) that a device implements are collectively known as the device capabilities. You define these capabilities in a model that's shared between the device and the IoT Central application. In IoT Central, this model is part of the device template that defines a specific type of device. To learn more, see [Assign a device to a device template](concepts-device-templates.md#assign-a-device-to-a-device-template).
 
 The [device implementation](tutorial-connect-device.md) should follow the [IoT Plug and Play conventions](../../iot-develop/concepts-convention.md) to ensure that it can communicate with IoT Central. For more information, see the various language [SDKs and samples](../../iot-develop/libraries-sdks.md).
 

articles/iot-central/core/concepts-device-authentication.md

@@ -0,0 +1,141 @@
+---
+title: Device authentication in Azure IoT Central | Microsoft Docs
+description: This article introduces key concepts relating to device authentication in Azure IoT Central
+author: dominicbetts
+ms.author: dobett
+ms.date: 03/02/2022
+ms.topic: conceptual
+ms.service: iot-central
+services: iot-central
+
+ms.custom:  [amqp, mqtt, device-developer]
+
+# This article applies to operators and device developers.
+---
+
+# Device authentication concepts in IoT Central
+
+This article describes how devices authenticate to an IoT Central application. To learn more about the overall connection process, see [Connect a device](overview-iot-central-developer.md#how-devices-connect).
+
+Devices authenticate with the IoT Central application by using either a _shared access signature (SAS) token_ or an _X.509 certificate_. X.509 certificates are recommended in production environments.
+
+You use _enrollment groups_ to manage the device authentication options in your IoT Central application.
+
+This article describes the following device authentication options:
+
+- [X.509 enrollment group](#x509-enrollment-group)
+- [SAS enrollment group](#sas-enrollment-group)
+- [Individual enrollment](#individual-enrollment)
+
+## X.509 enrollment group
+
+In a production environment, using X.509 certificates is the recommended device authentication mechanism for IoT Central. To learn more, see [Device Authentication using X.509 CA Certificates](../../iot-hub/iot-hub-x509ca-overview.md).
+
+An X.509 enrollment group contains a root or intermediate X.509 certificate. Devices can authenticate if they have a valid leaf certificate that's derived from the root or intermediate certificate.
+
+To connect a device with an X.509 certificate to your application:
+
+1. Create an _enrollment group_ that uses the **Certificates (X.509)** attestation type.
+1. Add and verify an intermediate or root X.509 certificate in the enrollment group.
+1. Generate a leaf certificate from the root or intermediate certificate in the enrollment group. Install the leaf certificate on the device for it to use when it connects to your application.
+
+To learn more, see [How to connect devices with X.509 certificates](how-to-connect-devices-x509.md)
+
+### For testing purposes only
+
+In a production environment, use certificates from your certificate provider. For testing only, you can use the following utilities to generate root, intermediate, and device certificates:
+
+- [Tools for the Azure IoT Device Provisioning Device SDK](https://github.com/Azure/azure-iot-sdk-node/blob/main/provisioning/tools/readme.md): a collection of Node.js tools that you can use to generate and verify X.509 certificates and keys.
+- [Manage test CA certificates for samples and tutorials](https://github.com/Azure/azure-iot-sdk-c/blob/master/tools/CACertificates/CACertificateOverview.md): a collection of PowerShell and Bash scripts to:
+  - Create a certificate chain.
+  - Save the certificates as .cer files to upload to your IoT Central application.
+  - Use the verification code from the IoT Central application to generate the verification certificate.
+  - Create leaf certificates for your devices using your device IDs as a parameter to the tool.
+
+## SAS enrollment group
+
+A SAS enrollment group contains group-level SAS keys. Devices can authenticate if they have a valid SAS token that's derived from a group-level SAS key.
+
+To connect a device with device SAS token to your application:
+
+1. Create an _enrollment group_ that uses the **Shared Access Signature (SAS)** attestation type.
+1. Copy the group primary or secondary key from the enrollment group.
+1. Use the Azure CLI to generate a device token from the group key:
+
+    ```azurecli
+    az iot central device compute-device-key --primary-key <enrollment group primary key> --device-id <device ID>
+    ```
+
+1. Use the generated device token when the device connects to your IoT Central application.
+
+> [!NOTE]
+> To use existing SAS keys in your enrollment groups, disable the **Auto generate keys** toggle and manually enter your SAS keys.
+
+## Individual enrollment
+
+Typically, devices connect by using credentials derived from an enrollment group X.509 certificate or SAS key. However, if your devices each have their own credentials, you can use individual enrollments. An individual enrollment is an entry for a single device that's allowed to connect. Individual enrollments can use either X.509 leaf certificates or SAS tokens (from a physical or virtual trusted platform module) as attestation mechanisms. For more information, see [DPS individual enrollment](../../iot-dps/concepts-service.md#individual-enrollment).
+
+> [!NOTE]
+> When you create an individual enrollment for a device, it takes precedence over the default enrollment group options in your IoT Central application.
+
+### Create individual enrollments
+
+IoT Central supports the following attestation mechanisms for individual enrollments:
+
+- **Symmetric key attestation:** Symmetric key attestation is a simple approach to authenticating a device with the DPS instance. To create an individual enrollment that uses symmetric keys, open the **Device connection** page for the device, select **Individual enrollment** as the authentication type, and **Shared access signature (SAS)** as the authentication method. Enter the base64 encoded primary and secondary keys, and save your changes. Use the **ID scope**, **Device ID**, and either the primary or secondary key to connect your device.
+
+    > [!TIP]
+    > For testing, you can use **OpenSSL** to generate base64 encoded keys: `openssl rand -base64 64`
+
+- **X.509 certificates:** To create an individual enrollment with X.509 certificates, open the **Device Connection** page, select **Individual enrollment** as the authentication type, and **Certificates (X.509)** as the authentication method. Device certificates used with an individual enrollment entry have a requirement that the issuer and subject CN are set to the device ID.
+
+    > [!TIP]
+    > For testing, you can use [Tools for the Azure IoT Device Provisioning Device SDK for Node.js](https://github.com/Azure/azure-iot-sdk-node/tree/main/provisioning/tools) to generate a self-signed certificate: `node create_test_cert.js device "mytestdevice"`
+
+- **Trusted Platform Module (TPM) attestation:** A [TPM](../../iot-dps/concepts-tpm-attestation.md) is a type of hardware security module. Using a TPM is one of the most secure ways to connect a device. This article assumes you're using a discrete, firmware, or integrated TPM. Software emulated TPMs are well suited for prototyping or testing, but they don't provide the same level of security as discrete, firmware, or integrated TPMs. Don't use software TPMs in production. To create an individual enrollment that uses a TPM, open the **Device Connection** page, select **Individual enrollment** as the authentication type, and **TPM** as the authentication method. Enter the TPM endorsement key and save the device connection information.
+
+## Automatically register devices
+
+This scenario enables OEMs to mass manufacture devices that can connect without first being registered in an application. An OEM generates suitable device credentials, and configures the devices in the factory.
+
+To automatically register devices that use X.509 certificates:
+
+1. Generate the leaf-certificates for your devices using the root or intermediate certificate you added to your [X.509 enrollment group](#x509-enrollment-group). Use the device IDs as the `CNAME` in the leaf certificates. A device ID can contain letters, numbers, and the `-` character.
+
+1. As an OEM, flash each device with a device ID, a generated X.509 leaf-certificate, and the application **ID scope** value. The device code should also send the model ID of the device model it implements.
+
+1. When you switch on a device, it first connects to DPS to retrieve its IoT Central connection information.
+
+1. The device uses the information from DPS to connect to, and register with, your IoT Central application.
+
+1. The IoT Central application uses the model ID sent by the device to [assign the registered device to a device template](concepts-device-templates.md#assign-a-device-to-a-device-template).
+
+To automatically register devices that use SAS tokens:
+
+1. Copy the group primary key from the **SAS-IoT-Devices** enrollment group:
+
+    :::image type="content" source="media/concepts-device-authentication/group-primary-key.png" alt-text="Group primary key from SAS-IoT-Devices enrollment group":::
+
+1. Use the `az iot central device compute-device-key` command to generate the device SAS keys. Use the group primary key from the previous step. The device ID can contain letters, numbers, and the `-` character:
+
+    ```azurecli
+    az iot central device compute-device-key --primary-key <enrollment group primary key> --device-id <device ID>
+    ```
+
+1. As an OEM, flash each device with the device ID, the generated device SAS key, and the application **ID scope** value. The device code should also send the model ID of the device model it implements.
+
+1. When you switch on a device, it first connects to DPS to retrieve its IoT Central registration information.
+
+1. The device uses the information from DPS to connect to, and register with, your IoT Central application.
+
+1. The IoT Central application uses the model ID sent by the device to [assign the registered device to a device template](concepts-device-templates.md#assign-a-device-to-a-device-template).
+
+## Next steps
+
+Some suggested next steps are to:
+
+- Review [best practices](concepts-device-implementation.md#best-practices) for developing devices.
+- Review some sample code that shows how to use SAS tokens in [Tutorial: Create and connect a client application to your Azure IoT Central application](tutorial-connect-device.md)
+- Learn how to [How to connect devices with X.509 certificates using Node.js device SDK for IoT Central Application](how-to-connect-devices-x509.md)
+- Learn how to [Monitor device connectivity using Azure CLI](./howto-monitor-devices-azure-cli.md)
+- Read about [Azure IoT Edge devices and Azure IoT Central](./concepts-iot-edge.md)