Deployment modes: hosted, on-premise, and hybrid

GraphWarden ships three deployment modes. Hosted runs the proxy in GraphWarden infrastructure. On-premise runs the proxy on your own Windows Server or container host. Hybrid keeps the proxy on-premise and delegates ruleset management plus audit shipping to the hosted control plane. The choice is driven by data residency requirements and your operations capacity, not by features — all three modes support the same ruleset schema and the same Graph API surface.

Hosted

GraphWarden operates the proxy for you. This is the fastest mode to start with and has the lowest ops burden.

• Where the proxy runs — GraphWarden cloud infrastructure or a customer-managed Kubernetes cluster that GraphWarden operates.
• Where your credentials live — in YOUR Azure Key Vault in YOUR tenant. The hosted proxy instance is granted get on the specific Graph Client Secret via an Azure AD application or Managed Identity federation. GraphWarden does not hold a copy of the secret.
• Data path — your client app calls a GraphWarden-issued hostname (typically https://{tenant-subdomain}.graphwarden.io). The proxy reads the secret from your Key Vault, obtains a Graph token via MSAL, and forwards to https://graph.microsoft.com. Your Graph data does not leave your Graph tenant.
• Sync and audit — always enabled. Rulesets and App Identity changes propagate from App Admin to the hosted proxy automatically; audit events ship to Elasticsearch on GraphWarden's retention tier you select.
• File writes on the proxy — disabled (the proxy runs read-only).

On-premise Windows

The proxy runs on a Windows Server host you operate. The binary is a self-hosted ASP.NET Core service hosted in Kestrel. It is NOT an IIS application; it does not require IIS to be installed, and IIS does NOT front-end Kestrel on port 443. You register the binary with Windows Service Control Manager and open the Kestrel port directly (or place your own load balancer in front).

Installation at a glance:

# Registers the proxy as an auto-start Windows Service hosted in Kestrel.
# NOTE: no IIS involvement. The binary owns its listener.
sc.exe create GraphWardenProxy `
    binPath= "C:\Program Files\GraphWardenProxy\GraphProxy.Proxy.exe" `
    DisplayName= "GraphWarden Proxy" `
    start= auto

# Starts the service. Health check: http://localhost:5000/health
net start GraphWardenProxy

• Where the proxy runs — your Windows Server 2016+ host with .NET 8 runtime installed.
• Hosting model — Kestrel self-hosted. Program.cs detects OperatingSystem.IsWindows() and calls builder.Host.UseWindowsService().
• Key Vault access — Managed Identity is the production standard. The Windows Service runs under a local account, but the host VM carries an Azure Managed Identity that Key Vault authorizes.
• Sync and audit — configurable. Set RuleSync:IntervalSeconds and Audit:ElasticsearchUrl via appsettings.json or environment variables.

On-premise container

Same runtime as the Windows Service mode, packaged as a Docker image. The image runs on any Linux or Windows container host (Docker, Kubernetes, Azure Container Instances, Amazon ECS, etc.).

# Minimal container deployment. Env vars override appsettings.json values.
docker run -d \
    -e GraphClient__TenantId=00000000-0000-0000-0000-000000000000 \
    -e GraphClient__ClientId=f63c4abc-1234-5678-90ab-cdef01234567 \
    -e KeyVault__Url=https://customer-vault.vault.azure.net/ \
    -p 5000:5000 \
    ghcr.io/graphwarden/proxy:latest

• Where the proxy runs — your container host.
• Hosting model — Kestrel in the container; no Windows dependency.
• Key Vault access — Managed Identity (on Azure hosts), federated workload identity (on AKS), or explicit service principal credentials (everywhere else).
• File writes on the proxy — disabled when GRAPHWARDEN__URL is present in the environment (container "hosted-style" mode). Use environment variables to mutate configuration.

Hybrid

The proxy runs on your infrastructure; the App Admin control plane (ruleset authoring, App Identity management, audit retention, reporting) runs in GraphWarden's hosted environment.

• Where the proxy runs — your Windows Service host or container host. Same binary as on-premise.
• Where App Admin runs — GraphWarden cloud. You log into the hosted App Admin to author rulesets and create App Identities.
• Sync path — the on-prem proxy periodically calls the hosted App Admin Agent API (POST /api/v1/agent/heartbeat, GET /api/v1/agent/sync) signed with the instance's HMAC secret. Outbound-only; no inbound firewall hole required.
• Audit path — events ship from the on-prem proxy to a GraphWarden-hosted Elasticsearch cluster (or to your own cluster if you prefer; set Audit:ElasticsearchUrl).

Hybrid is the default mode for customers who want "SaaS admin, on-prem data plane."

Choosing a mode

The table below lists the factors we see drive the choice in practice.

Troubleshooting

The on-premise Windows Service fails to start — inspect the Windows Event Log under Application → GraphWardenProxy. The most common causes are a missing .NET 8 runtime, a port 5000 conflict with another service, or an expired Key Vault secret that Kestrel reads at startup.

Port 443 is already in use on the on-premise host — Kestrel and IIS cannot share a port. GraphWarden does NOT run under IIS. Either move Kestrel to a different port (set Kestrel:Endpoints:Https:Url) or remove the IIS binding that is holding 443.

The container refuses to write configuration changes at runtime — this is intentional. When GRAPHWARDEN__URL is set (hosted-style mode), the proxy runs read-only. Mutate configuration by redeploying the container with updated environment variables.

Hybrid mode's Agent API calls return 401 Unauthorized — the proxy instance's HMAC secret does not match the one App Admin stored at enrollment. Re-enroll the instance from the App Admin UI to issue a fresh HMAC secret.

Last reviewed: April 19, 2026