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

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 will 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 Azure PowerShell. Setup can also be completed by using the following alternate instructions:

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.

Prepare your environment

  1. First, choose where to run the commands in this article. You can choose to run Azure PowerShell commands using a local installation of Azure PowerShell, or in a browser window using Azure Cloud Shell.

  2. If you have multiple Azure subscriptions, choose the appropriate subscription in which the resources should be billed. Select a specific subscription using the Set-AzContext cmdlet.

    Set-AzContext -SubscriptionId 00000000-0000-0000-0000-000000000000
    
  3. If this is your first time using Azure Digital Twins with this subscription, you must register the Microsoft.DigitalTwins resource provider. (If you're not sure, it's ok to run it again even if you've done it sometime in the past.)

    Register-AzResourceProvider -ProviderNamespace Microsoft.DigitalTwins
    
  4. Use the following command to install the Az.DigitalTwins PowerShell module.

    Install-Module -Name Az.DigitalTwins
    

Important

While the Az.DigitalTwins PowerShell module is in preview, you must install it separately using the Install-Module cmdlet as described above. After this PowerShell module becomes generally available, it will be part of future Az PowerShell module releases and available by default from within Azure Cloud Shell.

Create the Azure Digital Twins instance

In this section, you will create a new instance of Azure Digital Twins using Azure PowerShell. You'll need to provide:

  • An Azure resource group where the instance will be deployed. If you don't already have an existing resource group, you can create one using the New-AzResourceGroup cmdlet:

    New-AzResourceGroup -Name <name-for-your-resource-group> -Location <region>
    
  • A region for the deployment. To see what regions support Azure Digital Twins, visit Azure products available by region.

  • A name for your instance. The name of the new instance must be unique within the region for your subscription. 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.

Use your values in the following command to create the instance:

New-AzDigitalTwinsInstance -ResourceGroupName <your-resource-group> -ResourceName <name-for-your-Azure-Digital-Twins-instance> -Location <region>

Verify success and collect important values

If the instance was created successfully, the result looks similar to the following output containing information about the resource you've created:

Location   Name                                         Type
--------   ----                                         ----
<region>   <name-for-your-Azure-Digital-Twins-instance> Microsoft.DigitalTwins/digitalTwinsInstances

Next, display the properties of your new instance by running Get-AzDigitalTwinsInstance and piping to Select-Object -Property *, like this:

Get-AzDigitalTwinsInstance -ResourceGroupName <your-resource-group> -ResourceName <name-for-your-Azure-Digital-Twins-instance> |
  Select-Object -Property *

Tip

You can use this command to see all the properties of your instance at any time.

Note the Azure Digital Twins instance's host name, name, and resource group. These are important values that you may need as you continue working with your Azure Digital Twins instance, to set up authentication, and related Azure resources. 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 Azure Active Directory (Azure AD) 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 Azure AD 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 Azure AD 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.

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 Classic subscription administrator roles, Azure roles, and Azure AD 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:

Screenshot of the Subscriptions page in the Azure portal, showing user as an owner.

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

To give a user permissions to manage an Azure Digital Twins instance, you must assign them the Azure Digital Twins Data Owner role within the instance.

First, determine the ObjectId for the Azure AD account of the user that should be assigned the role. You can find this value using the Get-AzAdUser cmdlet, by passing in the user principal name on the Azure AD account to retrieve their ObjectId (and other user information). In most cases, the user principal name will match the user's email on the Azure AD account.

Get-AzADUser -UserPrincipalName <Azure-AD-user-principal-name-of-user-to-assign>

Next, use the ObjectId in the following command to assign the role. The command also requires you to enter the same subscription ID, resource group name, and Azure Digital Twins instance name that you chose earlier when creating the instance. The command must be run by a user with sufficient permissions in the Azure subscription.

$Params = @{
  ObjectId = '<Azure-AD-user-object-ID-of-user-to-assign>'
  RoleDefinitionName = 'Azure Digital Twins Data Owner'
  Scope = '/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DigitalTwins/digitalTwinsInstances/<name-for-your-Azure-Digital-Twins-instance>'
}
New-AzRoleAssignment @Params

The result of this command is outputted information about the role assignment that's been created.

Verify success

One way to check that you've successfully set up the role assignment is to view the role assignments for the Azure Digital Twins instance in the Azure portal. Go to your Azure Digital Twins instance in the Azure portal (you can look it up on the page of Azure Digital Twins instances or search its name in the portal search bar).

Then, view all of its assigned roles under Access control (IAM) > Role assignments. The user should show up in the list with a role of Azure Digital Twins Data Owner.

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.

Next steps

See how to connect a client application to your instance with authentication code: