Enable a managed identity for routing Azure Digital Twins events (preview)

This article describes how to enable a system-assigned identity for an Azure Digital Twins instance (currently in preview), and use the identity 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 Hub, Service Bus destinations, and Azure Storage Container.

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.
  2. 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 Hub, or Azure Service Bus Data Sender role if the endpoint is Service Bus.
  3. Create an endpoint in Azure Digital Twins that can use system-assigned identities for authentication.

Enable system-managed identity for the instance

When you enable a system-assigned identity on your Azure Digital Twins instance, Azure automatically creates an identity for it in Azure Active Directory (Azure AD). That identity can then be used to authenticate to Azure Digital Twins endpoints for event forwarding.

You can enable system-managed identities for an Azure Digital Twins instance as part of the instance's initial setup, or enable it later on an instance that already exists.

Either of these creation methods will give the same configuration options and the same end result for your instance. This section describes how to do both.

Add a system-managed identity during instance creation

In this section, you'll learn how to enable a system-managed identity for an Azure Digital Twins instance while the instance is being created. You can enable the identity whether you're creating the instance with the Azure portal or the Azure CLI. Use the tabs below to select instructions for your preferred experience.

To add a managed identity during instance creation in the portal, begin creating an instance as you normally would.

The system-managed identity option is located in the Advanced tab of instance setup.

In this tab, select the On option for System managed identity to turn on this feature.

Screenshot of the Azure portal showing the Advanced tab of the Create Resource dialog for Azure Digital Twins. System managed identity is turned on.

You can then use the bottom navigation buttons to continue with the rest of instance setup.

Add a system-managed identity to an existing instance

In this section, you'll add a system-managed identity to an Azure Digital Twins instance that already exists. Use the tabs below to select instructions for your preferred experience.

Start by opening the Azure portal in a browser.

  1. Search for the name of your instance in the portal search bar, and select it to view its details.

  2. Select Identity (preview) in the left-hand menu.

  3. On this page, select the On option to turn on this feature.

  4. Select the Save button, and Yes to confirm.

    Screenshot of the Azure portal showing the Identity (preview) page for an Azure Digital Twins instance.

After the change is saved, more fields will appear on this page for the new identity's Object ID and Permissions.

You can copy the Object ID from here if needed, and use the Permissions button to view the Azure roles that are assigned to the identity. To set up some roles, continue to the next section.

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 for forwarding events to supported destinations. This section describes the role options and how to assign them to the system-assigned 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.

Destination Azure role
Azure Event Hubs Azure Event Hubs Data Sender
Azure Service Bus Azure Service Bus Data Sender
Azure storage container Storage Blob Data Contributor

For more about endpoints, routes, and the types of destinations supported for routing in Azure Digital Twins, see Event routes.

Assign the role

Note

This section must be completed by an Azure user who has permissions to manage user access to Azure resources, including granting and delegating permissions. Common roles that meet this requirement are Owner, Account admin, or the combination of User Access Administrator and Contributor. For more information about permission requirements for Azure Digital Twins roles, see Set up an instance and authentication.

Use the tabs below to select instructions for your preferred experience.

To assign a role to the identity, start by opening the Azure portal in a browser.

  1. Navigate to your endpoint resource (your event hub, Service Bus topic, or storage container) by searching for its name in the portal search bar.

  2. Select Access control (IAM).

  3. Select Add > Add role assignment to open the Add role assignment page.

  4. Assign the desired role to the managed identity of your Azure Digital Twins instance, using the information below. For detailed steps, see Assign Azure roles using the Azure portal.

    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.

    Add role assignment page

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 that can use the identity for authentication. This option is only available for Event Hub 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.

Use the tabs below to select instructions for your preferred experience.

Start following the instructions to create an Azure Digital Twins endpoint.

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.

Finish setting up your endpoint and select Save.

Considerations for disabling system-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.

To continue using an endpoint that was set up with a managed identity that's now been disabled, you'll need to delete the endpoint and re-create it with a different authentication type. It may take up to an hour for events to resume delivery to the endpoint after this change.

Next steps

Learn more about managed identities in Azure AD: