Enable private access to Azure Digital Twins using Private Link

By using Azure Digital Twins together with Azure Private Link, you can enable private endpoints for your Azure Digital Twins instance, to eliminate public exposure and allow clients located in your virtual network to securely access the instance over Private Link. For more information about this security strategy for Azure Digital Twins, see Private Link with a private endpoint for an Azure Digital Twins instance.

Here are the steps that are covered in this article:

1. Turn on Private Link and configure a private endpoint for an Azure Digital Twins instance.
2. View, edit, or delete a private endpoint from an Azure Digital Twins instance.
3. Disable or enable public network access flags, to restrict API access for an Azure Digital Twins to Private Link connections only.

This article also contains information for deploying Azure Digital Twins with Private Link using an ARM template, and troubleshooting the configuration.

Prerequisites

Before you can set up a private endpoint, you'll need an Azure Virtual Network (VNet) where the endpoint can be deployed. If you don't have a VNet already, you can follow one of the Azure Virtual Network quickstarts to set this up.

Add private endpoints to Azure Digital Twins

You can use either the Azure portal or the Azure CLI to turn on Private Link with a private endpoint for an Azure Digital Twins instance.

If you want to set up Private Link as part of the instance's initial setup, you'll need to use the Azure portal. Otherwise, if you want to enable Private Link on an instance after it's been created, you can use either the Azure portal or the Azure CLI. Any of these creation methods will give the same configuration options and the same end result for your instance.

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

Tip

You can also set up a Private Link endpoint through the Private Link service, instead of through your Azure Digital Twins instance. This also gives the same configuration options and the same end result.

For more information on setting up Private Link resources, see Private Link documentation for the Azure portal, Azure CLI, Azure Resource Manager, or PowerShell.

Add a private endpoint during instance creation

In this section, you'll create a private endpoint with Private Link as part of the initial setup of an Azure Digital Twins instance. This action can only be done in the Azure portal.

Portal

This section describes how to turn on Private Link while setting up an Azure Digital Twins instance in the Azure portal.

The Private Link options are located in the Networking tab of instance setup.

1. Begin setting up an Azure Digital Twins instance in the Azure portal. For instructions, see Set up an instance and authentication.

2. When you reach the Networking tab of instance setup, you can enable private endpoints by selecting the Private endpoint option for the Connectivity method.

   Doing so will add a section called Private endpoint connections where you can configure the details of your private endpoint. Select the + Add button to continue.

   

3. In the Create private endpoint page that opens, enter the details of a new private endpoint.

   

   1. Fill in selections for your Subscription and Resource group. Set the Location to the same location as the VNet you'll be using. Choose a Name for the endpoint, and for Target sub-resources select API.

   2. Next, select the Virtual network and Subnet you want to use to deploy the endpoint.

   3. Lastly, select whether to Integrate with private DNS zone. You can use the default of Yes or, for help with this option, you can follow the link in the portal to learn more about private DNS integration.

   4. After filling out the configuration options, select OK to finish.

4. Once you finish this process, the portal will return you to the Networking tab of the Azure Digital Twins instance setup. Verify that your new endpoint is visible under Private endpoint connections.

   

5. Use the bottom navigation buttons to continue with the rest of instance setup.

CLI

You can't add a Private Link endpoint during instance creation using the Azure CLI.

You can switch to the Azure portal to add the endpoint during instance creation, or continue to the next section to use the CLI to add a private endpoint after the instance has been created.

Add a private endpoint to an existing instance

In this section, you'll enable Private Link with a private endpoint for an Azure Digital Twins instance that already exists.

Portal

1. First, navigate to the Azure portal in a browser. Bring up your Azure Digital Twins instance by searching for its name in the portal search bar.

2. Select Networking in the left-hand menu.

3. Switch to the Private endpoint connections tab.

4. Select + Private endpoint to open the Create a private endpoint setup.

   

5. In the Basics tab, enter or select the Subscription and Resource group of your project, and a Name and Region for your endpoint. The region needs to be the same as the region for the VNet you're using.

   

   When you're finished, select the Next : Resource > button to go to the next tab.

6. In the Resource tab, enter or select this information:

   • Connection method: Select Connect to an Azure resource in my directory to search for your Azure Digital Twins instance.
   • Subscription: Enter your subscription.
   • Resource type: Select Microsoft.DigitalTwins/digitalTwinsInstances
   • Resource: Select the name of your Azure Digital Twins instance.
   • Target sub-resource: Select API.

   

   When you're finished, select the Next : Configuration > button to go to the next tab.

7. In the Configuration tab, enter or select this information:

   • Virtual network: Select your virtual network.
   • Subnet: Choose a subnet from your virtual network.
   • Integrate with private DNS zone: Select whether to Integrate with private DNS zone. You can use the default of Yes or, for help with this option, you can follow the link in the portal to learn more about private DNS integration. If you select Yes, you can leave the default configuration information.

   

   When you're finished, you can select the Review + create button to finish setup.

8. In the Review + create tab, review your selections and select the Create button.

When the endpoint is finished deploying, it should show up in the private endpoint connections for your Azure Digital Twins instance.

CLI

To create a private endpoint and link it to an Azure Digital Twins instance using the Azure CLI, use the az network private-endpoint create command. Identify the Azure Digital Twins instance by using its fully qualified ID in the --private-connection-resource-id parameter.

Here's an example that uses the command to create a private endpoint, with only the required parameters.

az network private-endpoint create --connection-name <private-link-service-connection> --name <name-for-private-endpoint> --resource-group <resource-group> --subnet <subnet-ID> --private-connection-resource-id "/subscriptions/<subscription-ID>/resourceGroups/<resource-group>/providers/Microsoft.DigitalTwins/digitalTwinsInstances/<Azure-Digital-Twins-instance-name>" 

For a full list of required and optional parameters, as well as more private endpoint creation examples, see the az network private-endpoint create reference documentation.

Manage private endpoints

In this section, you'll see how to view, edit, and delete a private endpoint after it's been created.

Portal

Once a private endpoint has been created for your Azure Digital Twins instance, you can view it in the Networking tab for your Azure Digital Twins instance. This page will show all the private endpoint connections associated with the instance.

Select the endpoint to view its information in detail, make changes to its configuration settings, or delete the connection.

Tip

The endpoint can also be viewed from the Private Link Center in the Azure portal.

CLI

Once a private endpoint has been created for your Azure Digital Twins instance, you can use the az dt network private-endpoint connection commands to continue managing private endpoint connections with respect to the instance. Operations include:

• Show a private endpoint connection
• Set the state of the private endpoint connection
• Delete the private endpoint connection
• List all the private endpoint connections for an instance

For more information and examples, see the az dt network private-endpoint reference documentation.

Get more Private Link information

You can get more information about the Private Link status of your instance with the az dt network private-link commands. Operations include:

• List private links associated with an Azure Digital Twins instance
• Show a private link associated with the instance

For more information and examples, see the az dt network private-link reference documentation.

Disable / enable public network access flags

You can configure your Azure Digital Twins instance to deny all public connections and allow only connections through private access endpoints to enhance the network security. This action is done with a public network access flag.

This policy allows you to restrict API access to Private Link connections only. When the public network access flag is set to disabled, all REST API calls to the Azure Digital Twins instance data plane from the public cloud will return 403, Unauthorized. Otherwise, when the policy is set to disabled and a request is made through a private endpoint, the API call will succeed.

You can update the value of the network flag using the Azure portal, Azure CLI, or ARMClient command tool.

Portal

To disable or enable public network access in the Azure portal, open the portal and navigate to your Azure Digital Twins instance.

1. Select Networking in the left-hand menu.

2. In the Public access tab, set Allow public network access to either Disabled or All networks.

   

   Select Save.

CLI

In the Azure CLI, you can disable or enable public network access by adding a --public-network-access parameter to the az dt create command. While this command can also be used to create a new instance, you can use it to edit the properties of an existing instance by providing it the name of an instance that already exists. (For more information about this command, see its reference documentation or the general instructions for setting up an Azure Digital Twins instance).

To disable public network access for an Azure Digital Twins instance, use the --public-network-access parameter like this:

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --public-network-access Disabled

To enable public network access on an instance where it's currently disabled, use the following similar command:

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --public-network-access Enabled

ARMClient

With the ARMClient command tool, public network access is enabled or disabled using the commands below.

To disable public network access:

armclient login 

armclient PATCH /subscriptions/<your-Azure-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.DigitalTwins/digitalTwinsInstances/<your-Azure-Digital-Twins-instance>?api-version=2020-12-01 "{ 'properties': { 'publicNetworkAccess': 'disabled' } }"  

To enable public network access:

armclient login 

armclient PATCH /subscriptions/<your-Azure-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.DigitalTwins/digitalTwinsInstances/<your-Azure-Digital-Twins-instance>?api-version=2020-12-01 "{ 'properties': { 'publicNetworkAccess': 'enabled' } }"  

Deploy with ARM templates

You can also set up Private Link with Azure Digital Twins using an ARM template.

For a sample template that allows an Azure function to connect to Azure Digital Twins through a Private Link endpoint, see Azure Digital Twins with Azure function and Private Link (ARM template).

This template creates an Azure Digital Twins instance, a virtual network, an Azure function connected to the virtual network, and a Private Link connection to make the Azure Digital Twins instance accessible to the Azure function through a private endpoint.

Troubleshoot

Here are some common issues that might arise when using Private Link with Azure Digital Twins.

• Issue: When trying to access Azure Digital Twins APIs, you see an HTTP error code 403 with the following error in the response body:

  {
      "statusCode": 403,
      "message": "Public network access disabled by policy."
  }
  

  Resolution: This error occurs when publicNetworkAccess has been disabled for the Azure Digital Twins instance and API requests are expected to come through Private Link, but the call was routed through the public network (possibly over a load balancer configured for a virtual network). Make sure that your API client is resolving the private IP for the private endpoint when trying to access the API through the endpoint hostname.

  To facilitate hostname resolution to the private IP of the private endpoint in a subnet, you can configure a private DNS zone. Verify that the private DNS zone is correctly linked to the virtual network and uses the right zone name, such as privatelink.digitaltwins.azure.net.

• Issue: When trying to access Azure Digital Twins through a private endpoint, the connection times out.

  Resolution: Verify that there are no network security group rules that prohibit the client from communicating to the private endpoint and its subnet. Communication on TCP port 443 must be permitted between the client's source IP address/subnet, and the private endpoint destination IP address/subnet.

For more Private Link troubleshooting suggestions, see Troubleshoot Azure Private Endpoint connectivity problems.

Next steps

Quickly set up a protected environment with Private Link using an ARM template: Azure Digital Twins with Azure function and Private Link.

Or, learn more about Private Link for Azure: What is Azure Private Link service?