Merge pull request #176547 from dominicbetts/central-msi

Add managed identities to data export

Author: laurabren

articles/iot-central/TOC.yml

@@ -200,6 +200,8 @@
           href: core/howto-control-devices-with-rest-api.md
         - name: Manage jobs
           href: core/howto-manage-jobs-with-rest-api.md
+        - name: Manage applications
+          href: core/howto-manage-iot-central-with-rest-api.md
     - name: Manage your devices
       items:
         - name: Manage devices individually

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

@@ -53,6 +53,7 @@ In an IoT Central application you can manage the following security aspects of y
 
 - [Device connectivity](concepts-get-connected.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.
 - [Organizations](howto-create-organizations.md): Define a hierarchy to manage which users can see which devices in your IoT Central application.
 

articles/iot-central/core/howto-export-data.md

@@ -1,6 +1,6 @@
 ---
 title: Manage IoT Central from Azure CLI or PowerShell | Microsoft Docs
-description: This article describes how to create and manage your IoT Central application using the Azure CLI or PowerShell. You can view, modify, and remove the application using these tools.
+description: This article describes how to create and manage your IoT Central application using the Azure CLI or PowerShell. You can view, modify, and remove the application using these tools. You can also configure a managed system identity that can you can use to setup secure data export.
 services: iot-central
 ms.service: iot-central
 author: dominicbetts
@@ -174,6 +174,30 @@ Remove-AzIotCentralApp -ResourceGroupName "MyIoTCentralResourceGroup" `
 
 ---
 
+## Configure a managed identity
+
+An IoT Central application can use a system assigned [managed identity](../../active-directory/managed-identities-azure-resources/overview.md) to secure the connection to a [data export destination](howto-export-data.md#connection-options).
+
+To enable the managed identity, use either the [Azure portal - Configure a managed identity](howto-manage-iot-central-from-portal.md#configure-a-managed-identity) or the [REST API](howto-manage-iot-central-with-rest-api.md):
+
+:::image type="content" source="media/howto-manage-iot-central-from-cli/managed-identity.png" alt-text="Screenshot showing managed identity in Azure portal.":::
+
+After you enable the managed identity, you can use the CLI to configure the role assignments.
+
+Use the [az role assignment create](/cli/azure/role/assignment#az_role_assignment_create) command to create a role assignment. For example, the following commands first retrieve the principal ID of the managed identity. The second command assigns the `Azure Event Hubs Data Sender` role to the principal ID in the scope of the `MyIoTCentralResourceGroup` resource group:
+
+```azurecli-interactive
+spID=$(az resource list -n myiotcentralapp --query [*].identity.principalId --out tsv)
+az role assignment create --assignee $spID --role "Azure Event Hubs Data Sender" \
+  --scope /subscriptions/<your subscription id>/resourceGroups/MyIoTCentralResourceGroup
+```
+
+To learn more about the role assignments, see:
+
+- [Built-in roles for Azure Event Hubs](../../event-hubs/authenticate-application.md#built-in-roles-for-azure-event-hubs)
+- [Built-in roles for Azure Service Bus](../../service-bus-messaging/authenticate-application.md#azure-built-in-roles-for-azure-service-bus)
+- [Built-in roles for Azure Storage Services](/rest/api/storageservices/authorize-with-azure-active-directory#manage-access-rights-with-rbac)
+
 ## Next steps
 
 Now that you've learned how to manage Azure IoT Central applications from Azure CLI or PowerShell, here is the suggested next step:

articles/iot-central/core/howto-manage-iot-central-from-cli.md

@@ -1,6 +1,6 @@
 ---
 title: Manage and monitor IoT Central in the Azure portal | Microsoft Docs
-description: This article describes how to create, manage, and monitor your IoT Central applications from the Azure portal.
+description: This article describes how to create, manage, and monitor your IoT Central applications and enable managed identities from the Azure portal.
 services: iot-central
 ms.service: iot-central
 author: dominicbetts
@@ -67,6 +67,25 @@ To move the application to a different subscription, select  **change** beside t
 
 ![Management portal: resource management](media/howto-manage-iot-central-from-portal/highlight-subscription.png)
 
+## Configure a managed identity
+
+When you configure a data export in your IoT Central application, you can choose to configure the connection to the destination with a *connection string* or a [managed identity](../../active-directory/managed-identities-azure-resources/overview.md). Using a managed identity is more secure because you don't need to store the credentials for the destination in your IoT Central application. IoT Central currently uses [system-assigned managed identities](../../active-directory/managed-identities-azure-resources/overview.md#managed-identity-types). To create the managed identity for your application, you use either the Azure portal or the REST API.
+
+> [!NOTE]
+> You can only add a managed identity to an IoT Central application that was created in a region. All new applications are created in a region. To learn more, see [Updates](https://azure.microsoft.com/updates/azure-iot-central-new-and-updated-features-august-2021/).
+
+When you configure a managed identity, the configuration includes a *scope* and a *role*:
+
+* The scope defines where you can use the managed identity. For example, you can use an Azure resource group as the scope. In this case, both the IoT Central application and the destination must be in the same resource group.
+* The role defines what permissions the IoT Central application is granted in the destination service. For example, for an IoT Central application to send data to an event hub, the managed identity needs the **Azure Event Hubs Data Sender** role assignment.
+
+[!INCLUDE [iot-central-managed-identity](../../../includes/iot-central-managed-identity.md)]
+
+You can configure role assignments in the Azure portal or use the Azure CLI:
+
+* To learn more about to configure role assignments in the Azure portal for specific destinations, see [Export IoT data to cloud destinations using data export](howto-export-data.md).
+* To learn more about how to configure role assignments using the Azure CLI, see [Manage IoT Central from Azure CLI or PowerShell](howto-manage-iot-central-from-cli.md).
+
 ## Monitor application health
 
 > [!NOTE]

articles/iot-central/core/howto-manage-iot-central-from-portal.md

@@ -0,0 +1,106 @@
+---
+title: Use the REST API to manage and monitor IoT Central applications | Microsoft Docs
+description: This article describes how to create and manage your IoT Central applications with the REST API. The REST API also lets you add a system assigned managed identity to your application.
+services: iot-central
+ms.service: iot-central
+author: dominicbetts
+ms.author: dobett
+ms.date: 10/25/2021
+ms.topic: how-to
+---
+
+# Use the REST API to create and manage IoT Central applications
+
+You can use the [control plane REST API](/rest/api/iotcentral/2021-06-01controlplane/apps) to create and manage IoT Central applications. You can also use the REST API to add a managed identity to your application.
+
+To use this API, you need a bearer token for the `management.azure.com` resource. To get a bearer token, you can use the Azure CLI:
+
+```azurecli
+az account get-access-token --resource https://management.azure.com
+```
+
+## List your applications
+
+To get a list of the IoT Central applications in a subscription:
+
+```http
+GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
+```
+
+To get a list of the IoT Central applications in a resource group:
+
+```http
+GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
+```
+
+You can retrieve the details of an individual application:
+
+```http
+GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
+```
+
+## Create an IoT Central application
+
+To create an IoT Central application with a system assigned [managed identity](../../active-directory/managed-identities-azure-resources/overview.md):
+
+```http
+PUT https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
+```
+
+The following payload shows the configuration for the new application, including the managed identity:
+
+```json
+{
+  "location": "eastus",
+  "sku": {
+    "name": "ST2"
+  },
+  "properties": {
+    "displayName": "Contoso IoT Central App",
+    "subdomain": "my-iot-central-app",
+    "template": "[email protected]"
+  },
+  "identity": {
+    "type": "SystemAssigned"
+  }
+}
+```
+
+## Modify an IoT Central application
+
+You can modify an existing IoT Central application. The following example shows how to change the display name and enable the system assigned managed identity:
+
+```http
+PATCH https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
+```
+
+Use the following payload to change the display name and enable the system assigned managed identity:
+
+```json
+{
+  "properties": {
+    "displayName": "Contoso IoT Central App"
+  },
+  "identity": {
+    "type": "SystemAssigned"
+  }
+}
+```
+
+> [!NOTE]
+> You can only add a managed identity to an IoT Central application that was created in a region. All new applications are created in a region. To learn more, see [Updates](https://azure.microsoft.com/updates/azure-iot-central-new-and-updated-features-august-2021/).
+
+## Delete an IoT Central application
+
+To delete an IoT Central application, use:
+
+```http
+DELETE https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
+```
+
+## Next steps
+
+Now that you've learned how to create and manage Azure IoT Central applications using the REST API, here is the suggested next step:
+
+> [!div class="nextstepaction"]
+> [How to use the IoT Central REST API to manage users and roles](howto-manage-users-roles-with-rest-api.md)

articles/iot-central/core/howto-manage-iot-central-with-rest-api.md

@@ -46,6 +46,12 @@ To learn more, see [X.509 group enrollment](concepts-get-connected.md#x509-group
 
 The administrator can also create and manage the API tokens that a client application uses to authenticate with your IoT Central application. Client applications use the REST API to interact with IoT Central.
 
+For data exports, the administrator can configure [managed identities](../../active-directory/managed-identities-azure-resources/overview.md) to secure the connections to the [export destinations](howto-export-data.md). To learn more, see:
+
+- [Configure a managed identity (Azure portal)](howto-manage-iot-central-from-portal.md#configure-a-managed-identity)
+- [Configure a managed identity (REST API)](howto-manage-iot-central-with-rest-api.md)
+- [Configure a managed identity (Azure CLI)](howto-manage-iot-central-from-cli.md#configure-a-managed-identity)
+
 ## Configure an application
 
 The administrator can configure the behavior and appearance of an IoT Central application. To learn more, see:

articles/iot-central/core/media/howto-manage-iot-central-from-cli/managed-identity.png

@@ -31,7 +31,7 @@ The IoT Central documentation refers to four user roles that interact with an Io
 
 - A _solution builder_ is responsible for [creating an application](quick-deploy-iot-central.md), [configuring rules and actions](quick-configure-rules.md), [defining integrations with other services](quick-export-data.md), and further customizing the application for operators and device developers.
 - An _operator_ [manages the devices](howto-manage-devices-individually.md) connected to the application.
-- An _administrator_ is responsible for administrative tasks such as managing [user roles and permissions](howto-administer.md) within the application.
+- An _administrator_ is responsible for administrative tasks such as managing [user roles and permissions](howto-administer.md) within the application and [configuring managed identities](howto-manage-iot-central-from-portal.md#configure-a-managed-identity) for securing connects to other services.
 - A _device developer_ [creates the code that runs on a device](concepts-telemetry-properties-commands.md) or [IoT Edge module](concepts-iot-edge.md) connected to your application.
 
 ## Create your IoT Central application

articles/iot-central/core/overview-iot-central-admin.md

@@ -0,0 +1,52 @@
+---
+ title: include file
+ description: include file
+ services: iot-central
+ author: dominicbetts
+ ms.service: iot-central
+ ms.topic: include
+ ms.date: 10/20/2021
+ ms.author: dobett
+ ms.custom: include file
+---
+
+Now that you have a destination to export your data to, set up data export in your IoT Central application:
+
+1. Sign in to your IoT Central application.
+
+1. In the left pane, select **Data export**.
+
+    > [!Tip]
+    > If you don't see **Data export** in the left pane, then you don't have permissions to configure data export in your app. Talk to an administrator to set up data export.
+
+1. Select **+ New export**.
+
+1. Enter a display name for your new export, and make sure the data export is **Enabled**.
+
+1. Choose the type of data to export. The following table lists the supported data export types:
+
+    | Data type | Description | Data format |
+    | :------------- | :---------- | :----------- |
+    |  Telemetry | Export telemetry messages from devices in near-real time. Each exported message contains the full contents of the original device message, normalized.   |  [Telemetry message format](#telemetry-format)   |
+    | Property changes | Export changes to device and cloud properties in near-real time. For read-only device properties, changes to the reported values are exported. For read-write properties, both reported and desired values are exported. | [Property change message format](#property-changes-format) |
+    | Device connectivity | Export device connected and disconnected events. | [Device connectivity message format](#device-connectivity-changes-format) |
+    | Device lifecycle | Export device registered, deleted, provisioned, enabled, disabled, displayNameChanged, and deviceTemplateChanged events. | [Device lifecycle changes message format](#device-lifecycle-changes-format) |
+    | Device template lifecycle | Export published device template changes including created, updated, and deleted. | [Device template lifecycle changes message format](#device-template-lifecycle-changes-format) |
+
+1. Optionally, add filters to reduce the amount of data exported. There are different types of filter available for each data export type:
+    <a name="DataExportFilters"></a>
+
+    | Type of data | Available filters|
+    |--------------|------------------|
+    |Telemetry|<ul><li>Filter by device name, device ID, device template, and if the device is simulated</li><li>Filter stream to only contain telemetry that meets the filter conditions</li><li>Filter stream to only contain telemetry from devices with properties matching the filter conditions</li><li>Filter stream to only contain telemetry that has *message properties* meeting the filter condition. *Message properties* (also known as *application properties*) are sent in a bag of key-value pairs on each telemetry message optionally sent by devices that use the device SDKs. To create a message property filter, enter the message property key you're looking for, and specify a condition. Only telemetry messages with properties that match the specified filter condition are exported. [Learn more about application properties from IoT Hub docs](../articles/iot-hub/iot-hub-devguide-messages-construct.md) </li></ul>|
+    |Property changes|<ul><li>Filter by device name, device ID, device template, and if the device is simulated</li><li>Filter stream to only contain property changes that meet the filter conditions</li></ul>|
+    |Device connectivity|<ul><li>Filter by device name, device ID, device template, organizations, and if the device is simulated</li><li>Filter stream to only contain changes from devices with properties matching the filter conditions</li></ul>|
+    |Device lifecycle|<ul><li>Filter by device name, device ID, device template, and if the device is provisioned, enabled, or simulated</li><li>Filter stream to only contain changes from devices with properties matching the filter conditions</li></ul>|
+    |Device template lifecycle|<ul><li>Filter by device template</li></ul>|
+
+1. Optionally, enrich exported messages with extra key-value pair metadata. The following enrichments are available for the telemetry, property changes, device connectivity, and device lifecycle data export types:
+<a name="DataExportEnrichmnents"></a>
+    - **Custom string**: Adds a custom static string to each message. Enter any key, and enter any string value.
+    - **Property**, which adds to each message:
+       - Device metadata such as device name, device template name, enabled, organizations, provisioned, and simulated.
+       - The current device reported property or cloud property value to each message. If the exported message is from a device that doesn't have the specified property, the exported message doesn't get the enrichment.