| title | titleSuffix | description | author | ms.author | ms.date | ms.topic | ms.service | ms.custom |
|---|---|---|---|---|---|---|---|---|
Set up an instance and authentication (portal) |
Azure Digital Twins |
See how to set up an instance of the Azure Digital Twins service using the Azure portal |
baanders |
baanders |
02/24/2022 |
how-to |
digital-twins |
contperf-fy21q2, subject-rbac-steps |
[!INCLUDE digital-twins-setup-selector.md]
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.
[!INCLUDE digital-twins-setup-steps.md]
[!INCLUDE digital-twins-setup-portal.md]
-
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.
:::image type="content" source= "media/how-to-set-up-instance/portal/create-azure-digital-twins-2.png" alt-text="Screenshot of the Create Resource process for Azure Digital Twins in the Azure portal. The described values are filled in.":::
- Subscription: The Azure subscription you're using
-
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.
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-managed identity for your instance that can be used when forwarding events along event routes. For more information about using system-managed identities with Azure Digital Twins, see Security for Azure Digital Twins solutions.
- 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.
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.
:::image type="content" source="media/how-to-set-up-instance/portal/notifications-deployment.png" alt-text="Screenshot of the Azure notifications showing a successful deployment and highlighting the 'Go to resource' button in the Azure portal.":::
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.
:::image type="content" source="media/how-to-set-up-instance/portal/instance-important-values.png" alt-text="Screenshot of the Azure portal, highlighting the important values from the Azure Digital Twins instance's Overview page.":::
You now have an Azure Digital Twins instance ready to go. Next, you'll give the appropriate Azure user permissions to manage it.
[!INCLUDE digital-twins-setup-role-assignment.md]
There are two ways to create a role assignment for a user in Azure Digital Twins:
They both require the same permissions.
[!INCLUDE digital-twins-setup-permissions.md]
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.
:::image type="content" source= "media/how-to-set-up-instance/portal/create-azure-digital-twins-2-role.png" alt-text="Screenshot of the Create Resource process for Azure Digital Twins in the Azure portal. The checkbox under Grant access to resource is highlighted.":::
If you don't have permission to assign a role to an identity, the box will appear greyed out.
:::image type="content" source= "media/how-to-set-up-instance/portal/create-azure-digital-twins-2-role-greyed.png" alt-text="Screenshot of the Create Resource process for Azure Digital Twins in the Azure portal. The checkbox under Grant access to resource is disabled.":::
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.
You can also assign the Azure Digital Twins Data Owner role using the access control options in Azure Identity Management (IAM).
-
First, open the page for your Azure Digital Twins instance in the Azure portal.
-
Select Access control (IAM).
-
Select Add > Add role assignment to open the Add role assignment page.
-
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 
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.
:::image type="content" source="media/how-to-set-up-instance/portal/verify-role-assignment.png" alt-text="Screenshot of the role assignments for an Azure Digital Twins instance in the Azure portal.":::
You now have an Azure Digital Twins instance ready to go, and have assigned permissions to manage it.
Test out individual REST API calls on your instance using the Azure Digital Twins CLI commands:
Or, see how to connect a client application to your instance with authentication code: