Network and firewall requirements for the GraphWarden proxy

The proxy needs outbound HTTPS to Microsoft identity and Graph endpoints, your Azure Key Vault, and the GraphWarden control plane. It accepts inbound HTTPS on its configured listener port (default 5000). This page enumerates every hostname and port the proxy uses.

Outbound connections required

The proxy initiates outbound HTTPS to four destination families. Every connection uses TLS on port 443.

The control-plane host is the GraphWarden App Admin deployment your organization uses. Its value appears in appsettings.json as Audit:IngestionUrl (the audit batch POST target) and RuleSync:SaasBaseUrl (the rule sync GET base). Both URLs point at the same App Admin host — different paths under that host.

Inbound connections required

The proxy accepts inbound HTTPS on a Kestrel-bound port. The health and metrics endpoints listen on the same port.

Production operators typically override the listener via appsettings.json to bind to a specific hostname and port, and either terminate TLS at Kestrel or front the proxy with a dedicated TLS reverse proxy. The default port 5000 is only the fallback Kestrel binding when no override is configured.

Inbound access should be scoped to the client application networks that legitimately route Graph traffic through the proxy. Exposing the proxy to the open internet without client-authentication controls negates the zero-trust model.

Optional outbound connections

If the proxy is configured for audit retention replay (Audit:LocalRetentionPath set) and the local buffer overflows, the proxy writes audit events to disk and later replays them to the control plane. This is still an outbound connection to <your-control-plane-host> on port 443 — no new destinations are introduced by retention replay.

Telemetry to Microsoft (crash dumps, .NET runtime diagnostics) is disabled by default in production builds. If your compliance posture forbids it, confirm DOTNET_CLI_TELEMETRY_OPTOUT=1 is set on the service environment.

Recommended firewall rule patterns

Microsoft Graph and Azure AD endpoints resolve to a large, rotating pool of IP addresses. Pinning firewall rules to IP ranges is fragile; prefer FQDN-based rules wherever your firewall supports them.

• For firewalls with FQDN resolution (Palo Alto, Fortinet, Azure Firewall Premium): allow the four destinations above by hostname. Graph and AAD endpoints are pre-populated in most vendor categories as Microsoft 365 Common and Office Online.
• For IP-based firewalls: subscribe to the Microsoft 365 URL/IP web service and automate rule updates. The IP ranges change often; a rule set that is correct today will be stale in months.
• For egress gateways that log every connection: tag the four rule families so audit-time investigations can filter by purpose (identity vs Graph vs vault vs control plane) rather than by hostname.
• Wildcard vault rules (*.vault.azure.net) accept the convenience of not updating rules when Key Vault names change. Scoped rules to your exact vault host (myvault.vault.azure.net) reduce the blast radius if a misconfiguration points the proxy at the wrong vault.

Verifying connectivity from the proxy host

Run the snippet below from an elevated PowerShell session on the proxy host. It tests TCP reachability of every required endpoint on port 443.

# Test reachability of each required endpoint.
$endpoints = @(
    "login.microsoftonline.com",
    "graph.microsoft.com",
    "myvault.vault.azure.net"  # replace with your vault host
)
foreach ($endpoint in $endpoints) {
    $reachable = Test-NetConnection -ComputerName $endpoint -Port 443 -InformationLevel Quiet
    Write-Host "${endpoint}:443 reachable = $reachable"
}

Add your control-plane host to the $endpoints array — the snippet is deliberately minimal to fit the page, not exhaustive. A reachable endpoint returns True; an unreachable one returns False and warrants a firewall log review.

Test-NetConnection uses the full TCP handshake, so a True result proves the firewall permits the connection and the destination accepts TCP on 443. It does NOT prove TLS handshake succeeds; see the TLS section below for intercept-related failures.

TLS intercepting proxies

Regulated environments often terminate TLS on outbound traffic with an intercepting proxy (Zscaler, Blue Coat, Palo Alto Decryption, or a corporate Forward Proxy). The intercepting proxy presents its own certificate — signed by an internal CA — to the origin server. The GraphWarden proxy validates the certificate chain against its trust store and refuses connections whose chain does not resolve to a trusted root.

To run the GraphWarden proxy through a TLS-intercepting proxy:

• Install the intercepting CA's root and any intermediate certificates into the Windows certificate store under Trusted Root Certification Authorities on the proxy host. The .NET runtime honours the machine-level trust store.
• Verify the chain with certutil -verify -urlfetch <cert.cer> or by running Test-NetConnection above — a TLS failure will surface as a connect-level error on the /health check rather than a network-level block.
• Do NOT disable certificate validation in the proxy configuration. Graph requests routed through an intercepting proxy with validation disabled are indistinguishable from a man-in-the-middle attack.

Troubleshooting

Token endpoint unreachable

The proxy starts but /proxy/token returns 500 or 503 with a connect-level error in the Windows Event Log. Outbound to login.microsoftonline.com:443 is blocked. Run the PowerShell snippet above from the proxy host; if login.microsoftonline.com:443 reachable = False, open a firewall ticket for that specific destination. If reachable but the proxy still fails, check for a TLS-interception issue (see the TLS section above).

Graph calls time out

Token acquisition works (/proxy/token returns 200) but Graph calls hang until the client timeout fires. Outbound to graph.microsoft.com:443 is either blocked or rate-limited by the firewall. A rate-limiting firewall caps the number of concurrent connections to Graph — confirm the limit is at least double your peak Graph request rate. Microsoft publishes Graph throttling guidance separately; firewall limits compound with those.

Key Vault errors at startup

The proxy fails to start with Azure.Identity or KeyVault exceptions in the Event Log. Outbound to *.vault.azure.net:443 is blocked. Confirm the firewall rule covers the exact vault host in KeyVault:VaultUri; a wildcard rule that excludes your region or resource scope may produce misleading results. Private Endpoint deployments of Key Vault terminate on a private IP — in that case the outbound rule targets the private IP range, not the public wildcard.

TLS handshake fails only from the proxy host

Test-NetConnection succeeds (TCP is open) but the /health endpoint on a proxy-reachable Graph call fails with a certificate-chain error. An intercepting TLS proxy on the network segment is presenting a certificate whose CA is not in the Windows trust store on the proxy host. Install the intercepting CA chain into Trusted Root Certification Authorities and restart the GraphWardenProxy service. If the CA is correctly installed but the error persists, confirm the intercepting proxy's certificate is not expired and that its Subject Alternative Names cover the destination host.

Last reviewed: April 19, 2026