An Azure NoSQL database service for app development.
Inspect the complete Cosmos DB 403 response and diagnostic logs first, because they identify whether Azure received the request through the public internet, a service endpoint, or a private endpoint—and therefore which network control must be changed.^1^
1. Identify where the request is blocked
In the application logs, capture the HTTP status, substatus, activity ID, and full error text. A Cosmos DB firewall rejection normally returns 403 Forbidden with one of these descriptions:
-
Request originated from client IP ... through public internet -
Request originated from client VNET through service endpoint -
Request originated from client VNET through private endpoint
If the application hides those details:
- Open Azure portal → Cosmos DB account → Diagnostic settings.
- Send data-plane request logs to a Log Analytics workspace.
- Reproduce the failure.
- Filter for status code
403; the firewall message includes the blocked source IP or network path.^2^
Interpret the result as follows:
- Cosmos DB records a 403: Azure received the request; correct the matching Cosmos DB network ACL.
- No Cosmos DB request is recorded and the connection times out or is reset: investigate Zscaler, the corporate firewall, DNS, TLS inspection, routing, or the SDK transport.
- It works without Zscaler but fails with Zscaler: compare DNS resolution, observed public egress IP, and port connectivity in both states. That isolates the changed network path without proving in advance which Zscaler policy caused it.
2. If it arrives through the public internet
Open Cosmos DB account → Networking and review Public network access and Allow access from:
- If access is Selected networks, allowlist the public egress IP presented by Zscaler, not the laptop’s private address. The portal’s detected address can be the network gateway address.
- If Zscaler uses several or dynamic egress addresses, obtain the organization’s stable egress ranges or route this traffic through fixed egress. Cosmos DB IP firewall entries cannot contain private IP addresses.
- Allow firewall changes up to 15 minutes to propagate.^2^
Do not enable Accept connections from within Azure datacenters for a Zscaler client. That option adds 0.0.0.0 and permits Azure-datacenter source ranges; it does not allow arbitrary corporate or Zscaler addresses.^2^
3. Configure the required outbound transport
Obtain the exact account URI from Cosmos DB account → Keys → URI and allow that account endpoint through Zscaler and the corporate firewall.^3^
Requirements depend on the API and SDK connection mode:
| Connection mode/API | Required outbound ports |
|---|---|
| NoSQL Gateway | TCP 443 |
| Table Gateway | TCP 443 |
| Gremlin Gateway | TCP 443 |
| MongoDB Gateway | TCP 10255 |
| Cassandra Gateway | TCP 10350 |
| NoSQL Direct over public/service endpoints | TCP 443 plus dynamic TCP 10000–20000 |
| NoSQL Direct over a private endpoint | TCP 443 plus potentially TCP 0–65535 |
Gateway mode is the preferred mode for a strict corporate firewall because it uses HTTPS and a single DNS endpoint. Direct mode is available for .NET and Java and requires broader TCP access.^4^
If the application is .NET or Java in Direct mode and opening those ranges is unacceptable, configure Gateway mode instead. Gateway mode trades some performance for simpler proxy/firewall traversal. Also have the Zscaler administrator verify whether TLS inspection or proxy authentication is interfering with the SDK connection; do not disable TLS validation as a workaround.^5^
Run these tests while connected to Zscaler, then repeat outside it where policy permits:
$hostName = "<account-name>.documents.azure.com"
Resolve-DnsName $hostName
Test-NetConnection $hostName -Port 443
Test-NetConnection $hostName -Port 10000 # Only for Direct mode
Test-NetConnection $hostName -Port 20000 # Only for Direct mode
A successful TCP 443 test does not prove Direct-mode ports are available.
4. If the account uses a private endpoint
If Public network access = Disabled, adding a Zscaler public IP will not help. The client must have private routing into the VNet and DNS must resolve the Cosmos DB account FQDN to the private endpoint’s private IP.^6^
Check:
- Private Link Center → Private endpoints → the Cosmos endpoint.
- Confirm connection state is Approved and provisioning succeeded.
- Run
nslookup <account-FQDN>from the Zscaler-connected client. - Confirm the result matches the private IP shown on the private endpoint.
- Verify that the VPN/Zscaler private-access configuration routes that IP range into Azure.
- Check NSGs, route tables, Azure Firewall/NVA, and the corporate firewall along that path.
If DNS returns a public IP, fix private DNS forwarding rather than allowlisting the public result. Microsoft’s diagnostic guidance classifies that as private-DNS configuration failure.^7^
For standard Cosmos DB private endpoints, the private DNS zone depends on the API—for example, NoSQL uses privatelink.documents.azure.com, while MongoDB, Cassandra, and Gremlin use their corresponding API-specific zones.^8^
If every Azure-side path, DNS, and ACL check passes but Cosmos DB receives no request, provide the network team with the timestamp, source device, account FQDN, resolved IP, destination port, and Zscaler request ID so they can locate the deny event.
References
- Diagnose and troubleshoot Azure Cosmos DB forbidden exceptions
- Configure IP firewall for Azure Cosmos DB
- Quickstart: Full-text search in Azure Cosmos DB
- Azure Cosmos DB SQL SDK connectivity modes
- Azure Cosmos DB Shell troubleshooting guide
- Configure Azure Private Link for an Azure Cosmos DB account
- Troubleshoot private endpoint connectivity failures
- Azure Private Endpoint private DNS zone values