What GraphWarden does and when to use it

GraphWarden is a governance proxy for Microsoft Graph. Your applications authenticate to GraphWarden instead of Graph directly. GraphWarden enforces a ruleset on each call, records an audit event, and forwards allowed traffic to Graph using credentials read from a Key Vault in your own tenant. This page explains the role the proxy fills and when adopting it is worth the effort.

Phase-1 documentation baseline

Prerequisites

- No setup required to read this page — it is positioning, not configuration. - When you are ready to deploy the proxy, the quickstart walks through it in about ten minutes.
This page is a tour of what GraphWarden does and the problems it exists to solve. If you know that context already and want to start deploying, jump to the quickstart.

The core problem

Applications that call Microsoft Graph typically hold the real Azure AD client_id and client_secret in their configuration. That design has three consequences organisations consistently hit at scale.

  • Broad application access. Graph API permissions are granted per application. An app provisioned with User.Read.All can enumerate every user in the tenant, regardless of what the specific feature needs on a given call. There is no per-request gate.
  • Credential rotation is painful. Rotating a Graph client secret means updating every application that uses it, often across teams and deployment pipelines. Secrets stay in place longer than security policy says they should.
  • Audit gaps. Microsoft's sign-in logs record the token acquisition, not the per-call usage. There is no native way to answer "which of my apps called /users/{id} last Tuesday, and what scope matched." Custom telemetry closes the gap, unevenly.

GraphWarden sits between your apps and Graph to address these consequences without changing the Graph API surface your apps consume.

How GraphWarden addresses it

The proxy holds three responsibilities the apps no longer carry.

  • Zero-knowledge credentials. The real Graph client_id and client_secret live in your Azure Key Vault. GraphWarden reads the secret at runtime through a Managed Identity, uses it to acquire a Graph token through MSAL, and forwards the token upstream. Applications never see the real credential again; they present a proxy-issued credential to GraphWarden instead.
  • Ruleset enforcement at the API layer. Every Graph call is evaluated against a ruleset bound to the calling app's App Identity. A Rule names a match pattern, a set of conditions, and an action (allow, filter, block, log_only). A Ruleset groups rules in evaluation order; the first match decides the verdict. Rules give you per-call gates that Graph API permissions alone cannot express — "this app may read users, but may not delete any", "this app may list groups only in the HR unit", "this app may read Mail.Read but never Mail.Send".
  • Audit metadata capture. Each Graph call produces an audit event: timestamp, caller App Identity, HTTP method, path, status, matched rule, latency. Events ship to Elasticsearch with ILM-driven retention tiers (30 days, 90 days, 1 year, 7 years). Request and response bodies are not stored by default; the trust model page covers the tradeoffs.

Who uses it

Four audiences adopt GraphWarden for distinct reasons. The developer guides and PowerShell guides on this site cover the integration surface for each.

  • Application developers. Your apps are the primary consumers. Switching to GraphWarden is a two-value change — the base URL and the credentials; your SDK calls, scopes, and response shapes stay identical. The developer migration guide walks through the pattern language-agnostically; the .NET guide shows a complete working sample.
  • PowerShell administrators. Scripts written against the Microsoft.Graph PowerShell module route through the proxy by overriding the endpoint on Connect-MgGraph. The PowerShell quickstart covers the token acquisition and cmdlet override in one script.
  • ISVs shipping to Microsoft 365 customers. When a customer requires GraphWarden in their environment, your ISV app must accept a configurable Graph base URL. The developer guides show how to make your app compatible without per-customer forks.
  • Compliance teams. GraphWarden's audit trail answers regulator questions about Graph access, and its ruleset enforcement gives auditable controls per application. Compliance framework mappings ship in later phases.

What it is not

GraphWarden's scope is narrow on purpose. These four things the proxy explicitly does not do.

  • It is not a Graph response cache. The proxy does not store response bodies by default and does not serve cached payloads back to callers. Per-rule verdict caching exists but caches the decision, not the data.
  • It is not an identity provider. Azure AD remains the IdP. GraphWarden does not issue user tokens, does not run sign-in flows, and does not replace Microsoft Entra for authentication. It issues short-lived proxy JWTs to authenticated applications only.
  • It is not a replacement for Graph API permissions. Azure AD permissions still gate what a Graph token can do upstream. The proxy adds a second, per-call gate on top of that; it does not remove the first.
  • It is not a man-in-the-middle for user data. The proxy sees request metadata and (when filter rules apply) response properties it is explicitly configured to inspect. It does not read or store user passwords, tokens, or response bodies outside the transforms you opt into.

Next steps

Three pages to read next, depending on what you are here to do.

  • To deploy the proxy and make a first call, follow the quickstart. It runs in about ten minutes on a prepared host.
  • To understand how requests flow through the proxy and what each component owns, read the architecture concept page.
  • To switch an existing application to GraphWarden in the language you already use, see the developer migration guide.

Troubleshooting

This page is positioning, not configuration. The three situations below are the misreadings that most often bring new readers back to this page.

"Does GraphWarden issue Azure AD tokens?"

No. GraphWarden issues proxy JWTs signed by a local key. When your app calls /proxy/token, the response is a short-lived proxy token, not a Graph token. The real Graph token is acquired by the proxy from Azure AD behind the scenes and is never returned to your app.

"Does GraphWarden cache Graph responses?"

No, not by default. Rule verdict decisions can be cached per rule, per caller, per object for performance. Response payloads are forwarded fresh on every request. A filter rule inspects the response body in-flight to apply property allow-lists or strip-lists; the filtered body is not retained.

"Will GraphWarden work for user-delegated flows?"

GraphWarden is designed for application-to-Graph traffic using the client-credentials grant. If your app uses delegated flows where a human signs in (interactive sign-in, OBO, MFA prompts), the user still authenticates to Azure AD directly. Delegated-flow support for GraphWarden is tracked outside Phase 1 scope.

Last reviewed:

Last reviewed: .