Merge pull request #218425 from baanders/11-15-uai

ADT: Add UAI

Author: v-dirichards

articles/digital-twins/concepts-route-events.md

@@ -5,7 +5,7 @@ titleSuffix: Azure Digital Twins
 description: Learn how to route Azure Digital Twins events, both within the service and externally to other Azure services.
 author: baanders
 ms.author: baanders # Microsoft employees only
-ms.date: 07/18/2022
+ms.date: 11/15/2022
 ms.topic: conceptual
 ms.service: digital-twins
 ms.custom: contperf-fy23q1
@@ -63,6 +63,8 @@ When defining an endpoint, you'll need to provide:
 * The primary connection string and secondary connection string to authenticate 
 * The topic path of the endpoint, such as `your-topic.westus2.eventgrid.azure.net`
 
+Optionally, you can choose to create your endpoint with identity-based authentication, to use the endpoint with a [system-assigned or user-assigned managed identity](concepts-security.md#managed-identity-for-accessing-other-resources). This option is only available for Event Hubs and Service Bus-type endpoints (it's not supported for Event Grid).
+
 The endpoint APIs that are available in control plane are:
 * Create endpoint
 * Get list of endpoints

articles/digital-twins/concepts-security.md

@@ -91,11 +91,11 @@ If a user attempts to perform an action not allowed by their role, they may rece
 
 Setting up an [Azure Active Directory (Azure AD)](../active-directory/fundamentals/active-directory-whatis.md) *managed identity* for an Azure Digital Twins instance can allow the instance to easily access other Azure AD-protected resources, such as [Azure Key Vault](../key-vault/general/overview.md). The identity is managed by the Azure platform, and doesn't require you to provision or rotate any secrets. For more about managed identities in Azure AD, see [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md). 
 
-Azure supports two types of managed identities: system-assigned and user-assigned. Currently, Azure Digital Twins supports only *system-assigned identities*. 
+Azure Digital Twins supports both types of managed identities, *system-assigned* and *user-assigned*. 
 
-You can use a system-assigned managed identity for your Azure Digital Instance to authenticate to a [custom-defined endpoint](concepts-route-events.md#create-an-endpoint). Azure Digital Twins supports system-assigned identity-based authentication to endpoints for [Event Hubs](../event-hubs/event-hubs-about.md) and [Service Bus](../service-bus-messaging/service-bus-messaging-overview.md) destinations, and to an [Azure Storage Container](../storage/blobs/storage-blobs-introduction.md) endpoint for [dead-letter events](concepts-route-events.md#dead-letter-events). [Event Grid](../event-grid/overview.md) endpoints are currently not supported for managed identities.
+You can use either of these managed identity types to authenticate to a [custom-defined endpoint](concepts-route-events.md#create-an-endpoint). Azure Digital Twins supports identity-based authentication to endpoints for [Event Hubs](../event-hubs/event-hubs-about.md) and [Service Bus](../service-bus-messaging/service-bus-messaging-overview.md) destinations, and to an [Azure Storage Container](../storage/blobs/storage-blobs-introduction.md) endpoint for [dead-letter events](concepts-route-events.md#dead-letter-events). [Event Grid](../event-grid/overview.md) endpoints are currently not supported for managed identities.
 
-For instructions on how to enable a system-managed identity for Azure Digital Twins and use it to route events, see [Route events with a managed identity](how-to-route-with-managed-identity.md).
+For instructions on how to enable a managed identity for Azure Digital Twins and use it to route events, see [Route events with a managed identity](how-to-route-with-managed-identity.md).
 
 ## Private network access with Azure Private Link
 

articles/digital-twins/how-to-manage-routes.md

@@ -81,10 +81,10 @@ To create a new endpoint, go to your instance's page in the [Azure portal](https
 1. Enter a **Name** for your endpoint and choose the **Endpoint type**.
 
 1. Complete the other details that are required for your endpoint type, including your subscription and the endpoint resources described [above](#prerequisite-create-endpoint-resources).
-    1. For Event Hubs and Service Bus endpoints only, you must select an **Authentication type**. You can use key-based authentication with a pre-created authorization rule, or identity-based authentication if you'll be using the endpoint with a [managed identity](concepts-security.md#managed-identity-for-accessing-other-resources) for your Azure Digital Twins instance. 
-
-    :::image type="content" source="media/how-to-manage-routes/create-endpoint-event-hub-authentication.png" alt-text="Screenshot of creating an endpoint of type Event Hubs in the Azure portal.":::
+    1. For Event Hubs and Service Bus endpoints only, you must select an **Authentication type**. You can use key-based authentication with a pre-created authorization rule, or select the option for a [system-assigned or user-assigned managed identity](concepts-security.md#managed-identity-for-accessing-other-resources).
 
+    :::image type="content" source="media/how-to-manage-routes/create-endpoint-event-hub-authentication.png" alt-text="Screenshot of creating an endpoint of type Event Hubs in the Azure portal." lightbox="media/how-to-manage-routes/create-endpoint-event-hub-authentication.png":::
+    
 1. Finish creating your endpoint by selecting **Save**.
 
 >[!IMPORTANT]
@@ -125,7 +125,7 @@ After successfully running these commands, the Event Grid topic, event hub, or S
 
 #### Create an endpoint with identity-based authentication
 
-You can also create an endpoint that has identity-based authentication, to use the endpoint with a [managed identity](concepts-security.md#managed-identity-for-accessing-other-resources). This option is only available for Event Hubs and Service Bus-type endpoints (it's not supported for Event Grid).
+You can use optional command parameters to create an endpoint that has identity-based authentication, to use the endpoint with a [system-assigned or user-assigned managed identity](concepts-security.md#managed-identity-for-accessing-other-resources). This option is only available for Event Hubs and Service Bus-type endpoints (it's not supported for Event Grid).
 
 For instructions on how to do this, see [Create an endpoint with identity-based authentication](how-to-route-with-managed-identity.md?tabs=cli#create-an-endpoint-with-identity-based-authentication).
 

articles/digital-twins/how-to-route-with-managed-identity.md

@@ -2,7 +2,7 @@
 # Mandatory fields.
 title: Route events with a managed identity
 titleSuffix: Azure Digital Twins
-description: See how to use a system-assigned identity to forward events in Azure Digital Twins.
+description: See how to use a managed identity to forward events in Azure Digital Twins.
 author: baanders
 ms.author: baanders # Microsoft employees only
 ms.date: 11/17/2022
@@ -18,32 +18,32 @@ ms.custom: subject-rbac-steps, contperf-fy21q4, devx-track-azurecli, engagement-
 
 # Enable a managed identity for routing Azure Digital Twins events
 
-This article describes how to use a [system-assigned identity for an Azure Digital Twins instance](concepts-security.md#managed-identity-for-accessing-other-resources) when forwarding events to supported routing destinations. Setting up a managed identity isn't required for routing, but it can help the instance to easily access other Azure AD-protected resources, such as [Event Hubs](../event-hubs/event-hubs-about.md), [Service Bus](../service-bus-messaging/service-bus-messaging-overview.md) destinations, and [Azure Storage Container](../storage/blobs/storage-blobs-introduction.md).
+This article describes how to use a [managed identity for an Azure Digital Twins instance](concepts-security.md#managed-identity-for-accessing-other-resources) when forwarding events to supported routing destinations. Setting up a managed identity isn't required for routing, but it can help the instance to easily access other Azure AD-protected resources, such as [Event Hubs](../event-hubs/event-hubs-about.md), [Service Bus](../service-bus-messaging/service-bus-messaging-overview.md) destinations, and [Azure Storage Container](../storage/blobs/storage-blobs-introduction.md). Managed identities can be *system-assigned* or *user-assigned*.
 
 Here are the steps that are covered in this article: 
 
-1. Create an Azure Digital Twins instance with a system-assigned identity or enable system-assigned identity on an existing Azure Digital Twins instance. 
+1. Create an Azure Digital Twins instance with a managed identity, or enable managed identity on an existing Azure Digital Twins instance. 
 1. Add an appropriate role or roles to the identity. For example, assign the **Azure Event Hub Data Sender** role to the identity if the endpoint is Event Hubs, or **Azure Service Bus Data Sender role** if the endpoint is Service Bus.
-1. Create an endpoint in Azure Digital Twins that can use system-assigned identities for authentication.
+1. Create an endpoint in Azure Digital Twins that can use managed identities for authentication.
 
 ## Create an Azure Digital Twins instance with a managed identity
 
-If you already have an Azure Digital Twins instance, ensure that you've enabled a [system-managed identity](how-to-set-up-instance-cli.md#enabledisable-system-managed-identity-for-the-instance) for it.
+If you already have an Azure Digital Twins instance, ensure that you've enabled a [managed identity](how-to-set-up-instance-cli.md#enabledisable-managed-identity-for-the-instance) for it.
 
-If you don't have an Azure Digital Twins instance, follow the instructions in [Create the instance with a system-managed identity](how-to-set-up-instance-cli.md#create-the-instance-with-a-system-managed-identity) to create an Azure Digital Twins instance with a managed identity for the first time.
+If you don't have an Azure Digital Twins instance, follow the instructions in [Create the instance with a managed identity](how-to-set-up-instance-cli.md#create-the-instance-with-a-managed-identity) to create an Azure Digital Twins instance with a managed identity for the first time.
 
 Then, make sure you have *Azure Digital Twins Data Owner* role on the instance. You can find instructions in [Set up user access permissions](how-to-set-up-instance-cli.md#set-up-user-access-permissions).
 
 ## Assign Azure roles to the identity 
 
-Once a system-assigned identity is created for your Azure Digital Twins instance, you'll need to assign it appropriate roles to authenticate with different types of [endpoints](concepts-route-events.md) for routing events to supported destinations. This section describes the role options and how to assign them to the system-assigned identity.
+Once a managed identity is created for your Azure Digital Twins instance, you'll need to assign it appropriate roles to authenticate with different types of [endpoints](concepts-route-events.md) for routing events to supported destinations. This section describes the role options and how to assign them to the managed identity.
 
 >[!NOTE]
 > This is an important step—without it, the identity won't be able to access your endpoints and events won't be delivered.
 
 ### Supported destinations and Azure roles 
 
-Here are the minimum roles that an identity needs to access an endpoint, depending on the type of destination. Roles with higher permissions (like Data Owner roles) will also work.
+Here are the minimum roles that your Azure Digital Twins identity needs to access an endpoint, depending on the type of destination. Roles with higher permissions (like Data Owner roles) will also work.
 
 | Destination | Azure role |
 | --- | --- |
@@ -73,17 +73,17 @@ To assign a role to the identity, start by opening the [Azure portal](https://po
 
     | Setting | Value |
     | --- | --- |
-    | Role | Select the desired role from the dropdown menu. |
-    | Assign access to | Under **System assigned managed identity**, select **Digital Twins**. |
-    | Members | Select the managed identity of your Azure Digital Twins instance that's being assigned the role. The name of the managed identity matches the name of the instance, so choose the name of your Azure Digital Twins instance. |
+    | Role | Select the desired role from the options. |
+    | Assign access to | **Managed identity** |
+    | Members | Select the user-assigned or system-assigned managed identity of your Azure Digital Twins instance that's being assigned the role. A user-assigned identity will have the name you chose when you created the identity, and a system-assigned identity will have a name that matches the name of your Azure Digital Twins instance. |
 
    :::image type="content" source="../../includes/role-based-access-control/media/add-role-assignment-page.png" alt-text="Screenshot of the 'Add role assignment' page for an Azure Digital Twins instance." lightbox="../../includes/role-based-access-control/media/add-role-assignment-page.png":::
 
 # [CLI](#tab/cli)
 
 You can add the `--scopes` parameter onto the `az dt create` command to assign the identity to one or more scopes with a specified role. The command with this parameter can be used when first creating the instance, or later by passing in the name of an instance that already exists.
 
-Here's an example that creates an instance with a system managed identity, and assigns that identity a custom role called `MyCustomRole` in an event hub.
+Here's an example that creates an instance with a system-assigned managed identity, and assigns that identity a custom role called `MyCustomRole` in an event hub.
 
 ```azurecli-interactive
 az dt create --dt-name <new-instance-name> --resource-group <resource-group> --assign-identity --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole
@@ -97,7 +97,7 @@ You can also use the [az role assignment](/cli/azure/role/assignment) command gr
 
 ## Create an endpoint with identity-based authentication
 
-After setting up a system-managed identity for your Azure Digital Twins instance and assigning it the appropriate role(s), you can create Azure Digital Twins [endpoints](how-to-manage-routes.md#create-an-endpoint-for-azure-digital-twins) that can use the identity for authentication. This option is only available for Event Hubs and Service Bus-type endpoints (it's not supported for Event Grid).
+After setting up a managed identity for your Azure Digital Twins instance and assigning it the appropriate role(s), you can create Azure Digital Twins [endpoints](how-to-manage-routes.md#create-an-endpoint-for-azure-digital-twins) that can use the identity for authentication. This option is only available for Event Hubs and Service Bus-type endpoints (it's not supported for Event Grid).
 
 >[!NOTE]
 > You cannot edit an endpoint that has already been created with key-based identity to change to identity-based authentication. You must choose the authentication type when the endpoint is first created.
@@ -108,25 +108,36 @@ Use the tabs below to select instructions for your preferred experience.
 
 Start following the [instructions to create an Azure Digital Twins endpoint](how-to-manage-routes.md#create-an-endpoint-for-azure-digital-twins).
 
-When you get to the step of completing the details required for your endpoint type, make sure to select **Identity-based** for the Authentication type.
+When you get to the step of completing the details required for your endpoint type, select either **System-assigned** or **User-assigned (preview)** for the Authentication type.
 
 :::image type="content" source="media/how-to-manage-routes/create-endpoint-event-hub-authentication.png" alt-text="Screenshot of creating an endpoint of type Event Hubs." lightbox="media/how-to-manage-routes/create-endpoint-event-hub-authentication.png":::
 
 Finish setting up your endpoint and select **Save**.
 
 # [CLI](#tab/cli)
 
-Creating the endpoint with the CLI is done by adding a `--auth-type` parameter to the `az dt endpoint create` command that's used to create the endpoint. (For more information about this command, see its [reference documentation](/cli/azure/dt/endpoint/create) or the [general instructions for setting up an Azure Digital Twins endpoint](how-to-manage-routes.md#create-the-endpoint)).
+Managed identities are added to an endpoint by adding a `--auth-type` parameter to the `az dt endpoint create` command that's used to create the endpoint. (For more information about this command, see its [reference documentation](/cli/azure/dt/endpoint/create) or the [general instructions for setting up an Azure Digital Twins endpoint](how-to-manage-routes.md#create-the-endpoint)).
 
-To create an endpoint that uses identity-based authentication, specify the `IdentityBased` authentication type with the  `--auth-type` parameter. The example below illustrates this functionality for an Event Hubs endpoint.
+Use the CLI command below for your chosen type of managed identity.
+
+#### System-assigned identity command
+
+To create an endpoint that uses system-assigned authentication, specify the `IdentityBased` authentication type with the  `--auth-type` parameter. The example below illustrates this functionality for an Event Hubs endpoint.
 
 ```azurecli-interactive
-az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --auth-type IdentityBased --dt-name <instance-name>
+az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased
 ```
 
+#### User-assigned identity command
+
+To create an endpoint that uses user-assigned identity authentication, specify the user assigned identity resource ID with the  `--user` parameter. The example below illustrates this functionality for an Event Hubs endpoint.
+
+```azurecli-interactive
+az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>
+```
 ---
 
-## Considerations for disabling system-managed identities
+## Considerations for disabling managed identities
 
 Because an identity is managed separately from the endpoints that use it, it's important to consider the effects that any changes to the identity or its roles can have on the endpoints in your Azure Digital Twins instance. If the identity is disabled, or a necessary role for an endpoint is removed from it, the endpoint can become inaccessible and the flow of events will be disrupted.