Set up an Azure Digital Twins instance and authentication (portal)

• Portal
• CLI

This article covers the steps to set up a new Azure Digital Twins instance, including creating the instance and setting up authentication. After completing this article, you'll have an Azure Digital Twins instance ready to start programming against.

This version of this article goes through these steps manually, one by one, using the Azure portal. The Azure portal is a web-based, unified console that provides an alternative to command-line tools.

Full setup for a new Azure Digital Twins instance consists of two parts:

1. Creating the instance
2. Setting up user access permissions: Azure users need to have the Azure Digital Twins Data Owner role on the Azure Digital Twins instance to be able to manage it and its data. In this step, you as an Owner/administrator of the Azure subscription will assign this role to the person who will be managing your Azure Digital Twins instance. This may be yourself or someone else in your organization.

Important

To complete this full article and completely set up a usable instance, you need permissions to manage both resources and user access on the Azure subscription. The first step can be completed by anyone who's able to create resources on the subscription, but the second step requires user access management permissions (or the cooperation of someone with these permissions). You can read more about this in the Prerequisites: Required permissions section for the user access permission step.

Create the Azure Digital Twins instance

In this section, you'll create a new instance of Azure Digital Twins using the Azure portal. Navigate to the portal and log in with your credentials.

1. Once in the portal, start by selecting Create a resource in the Azure services home page menu.

   

2. Search for azure digital twins in the search box, and choose the Azure Digital Twins service from the results.

   Leave the Plan field set to Azure Digital Twins and select the Create button to start creating a new instance of the service.

   

3. On the following Create Resource page, fill in the values given below:

   • Subscription: The Azure subscription you're using
     • Resource group: A resource group in which to deploy the instance. If you don't already have an existing resource group in mind, you can create one here by selecting the Create new link and entering a name for a new resource group
   • Location: An Azure Digital Twins-enabled region for the deployment. For more details on regional support, visit Azure products available by region (Azure Digital Twins).
   • Resource name: A name for your Azure Digital Twins instance. If your subscription has another Azure Digital Twins instance in the region that's already using the specified name, you'll be asked to pick a different name.
   • Grant access to resource: Checking the box in this section will give your Azure account permission to access and manage data in the instance. If you're the one that will be managing the instance, you should check this box now. If it's greyed out because you don't have permission in the subscription, you can continue creating the resource and have someone with the required permissions grant you the role later. For more information about this role and assigning roles to your instance, see the next section, Set up user access permissions.

   

4. When you're finished, you can select Review + create if you don't want to configure any more settings for your instance. Doing so will take you to a summary page, where you can review the instance details you've entered and finish with Create.

   If you do want to configure more details for your instance, the next section describes the remaining setup tabs.

Additional setup options

Here are the additional options you can configure during setup, using the other tabs in the Create Resource process.

• Networking: In this tab, you can enable private endpoints with Azure Private Link to eliminate public network exposure to your instance. For instructions, see Enable private access with Private Link.
• Advanced: In this tab, you can enable a system-assigned managed identity for your instance. When this is enabled, Azure automatically creates an identity for the instance in Microsoft Entra ID, which can be used to authenticate to other services. You can enable that system-assigned managed identity while you're creating the instance here, or later on an existing instance. If you want to enable a user-assigned managed identity instead, you'll need to do it later on an existing instance.
• Tags: In this tab, you can add tags to your instance to help you organize it among your Azure resources. For more about Azure resource tags, see Tag resources, resource groups, and subscriptions for logical organization.

Verify success and collect important values

After finishing your instance setup by selecting Create, you can view the status of your instance's deployment in your Azure notifications along the portal icon bar. The notification will indicate when deployment has succeeded, at which point you can select the Go to resource button to view your created instance.

If deployment fails, the notification will indicate why. Observe the advice from the error message and retry creating the instance.

Tip

Once your instance is created, you can return to its page at any time by searching for the name of your instance in the Azure portal search bar.

From the instance's Overview page, note its Name, Resource group, and Host name. These values are all important and you may need to use them as you continue working with your Azure Digital Twins instance. If other users will be programming against the instance, you should share these values with them.

You now have an Azure Digital Twins instance ready to go. Next, you'll give the appropriate Azure user permissions to manage it.

Set up user access permissions

Azure Digital Twins uses Microsoft Entra ID for role-based access control (RBAC). This means that before a user can make data plane calls to your Azure Digital Twins instance, that user needs to be assigned a role with appropriate permissions for it.

For Azure Digital Twins, this role is Azure Digital Twins Data Owner. You can read more about roles and security in Security for Azure Digital Twins solutions.

Note

This role is different from the Microsoft Entra ID Owner role, which can also be assigned at the scope of the Azure Digital Twins instance. These are two distinct management roles, and Owner does not grant access to data plane features that are granted with Azure Digital Twins Data Owner.

This section will show you how to create a role assignment for a user in your Azure Digital Twins instance, using that user's email in the Microsoft Entra tenant on your Azure subscription. Depending on your role in your organization, you might set up this permission for yourself, or set it up on behalf of someone else who will be managing the Azure Digital Twins instance.

There are two ways to create a role assignment for a user in Azure Digital Twins:

• During Azure Digital Twins instance creation
• Using Azure Identity Management (IAM)

They both require the same permissions.

Prerequisites: Permission requirements

To be able to complete all the following steps, you need to have a role in your subscription that has the following permissions:

• Create and manage Azure resources
• 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 a complete explanation of roles and permissions, including what permissions are included with other roles, visit Azure roles, Microsoft Entra roles, and classic subscription administrator roles in the Azure RBAC documentation.

To view your role in your subscription, visit the subscriptions page in the Azure portal (you can use this link or look for Subscriptions with the portal search bar). Look for the name of the subscription you are using, and view your role for it in the My role column:

If you find that the value is Contributor, or another role that doesn't have the required permissions described above, you can contact the user on your subscription that does have these permissions (such as a subscription Owner or Account admin) and proceed in one of the following ways:

• Request that they complete the role assignment steps on your behalf.
• Request that they elevate your role on the subscription so that you will have the permissions to proceed yourself. Whether this is appropriate depends on your organization and your role within it.

Assign the role during instance creation

While creating your Azure Digital Twins resource through the process described earlier in this article, select the Assign Azure Digital Twins Data Owner Role under Grant access to resource. Doing so will grant yourself full access to the data plane APIs.

If you don't have permission to assign a role to an identity, the box will appear greyed out.

In that case, you can still continue to successfully create the Azure Digital Twins resource, but someone with the appropriate permissions will need to assign this role to you or the person who will be managing the instance's data.

Assign the role using Azure Identity Management (IAM)

You can also assign the Azure Digital Twins Data Owner role using the access control options in Azure Identity Management (IAM).

1. First, open the page for your Azure Digital Twins instance in the Azure portal.

2. Select Access control (IAM).

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

4. Assign the Azure Digital Twins Data Owner role. For detailed steps, see Assign Azure roles using the Azure portal.

   Setting	Value
   Role	Azure Digital Twins Data Owner
   Assign access to	User, group, or service principal
   Members	Search for the name or email address of the user to assign

   

Verify success

You can view the role assignment you've set up under Access control (IAM) > Role assignments. The user should show up in the list with a role of Azure Digital Twins Data Owner.

You now have an Azure Digital Twins instance ready to go, and have assigned permissions to manage it.

Enable/disable managed identity for the instance

This section shows you how to add a managed identity (either system-assigned or user-assigned) to an existing Azure Digital Twins instance. You can also use this page to disable managed identity on an instance that has it already.

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 in the left-hand menu.

3. Use the tabs to select which type of managed identity you want to add or remove.

   1. System-assigned: After selecting this tab, select the On option to turn on this feature, or Off to remove it.

      

      Select the Save button, and Yes to confirm. After system-assigned identity is turned on, more fields will be displayed on this page showing the new identity's Object ID and Permissions (Azure role assignments).

   2. User-assigned (preview): After selecting this tab, select Associate a user-assigned managed identity and follow the prompts to choose an identity to associate with the instance.

      

      Or, if there is already an identity listed here that you want to disable, you can check the box next to it in the list and Remove it.

      Once an identity has been added, you can select its name from the list here to open its details. From its details page, you can view its Object ID and use the left menu to see its Azure role assignments.

Considerations for disabling managed identities

It's important to consider the effects that any changes to the identity or its roles can have on the resources that use it. If you're using managed identities with your Azure Digital Twins endpoints or for data history and the identity is disabled, or a necessary role is removed from it, the endpoint or data history connection can become inaccessible and the flow of events will be disrupted.

Next steps

Test out individual REST API calls on your instance using the Azure Digital Twins CLI commands:

• az dt reference
• Azure Digital Twins CLI command set

Or, see how to connect a client application to your instance with authentication code:

• Write app authentication code