How to: Configure private networks for Azure Cosmos DB Fabric Mirroring (Preview)

This guide helps you configure Azure Cosmos DB accounts that use virtual networks or private endpoints to work with Microsoft Fabric mirroring. You can mirror data from Azure Cosmos DB accounts configured with virtual network (VNET) or private endpoints, while maintaining enhanced network security.

Prerequisites

• An existing Azure Cosmos DB for NoSQL account using virtual network or private endpoint connectivity.
• An existing Fabric capacity.
• PowerShell with Azure PowerShell modules (Az.Accounts, Az.CosmosDB, Az.Network) installed.
• The Azure Cosmos DB for NoSQL account must be configured for Fabric mirroring including:
  1. Continuous Backup with 7 or 30 day retention.
  2. Entra ID authentication enabled with...
  3. Built-in Data Contributor RBAC Policy - See assign-contibutor-rbac.ps1
  4. Custom Mirroring RBAC Policy - See assign-mirroring-rbac.ps1
• The Cosmos DB account and Fabric workspace must be in the same Azure region. To verify your Fabric workspace region:
  1. Open your Fabric workspace
  2. Navigate to Workspace settings → License info
  3. Note the region of the Fabric capacity
  4. Ensure this matches your Cosmos DB account region
• The user configuring private networks for Cosmos DB Mirroring should either be an Azure subscription owner or have Contributor permissions on the Cosmos DB account with RBAC assignment permissions on the subscription. To learn how to assign this role to a user, see Assign a user as an administrator of an Azure subscription with conditions.

Overview of network configuration options

Azure Cosmos DB supports two primary network security configurations for mirroring:

• Virtual network: Restrict access to your Azure Cosmos DB account to specific virtual network subnets. With this configuration, you maintain "Selected networks" access and add the necessary Azure service IP addresses.
• Private endpoint: Provide a private IP address from your virtual network to your Azure Cosmos DB account, keeping all traffic on the Microsoft backbone network. This requires temporarily enabling public access to specific Azure services during mirroring setup.

Both configurations use the Network ACL feature to allow Fabric to access your Cosmos DB account as a trusted workspace authorizing specific Fabric workspace IDs.

Quick start: Automated configuration with PowerShell

For a streamlined setup experience, use the provided PowerShell script that automates all configuration steps. The script performs the following actions:

1. Configures RBAC permissions - Creates a custom role with required read permissions for Fabric mirroring and assigns it to your Fabric workspace identity. Also applies the Built-in Data Contributor if not already configured.
2. Sets up IP firewall rules - Enables public access and adds region specific IP Firewall rules for DataFactory and PowerQueryOnline to allow these services to initialize mirroring. (Public access is disabled after mirroring successfully configured)
3. Enables Network ACL capability - Activates the EnableFabricNetworkAclBypass feature on your Cosmos DB account to allow a Fabric workspace to authenticate as a trusted resource.
4. Configures trusted workspace - Authorizes your Fabric workspace ID.
5. Disables public access - For private endpoint configurations only. If public access was enabled previously, it leaves it enabled.

Run the automated script

1. Download the PowerShell script ps-account-setup-cosmos-pe-mirroring.ps1.

2. Open PowerShell as Administrator and run the following commands to authenticate and set your subscription context:

   # Connect to Azure
   Connect-AzAccount
   
   # Set your subscription context
   Set-AzContext -Subscription "<subscriptionId>"
   

3. Run the private network configuration script to set up mirroring

   .\ps-account-setup-cosmos-pe-mirroring.ps1
   

4. Provide the following information when prompted:

   • Azure Subscription ID
   • Resource Group name
   • Cosmos DB account name
   • Fabric Workspace name
   • Azure region for service tag filtering (for example, westus3)

5. The script guides you through each step with confirmation prompts. Review and confirm each action.

6. When prompted, create your mirrored database in Fabric while the account is temporarily accessible.

7. After mirroring is created, return to the script and press Y to have it restore your original network security settings including disabling public access for private endpoints or restoring your original IP firewall rules for Virtual Network.

Manual configuration

If you prefer manual configuration or need to understand the detailed steps, follow these configuration steps:

Authenticate to Azure

Before beginning the configuration steps, connect to your Azure account:

1. Open PowerShell.

2. Run the following commands to authenticate and set your subscription context:

   # Connect to Azure
   Connect-AzAccount
   
   # Set your subscription context
   Set-AzContext -Subscription "<subscriptionId>"
   

Step 1: Configure RBAC permissions

Configure the required RBAC permissions for both the user setting up mirroring and the Fabric workspace:

Assign Cosmos DB data contributor permissions to the user

To apply the required Data Contributor RBAC policy, use the provided script assign-contibutor-rbac.ps1 to automate the user's identity role assignment.

To run these commands manually:

1. Get your principal ID.

   $currentUser = Get-AzADUser -SignedIn
   $currentUser.Id
   

2. Apply the Data Contributor RBAC policy.

   New-AzCosmosDBSqlRoleAssignment `
       -AccountName <accountName> `
       -ResourceGroupName <resourceGroupName> `
       -RoleDefinitionName "Cosmos DB Built-in Data Contributor" `
       -Scope "/" `
       -PrincipalId <principalId>
   

Assign Cosmos DB metadata and analytics reader permissions to the user

To apply the required mirroring RBAC policy, use the provided script ps-account-rbac-mirroring.ps1 to automate the user's identity role assignment.

The script ensures the following data plane permissions are added: - Microsoft.DocumentDB/databaseAccounts/readMetadata - Microsoft.DocumentDB/databaseAccounts/readAnalytics

To learn more about applying custom RBAC polices, refer to Grant data plane role-base access.

Step 2: Configure network access

Configure network access to allow Fabric services to connect to your Cosmos DB account.

[IMPORTANT!] Manual configuration using Azure Service IP Ranges requires downloading and applying over 1200 IP addresses for PowerQueryOnline from the Azure IP Ranges and Service Tags file. We recommend using the PowerShell script above to handle the Cosmos network configuration, or use Network Security Perimeter with Service Tags (see below).

Add Azure service IP addresses

Choose one of the following methods to allow Fabric service access:

Option A: Manual IP Address Configuration

1. Download the latest Azure Service Tags JSON file from Azure IP Ranges and Service Tags.

2. Extract IPv4 address ranges for DataFactory for your Fabric capacity region:

   • DataFactory.<region> - For example, DataFactory.WestUS3

3. Extract ALL IPv4 address ranges for PowerQueryOnline

   • PowerQueryOnline.<region> For example, PowerQueryOnline.WestUS3, PowerQueryOnline.EastUS, etc.
   • Also include PowerQueryOnline with no region appended in the name.

   [IMPORTANT!] This will result in over 1200 IP addresses. You can choose to remove duplicates which will result in approximately 400+ IPv4 addresses that manually need to be added to the Cosmos DB IP Firewall rules. The PowerShell script above can handle this automatically or use Network Security Perimeter with Service Tags (see below).

4. In the Azure portal, navigate to your Azure Cosmos DB account.

5. In the resource menu, select Networking under Settings.

6. Under Firewall, add the IP address ranges you extracted.

   Important

   You must add all IPv4 address ranges for the DataFactory and PowerQueryOnline services. Adding only a subset of addresses may cause connectivity issues. The provided PowerShell script automates this process.

7. Ensure your existing network rules (virtual network rules or private endpoint connections) remain in place.

8. Select Save to apply your changes.

Option B: Network Security Perimeter with Service Tags (Preview)

Use Network Security Perimeter (NSP) to allow access using service tags, which automatically includes all IP addresses for the services without manual entry.

1. In the Azure portal, navigate to your Azure Cosmos DB account.

2. In the resource menu, select Networking under Settings.

3. Select Network Security Perimeter at the top of the page.

4. Create or select an existing Network Security Perimeter.

5. Add the following service tags to your inbound access rules for your Fabric capacity region:

   • DataFactory.<region> - For example, DataFactory.WestUS3
   • PowerQueryOnline.<region> - For example, PowerQueryOnline.WestUS3

6. Ensure your existing network rules (virtual network rules or private endpoint connections) remain in place.

7. Select Save to apply your changes.

Step 3: Enable Network ACL capability

Enable the Fabric Network ACL capability on your Cosmos DB account:

1. Open PowerShell.

2. Run the following commands to enable the capability:

   $cosmos = Get-AzResource -ResourceGroupName <resourceGroup> -Name <accountName> -ResourceType "Microsoft.DocumentDB/databaseAccounts"
   $cosmos.Properties.capabilities += @{ name = "EnableFabricNetworkAclBypass" }
   $cosmos | Set-AzResource -UsePatchSemantics -Force
   

Step 4: Configure the trusted Fabric workspace

Authorize your Fabric workspace as a trusted resource:

1. Get your Fabric workspace ID from the Fabric portal:

   • Navigate to your workspace in Fabric portal
   • Look at the browser URL for a segment like /groups/{GUID}/.
   • That GUID is your Workspace ID.

   For example:

   https://app.fabric.com/groups/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4/list?experience=fabric-developer

   The Workspace ID in this example is d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4.

   

2. Get your Fabric tenant ID.

   • Navigate to your Fabric portal
   • Click your avatar at the top right of the Fabric Portal
   • Hover over the information icon next to your tenant name

3. Run the following PowerShell command:

   Update-AzCosmosDBAccount `
   -ResourceGroupName <CosmosDbResourceGroupName> `
   -Name <CosmosDbAccountName> `
   -NetworkAclBypass AzureServices `
   -NetworkAclBypassResourceId "/tenants/<FabricTenantId>/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Fabric/providers/Microsoft.Fabric/workspaces/<FabricWorkspaceId>"
   

Step 5: Create the mirrored database

Create your mirrored database in Fabric:

1. Navigate to the Fabric portal.

2. Open the workspace you configured for trusted access.

3. In the navigation menu, select Create.

4. Locate the Mirror data section, and then select Mirrored Azure Cosmos DB.

5. Provide a name for the mirrored database and then select Create.

6. In the New connection section, select Azure Cosmos DB v2.

   

7. Provide credentials for the Azure Cosmos DB for NoSQL account:

   Account credentials	Value
   Azure Cosmos DB endpoint	URL endpoint for the source account.
   Connection name	Unique name for the connection.
   Authentication kind	Select Organizational account.
   Organizational account	Access token from Microsoft Entra ID.

   Note

   Private network support for Cosmos DB mirroring is only available for OAuth-based authentication.

   

8. Select Connect.

9. Select a database to mirror. Optionally, select specific containers to mirror.

10. Select Connect to start the mirroring process.

    

11. Monitor replication to verify the connection is working properly.

Step 6: Disable public network access (Optional for private endpoints)

After successfully creating the mirror and verifying replication, disable public network access to restore your private endpoint-only configuration. You can do this using either the Azure portal or PowerShell:

Option A: Azure portal

1. Navigate to your Azure Cosmos DB account in the Azure portal.

2. In the resource menu, select Networking under Settings.

3. Under Public network access, select Disabled.

4. Select Save to apply your changes.

Option B: PowerShell

1. Open PowerShell.

2. Run the following command:

   Update-AzCosmosDBAccount `
       -ResourceGroupName <resourceGroup> `
       -Name <accountName> `
       -PublicNetworkAccess "Disabled"
   

After disabling public access, verify that mirroring continues to work. The Network ACL allows your Fabric workspace to access your account through the authorized workspace even with public access disabled.

Verify the mirroring connection

After configuring your mirrored database, verify that the connection is working properly:

1. In your mirrored database, select Monitor replication to see the replication status.

2. After a few minutes, the status should change to Running, which indicates that the containers are being synchronized.

3. Verify that data is being replicated by checking the last refresh and total rows columns.

Limitations and considerations

When using virtual networks or private endpoints with Azure Cosmos DB mirroring, be aware of these limitations:

• The target Fabric workspace region must be the same as the source Azure Cosmos DB Account region.
• The user configuring private networks for Cosmos DB Mirroring must be an Azure subscription owner. To learn how to assign this role to a user, see Assign a user as an administrator of an Azure subscription with conditions.
• Private network support for Cosmos DB mirroring is only available for OAuth-based authentication.
• When using Microsoft Entra ID authentication, ensure that the required RBAC permissions are configured. For more information, see security limitations.
• The EnableFabricNetworkAclBypass capability must be enabled on your Cosmos DB account before configuring the Network ACL.
• Network ACL configuration is workspace-specific. Each workspace that needs to access the Cosmos DB account must be authorized separately.
• You must add all IPv4 addresses for the DataFactory and PowerQueryOnline service tags in your region. Partial IP lists may cause connection failures.
• For private endpoint configurations, you must temporarily enable public access during the initial mirror setup. After mirroring is established, you can disable public access.
• For virtual network configurations, the endpoint rules must remain in place along with the added IP addresses.
• Configuring your public network access can take 5-15 minutes to complete.

Troubleshooting

If you experience issues connecting to your Azure Cosmos DB account:

1. Verify Network ACL capability is enabled:

   $account = Get-AzCosmosDBAccount -ResourceGroupName <resourceGroup> -Name <accountName>
   $account.Capabilities.Name
   

   Confirm that EnableFabricNetworkAclBypass appears in the output. If there's no output, the Network ACL capability has not been enabled.

2. Check trusted workspace configuration:

   $account = Get-AzCosmosDBAccount -ResourceGroupName <resourceGroup> -Name <accountName>
   $account.NetworkAclBypassResourceIds
   

   Verify that the resource exists and has the correct tenant ID and workspace ID. If there's no output, Fabric workspace has not been configured.

3. Verify IP addresses are correct:

   • Download the latest Azure Service Tags JSON file
   • Confirm you added all IPv4 ranges for DataFactory for your region and ALL PowerQueryOnline services
   • Check that no IP addresses were entered incorrectly

4. Review Azure Cosmos DB firewall settings:

   • For virtual networks, ensure the endpoint rules are still in place
   • For private endpoints, only disable public access after mirror setup completes

5. Check connection credentials:

   • Account keys are not supported for mirroring with private networks. Ensure you are using Microsoft Entra ID authentication and verify the required permissions are assigned

6. Check Fabric and Azure regions

   • Verify both your Fabric workspace region and Azure Cosmos DB Account region are the same.

7. Review monitoring logs:

   • Check the mirroring replication status for any error messages

For more troubleshooting guidance, see Troubleshooting: Microsoft Fabric mirrored databases from Azure Cosmos DB.

Related content

• Mirroring Azure Cosmos DB
• Tutorial: Configure Microsoft Fabric mirrored database for Azure Cosmos DB
• Limitations in Microsoft Fabric mirrored databases from Azure Cosmos DB
• Azure IP Ranges and Service Tags
• Configure network access to an Azure Cosmos DB account