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 processes that are covered in this article:

• Turn on Private Link and configure a private endpoint for an Azure Digital Twins instance.
• View, edit, or delete a private endpoint from an Azure Digital Twins instance.
• Disable or enable public network access flags, to restrict API access for an Azure Digital Twins to Private Link connections only.
• Deploy Azure Digital Twins with Private Link using an ARM template
• Troubleshoot the configuration.

Prerequisites

Before you can set up a private endpoint, you need an Azure Virtual Network (VNet) where the endpoint can be deployed. If you don't have a VNet already,follow the Azure Virtual Network quickstart to set one 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 need to use the Azure portal. Otherwise, if you want to enable Private Link on an instance after it's created, you can use either the Azure portal or the Azure CLI. Any of these creation methods give the same configuration options and the same end result for your instance.

Use the tabs in the following sections 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 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.

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 adds 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're 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 returns 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.

Add a private endpoint to an existing instance

In this section, you enable Private Link with a private endpoint for an Azure Digital Twins instance that already exists. This action can be completed in the Azure portal or with the Azure CLI.

Portal

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

2. Select Settings > Networking from 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, Network Interface Name (you can use the default that populates), 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 : Virtual Network > button to go to the next tab.

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

   • Virtual network: Select your virtual network.
   • Subnet: Choose a subnet from your virtual network.
   • Network policy for private endpoints: Enable or disable. For more information, see Manage network policies for private endpoints.
   • Private IP configuration: Select whether to dynamically allocate the IP address or statically allocate it with a private IP.
   • Application security group: Configure security details as needed. For more information, see Application security groups.

   

   Select Next : DNS.

8. Leave the defaults in DNS. Select Next : Tags, then Next : Review + create.

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

When the endpoint is finished deploying, it shows 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. It contains placeholders for the names of your resources.

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, and more private endpoint creation examples, see the az network private-endpoint create reference documentation.

Manage private endpoints

In this section, you see how to view, edit, and delete a private endpoint after it's created. These actions can be done in the Azure portal or with the Azure CLI.

Portal

After a private endpoint is created for your Azure Digital Twins instance, you can view it in the Settings > Networking page for your Azure Digital Twins instance. This page shows 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

After a private endpoint is 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 returns 403, Unauthorized. Otherwise, when the policy is set to disabled and a request is made through a private endpoint, the API call succeeds.

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 Settings > 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 following commands.

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.

Limitations and troubleshooting

A limitation of using Private Link with Azure Digital Twins is that cross-tenant scenarios aren't supported.

For troubleshooting, here are some solutions to common issues:

• Issue: While 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 is 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: While 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?