Cosmos DB SDK behind a TLS-inspecting proxy: strict certificate validation with private endpoint DNS

Answer summary

Keep strict validation by trusting the proxy’s root CA in the client trust store, bypass TLS inspection for the Cosmos DB privatelink name, and point DNS to a private zone that forwards account.documents.azure.com to the privatelink zone. Set a short JVM address cache TTL (≈30 s) and rely on the OS resolver’s default TTL so clients re‑resolve quickly after a regional failover.

Likely explanation

The Cosmos DB Java and .NET SDKs do not perform certificate pinning; they validate the server certificate against the default trust store. When a corporate proxy re‑terminates TLS, it presents its own chain, causing validation failures unless the proxy’s root CA is trusted. The proxy can be configured to skip decryption for specific hostnames (SNI‑based bypass) so the original server chain is seen, preserving end‑to‑end validation without importing the CA. For private endpoints, the account name must resolve to the *.privatelink.documents.azure.com zone; otherwise clients reach public IPs and bypass the private link. DNS caching controls how fast clients pick up a new regional endpoint after failover.

Confirmed facts

• The SDK relies on the JVM trust store (-Djavax.net.ssl.trustStore) or the OS trust store (Windows/macOS/Linux) for validation.
• Azure Cosmos DB does not embed certificate pins in the client libraries.
• A private endpoint is reachable only via its privatelink FQDN; public DNS returns public IPs.
• The JVM property networkaddress.cache.ttl controls how long resolved addresses are cached; a value of 30 seconds forces a re‑lookup after roughly half a minute.
• OS resolvers typically honor the TTL supplied in the DNS response (often 300 s or less).

Steps for this case

1. Proxy handling:
   
   • Check whether the proxy supports SNI‑based TLS bypass for *.privatelink.documents.azure.com.
   • If yes, create a bypass rule so traffic to that suffix is passed through unchanged; the SDK will see the server’s original certificate chain and validation succeeds.
   • If the proxy cannot bypass, export the proxy’s root CA (or the full chain if it includes an untrusted intermediate) and import it into:
     • JVM: keytool -import -alias proxyca -file proxy-root.crt -keystore $JAVA_HOME/lib/security/cacerts
     • .NET/OS: add the certificate to the trusted root store (Windows CertMgr, macOS Keychain, Linux /etc/ssl/certs).
2. DNS configuration for private endpoint:
   
   • Create a private DNS zone linked to the virtual network, e.g., privatelink.documents.azure.com.
   • Add an A record (or CNAME) for account.documents.azure.com pointing to the private endpoint’s FQDN (<account>.privatelink.documents.azure.com).
   • Configure client‑side DNS forwarders (or the VNet DNS) to query this zone first, then fall back to public DNS for all other names.
   • Validate with nslookup account.documents.azure.com from a client VM; the answer should be a private IP in the subnet’s address space.
3. DNS cache TTL tuning:
   
   • Set JVM property: -Dnetworkaddress.cache.ttl=30 (or lower, e.g., 15, if failover detection must be faster).
   • Leave the OS resolver at its default; it will use the TTL returned by the private DNS zone (typically 30‑60 s for Azure privatelink).
   • After a regional failover test, observe that new connections are established within the TTL window and that DNS query rates stay baseline.

Missing diagnostic detail

If the proxy cannot be configured for SNI‑based bypass, the only reliable path is to import the proxy’s root CA into every client trust store. Confirming whether your proxy supports hostname‑specific TLS decryption bypass will determine if the CA import step is required.