GraphWarden proxy environment variables

Every environment variable the GraphWarden proxy reads at startup, grouped by configuration surface. Values can be set via appsettings.json, environment variables, or Docker-style .env files. This page documents the proxy server configuration. For client-side conventions used in the .NET and PowerShell guides, see the bottom of this page.

Proxy runtime configuration — shipped

Prerequisites

- A GraphWarden proxy instance you operate (on-premises or hybrid) - Read-access to the proxy host's environment, Windows Service configuration, or Docker env file - Familiarity with the proxy's deployment mode (see the deployment modes concept page)

The proxy honours the .NET configuration provider binding pattern. Colon-delimited keys in `appsettings.json` (for example `GraphClient:ClientId`) translate to double-underscore environment variables on Linux and Docker (`GraphClient__ClientId`). Both forms are equivalent. The tables below show the colon form the proxy source uses internally; substitute `__` when you set the value as an OS environment variable.

Core identity

These values identify the proxy instance and select its deployment profile. Set them first; everything else layers on top.

Variable	Required	Default	Purpose
`Kestrel:MaxRequestBodySizeMb`	No	10	Maximum HTTP request body size accepted by Kestrel, in megabytes.
`GRAPHWARDEN__URL`	No	(none)	Presence (non-empty) signals hosted deployment. When set, file-based config store writes are disabled.

Graph client (upstream)

The credentials the proxy uses when it authenticates to Azure AD and calls Microsoft Graph on your behalf. ClientSecret is read from Key Vault in production; see the Key Vault section below.

Variable	Required	Default	Purpose
`GraphClient:TenantId`	Yes	(empty)	Azure AD tenant ID the proxy authenticates against for client-credentials flow.
`GraphClient:ClientId`	Yes	(empty)	Real Azure AD application client ID the proxy impersonates.
`GraphClient:ClientSecret`	Yes (via Key Vault in production)	(empty)	Real Graph secret. In development it can be inline; in production it is retrieved from Key Vault.
`GraphClient:BaseUrl`	No	`https://graph.microsoft.com/v1.0`	Upstream Microsoft Graph base URL. Override for sovereign clouds or testing.

Cache

Optional Redis-backed cache for MSAL tokens and rule-lookup memoisation. Leave disabled for single-instance deployments.

Variable	Required	Default	Purpose
`Cache:UseRedis`	No	`false`	Enable Redis-backed cache. Requires `ConnectionStrings:Redis`.
`ConnectionStrings:Redis`	Yes (if `Cache:UseRedis=true`)	(empty)	Redis server address in `host:port` form.

Key Vault

How the proxy reads the real Graph Client Secret at runtime. Managed Identity is the production standard; the in-memory fallback exists only for development.

Variable	Required	Default	Purpose
`KeyVault:VaultUri`	Yes (if `UseManagedIdentity=true`)	(empty)	Azure Key Vault URI (for example `https://my-vault.vault.azure.net/`).
`KeyVault:UseManagedIdentity`	No	`true`	Use a Managed Identity for Vault authentication. `false` falls back to an in-memory secret store (development only).

Proxy JWT

The signing configuration for the short-lived JWT the proxy hands clients after they authenticate to /proxy/token.

Variable	Required	Default	Purpose
`ProxyJwt:SigningKey`	Yes	(empty)	Symmetric secret used to sign proxy JWTs. Minimum 32 characters recommended; treat as a production secret.
`ProxyJwt:Issuer`	No	`graphproxy`	JWT `iss` claim value.
`ProxyJwt:Audience`	No	`graphproxy`	JWT `aud` claim value.

Admin and rules

The operator-facing surface: the admin key that gates sensitive endpoints and the ruleset file location.

Variable	Required	Default	Purpose
`AdminKey`	No	(empty)	Static API key required in the `X-Admin-Key` header for privileged endpoints (for example `/proxy/token/rotate-real`).
`Rules:FilePath`	No	`/config/rules.yaml`	Path on the proxy host where the YAML ruleset is read on startup and on each sync cycle.

Reverse proxy (YARP)

Catch-all routing configuration. The defaults forward every request to Microsoft Graph with path and query preserved; override only when you need a custom upstream for testing.

Variable	Required	Default	Purpose
`ReverseProxy:Routes[*].Match.Path`	No	`/{**catch-all}`	Route match pattern. At least one catch-all route must exist.
`ReverseProxy:Clusters[].Destinations[].Address`	No	`https://graph.microsoft.com`	Upstream Graph cluster destination address.

Rule sync

Controls the proxy's periodic pull of rulesets and app identities from the GraphWarden control plane. Disabled on-premises by default so the proxy can run fully offline.

Variable	Required	Default	Purpose
`RuleSync:Enabled`	No	`false`	Enable periodic ruleset and identity sync from the GraphWarden cloud.
`RuleSync:SaasBaseUrl`	Yes (if `Enabled=true`)	(empty)	GraphWarden control-plane base URL (for example `https://graphwarden.example.com`).
`RuleSync:TenantId`	Yes (if `Enabled=true`)	(empty)	Tenant UUID registered in the GraphWarden cloud.
`RuleSync:ApiKey`	Yes (if `Enabled=true`)	(empty)	API key paired with the HMAC secret for sync calls.
`RuleSync:HmacSecret`	Yes (if `Enabled=true`)	(empty)	Secret used to sign sync requests with HMAC-SHA256.
`RuleSync:IntervalSeconds`	No	60	Sync polling interval, in seconds.

Audit ingestion

Audit event capture and shipment to the control plane. All Audit:* keys are inert until Audit:Enabled is true.

Variable	Required	Default	Purpose
`Audit:Enabled`	No	`false`	Enable audit event capture and shipment.
`Audit:IngestionUrl`	Yes (if `Enabled=true`)	(empty)	Control-plane ingestion URL (for example `https://app.graphwarden.com/api/v1/agent/audit`).
`Audit:ApiKey`	Yes (if `Enabled=true`)	(empty)	API key paired with the HMAC secret for audit shipments.
`Audit:HmacSecret`	Yes (if `Enabled=true`)	(empty)	Secret used to sign audit batches with HMAC-SHA256.
`Audit:FlushSize`	No	500	Number of buffered events that triggers a flush.
`Audit:FlushIntervalSeconds`	No	5	Maximum buffer age before a forced flush, in seconds.
`Audit:MaxBufferSize`	No	10000	Maximum in-memory events before overflow protection drops the oldest entries.
`Audit:MaxBatchSize`	No	1000	Maximum events per batch sent to the control plane.
`Audit:LocalRetentionPath`	No	`audit-retention`	Directory (relative to the content root) for disk-backed retention when shipment fails.
`Audit:LocalRetentionMaxFileSizeMb`	No	100	Maximum single retention file size, in megabytes.
`Audit:LocalRetentionMaxAgeDays`	No	7	Retention file purge age, in days.
`Audit:ReplayIntervalSeconds`	No	60	Interval at which the proxy retries local retention files for re-shipment.
`Audit:DeploymentType`	No	`onprem`	Declared deployment context — `onprem` or `hosted`. Stamped into every audit event.

Logging

Serilog levels emitted to stdout (Docker) or the Windows Event Log (Windows Service).

Variable	Required	Default	Purpose
`Logging:LogLevel:Default`	No	`Information`	Serilog default level for framework and third-party namespaces.
`Logging:LogLevel:GraphProxy`	No	`Debug`	Serilog level for the `GraphProxy.*` namespaces.

Client-side conventions used in this documentation

The .NET and PowerShell guides read three environment variables on the client side — GRAPHWARDEN_PROXY_URL, GRAPHWARDEN_CLIENT_ID, and GRAPHWARDEN_CLIENT_SECRET. These are conventions for the consumer application's own environment; they are not proxy server configuration, and the proxy binary does not read them. Name them whatever your application prefers — the guides standardise on the GRAPHWARDEN_* prefix so the samples are consistent across languages.

Client-side variable	Meaning on the consumer side
`GRAPHWARDEN_PROXY_URL`	The proxy base URL the client application points its Graph SDK at.
`GRAPHWARDEN_CLIENT_ID`	The Proxy Client ID the client application sends to `/proxy/token`.
`GRAPHWARDEN_CLIENT_SECRET`	The Proxy Client Secret paired with the Proxy Client ID above.

The three client-side names do not follow the proxy's __ or colon-key binding style. They are plain POSIX-style identifiers because they are read by language runtimes (PowerShell, .NET configuration providers) that do not know about the proxy's internal key convention. If your client app already uses a different naming scheme, keep it — the sample code is copy-paste, not contract.

Troubleshooting

The four misconfigurations below are the most common startup failures.

Proxy exits on startup with "SigningKey is required"

ProxyJwt:SigningKey is unset or shorter than the minimum the validator enforces. Set a high-entropy secret of at least 32 characters. Do not reuse a staging value in production.

Graph calls return `502 Bad Gateway` and logs show "KeyVault: access denied"

The Managed Identity running the proxy does not have get permission on the Graph Client Secret in Key Vault. Grant Key Vault Secrets User scoped to the specific secret (RBAC mode) or equivalent access policy (legacy policy mode). Confirm the KeyVault:VaultUri matches the vault holding the secret.

Rule sync is enabled but the proxy log says "RuleSync disabled"

One of the four required RuleSync:* values is missing. Check SaasBaseUrl, TenantId, ApiKey, and HmacSecret — the proxy will refuse to enable sync if any is blank, even when RuleSync:Enabled=true.

Environment variables set on the host are ignored

The variable name uses the colon-key form. On Linux and Docker, colons are not valid in POSIX environment variable names — substitute __ (double underscore). GraphClient:ClientId becomes GraphClient__ClientId when set as an OS environment variable. Both forms map to the same configuration key.

Last reviewed: April 19, 2026