# GraphWarden

> Zero-trust security proxy for Microsoft Graph API. Policy enforcement, data filtering, and zero-knowledge credentials — deployed in under 60 minutes.

## Documentation

- [AI-native documentation for GraphWarden](/docs/ai-agents/overview): GraphWarden's documentation is authored for AI coding assistants and search engines as a primary audience. The llms.txt index, the x-doc.ai-prompt component, and TechArticle JSON-LD on every guide help Claude, Cursor, ChatGPT, and other agents generate correct GraphWarden integrations from a single prompt.
- [Prompts for common GraphWarden integration tasks](/docs/ai-agents/prompts): Copy-paste prompts for AI coding assistants covering the most common GraphWarden integration tasks — migrating a .NET or PowerShell app, adding GraphWarden support to a SaaS product, routing CI/CD pipelines, and building rulesets. Each prompt references https://graphwarden.com/llms.txt so the agent pulls current documentation.
- [Agent API: HMAC-authenticated endpoints between the proxy and the control plane](/docs/api-reference/agent-api): The GraphWarden proxy communicates with the control plane over four HMAC-authenticated endpoints — sync, heartbeat, audit, and metrics. This page documents the canonical request signing convention, the four endpoints, rate limits, error responses, and a hand-verifiable worked example that any HMAC-SHA256 library can reproduce.
- [Condition types: all 11 matchers used in GraphWarden rulesets](/docs/api-reference/condition-types): GraphWarden rulesets evaluate each Microsoft Graph request against an ordered list of conditions. Conditions match on endpoint path, HTTP method, request headers, app identity, and other request attributes. This page documents all 11 condition types, their YAML shape, and a matching example for each. See the rule schema reference for the top-level YAML contract.
- [GraphWarden proxy environment variables](/docs/api-reference/environment-variables): Every environment variable the GraphWarden proxy reads at startup, with required flag, default, and purpose. Covers core identity, TLS, Graph auth, Key Vault, JWT signing, rule sync, audit, and logging.
- [Rule schema: the GraphWarden ruleset YAML format](/docs/api-reference/rule-schema): GraphWarden rulesets are YAML documents with a top-level rules list. Each rule pairs a match block with optional conditions, a response filter, and an action. This page documents the top-level shape, rule-level keys, evaluation order, and the names of the eleven condition types and nine transform types that Phase 6 will document per-type.
- [Transform types: all 9 transformations used in GraphWarden rulesets](/docs/api-reference/transform-types): When a GraphWarden rule matches with action filter, its response filter can transform individual properties before the response returns to the caller. The 9 transform types cover masking, redaction, hashing, truncation, regex substitution, and other shape-preserving edits. This page documents each transform with its YAML shape and a before/after example.
- [Run GraphWarden proxy deployments from Azure DevOps Pipelines](/docs/ci-cd/azure-devops): A complete Azure DevOps YAML pipeline that builds, tests, and smoke-tests a GraphWarden proxy deployment. Variable groups hold credentials and a banner comment prevents accidental commits of real secrets. Runnable after replacing the marked values with your organization's tenant, client id, and secret.
- [Run GraphWarden proxy deployments from GitHub Actions](/docs/ci-cd/github-actions): A complete GitHub Actions workflow that builds, tests, and runs a GraphWarden smoke test. Repository secrets hold credentials and a banner comment prevents accidental commits. Runnable after adding the required repository secrets.
- [Manage GraphWarden secrets across environments](/docs/ci-cd/secrets-management): Store GraphWarden credentials in Azure Key Vault for production, in your CI platform's secret store for pipelines, and in a per-developer .env file for local work. Never commit secrets to source. This page covers the three-tier model, the rotation playbook, and how to detect accidental commits.
- [Provision GraphWarden infrastructure with Terraform](/docs/ci-cd/terraform): A Terraform module that provisions the GraphWarden proxy as Azure Container Apps alongside its Key Vault, user-assigned managed identity, and required permissions. This page provides a runnable HCL module with variables for the proxy's configuration. The module is a starting point — adapt to your naming conventions.
- [App identities: proxy credentials vs. real Graph credentials](/docs/concepts/app-identities): Your app authenticates to GraphWarden using proxy credentials issued by GraphWarden. GraphWarden holds the real Graph credentials in your Azure Key Vault. Your app never sees the real credentials.
- [How requests flow through GraphWarden](/docs/concepts/architecture): The proxy sits between your client app and Microsoft Graph, authenticates the client, evaluates a ruleset, and forwards allowed calls.
- [Deployment modes: hosted, on-premise, and hybrid](/docs/concepts/deployment-modes): Choose hosted (GraphWarden runs the proxy), on-premise (you run it as a Windows Service or container), or hybrid (proxy on-prem, control plane hosted). Each mode trades off data residency, ops burden, and time to deploy.
- [Rulesets and rules: the GraphWarden data model](/docs/concepts/rulesets-and-rules): Rulesets group ordered rules; rules match conditions and apply an action (allow, filter, block, or log_only). Every Graph request is evaluated against the caller's App Identity ruleset.
- [Trust model: zero-knowledge credentials and what GraphWarden does not see](/docs/concepts/trust-model): GraphWarden stores your Graph API credentials in your Azure Key Vault. It reads them at runtime to authenticate to Graph on your behalf. Audit logs capture metadata only; response bodies are not stored by default.
- [Deploy the GraphWarden proxy to Azure Container Apps](/docs/deployment/azure-container-apps): Azure Container Apps hosts the GraphWarden proxy as a managed container with auto-scaling, integrated Azure AD for Key Vault access, and Azure Monitor telemetry. This page covers ACA-specific deployment via Azure CLI and Bicep, ingress configuration, and scale rules tuned to your Graph request volume.
- [Deploy the GraphWarden proxy with Docker](/docs/deployment/docker): Run the GraphWarden proxy as a Docker container on any Linux or Windows Docker host. The image is built from the published .NET binaries; configuration is environment-driven through the full environment-variables reference. This page covers a Dockerfile pattern, docker-compose orchestration, health checks, and Key Vault access from a container.
- [Network and firewall requirements for the GraphWarden proxy](/docs/deployment/networking-firewall): The GraphWarden 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 and offers a verification snippet.
- [Install the GraphWarden proxy as a Windows Service](/docs/deployment/on-premise-windows): Install and operate the GraphWarden proxy as a Windows Service on Windows Server 2019 or 2022. The proxy runs a self-hosted Kestrel listener and is managed via sc.exe or the Services MMC snap-in — it does NOT run under IIS. This page covers service-account setup, Key Vault permissions, and firewall prerequisites.
- [Sizing the GraphWarden proxy for your request volume](/docs/deployment/sizing): The GraphWarden proxy's CPU and memory needs scale with request rate and response-body transform complexity. This page gives conservative starting-point recommendations and a methodology for profiling your workload. Adjust based on your observed CPU and memory during load testing — these numbers are reference baselines, not guarantees.
- [Integrate GraphWarden with a .NET application](/docs/developers/dotnet): A .NET app using Microsoft.Identity.Client and Microsoft.Graph can route through GraphWarden by overriding two values — the token endpoint and the Graph base URL. This page walks a complete working sample.
- [Integrate GraphWarden with a Go application](/docs/developers/go): A Go app using msgraph-sdk-go and azidentity can route through GraphWarden by overriding two values — the token endpoint and the Graph base URL. This page walks a complete working sample.
- [Route an existing app through GraphWarden](/docs/developers/migration-guide): Switching a Microsoft Graph integration to GraphWarden changes two things — the Graph base URL and the credentials. Your SDK calls, scopes, and response shapes stay the same.
- [Integrate GraphWarden with a Node.js application](/docs/developers/nodejs): A Node.js app using @microsoft/microsoft-graph-client and @azure/msal-node can route through GraphWarden by overriding two values — the token endpoint and the Graph base URL. This page walks a complete working sample.
- [Integrate GraphWarden with a PHP or Laravel application](/docs/developers/php-laravel): A PHP or Laravel app using microsoft/microsoft-graph can route through GraphWarden by overriding two values — the token endpoint and the Graph base URL. This page walks a complete working sample plus a Laravel service-container binding.
- [Integrate GraphWarden with a Python application](/docs/developers/python): A Python app using msgraph-sdk and azure-identity can route through GraphWarden by overriding two values — the token endpoint and the Graph base URL. This page walks a complete working sample.
- [What GraphWarden does and when to use it](/docs/introduction): GraphWarden is a Microsoft Graph API governance proxy. Your apps authenticate to GraphWarden instead of Graph directly; it enforces rulesets, audits calls, and keeps your Graph credentials in your own Key Vault.
- [GraphWarden-compatible partners](/docs/isv/certified-partners): This page lists third-party products whose vendors have published a GraphWarden compatibility statement. Inclusion here reflects a vendor-published declaration, not a GraphWarden-issued certification.
- [Add GraphWarden compatibility to your product](/docs/isv/compatibility-guide): GraphWarden-compatible means your product reads the Microsoft Graph base URL and credentials from customer configuration instead of hardcoding them. This page walks through the technical integration, edge cases, and a compatibility test checklist.
- [GraphWarden compatibility statement (template)](/docs/isv/compatibility-statement): Copy-paste template an ISV uses to declare GraphWarden compatibility in their own product documentation.
- [Why your product should support GraphWarden](/docs/isv/overview): Enterprise customers adopt GraphWarden to govern Microsoft Graph API access. If your product calls Graph, those customers will ask whether you support routing through the proxy. This page explains the business case for declaring compatibility and what support means technically and operationally.
- [Graph subscriptions, webhooks, and callbacks with GraphWarden](/docs/isv/webhooks-and-callbacks): Microsoft Graph subscriptions deliver change notifications directly from Graph to your endpoint — they bypass the GraphWarden proxy entirely. This page explains the edge cases, audit-gap implications, and mitigation patterns.
- [PowerShell cookbook: common M365 admin tasks through GraphWarden](/docs/powershell/cookbook): Copy-paste PowerShell snippets for common Microsoft 365 administration tasks routed through GraphWarden. Each snippet assumes you have already connected via Connect-MgGraph per the quickstart. Snippets are reference-authored and should be validated on a non-production tenant before operational use.
- [Route Exchange Online PowerShell through GraphWarden](/docs/powershell/exchange-online): Connect-ExchangeOnline can route through GraphWarden by supplying a proxy-acquired access token. All Exchange Online cmdlets (Get-Mailbox, Set-CASMailbox, and the rest) then flow through the proxy and are subject to your ruleset's endpoint allowlist, with the caveat that some legacy Exchange REST operations bypass Microsoft Graph entirely.
- [Route legacy AzureAD and MSOnline PowerShell modules through GraphWarden](/docs/powershell/legacy-azuread-msonline): The deprecated AzureAD and MSOnline modules can be routed through GraphWarden with the same override pattern as Microsoft.Graph — acquire a proxy JWT, pass it to Connect-AzureAD or Connect-MsolService, and existing cmdlets flow through the proxy. This page also flags the endpoint differences that matter when planning a migration.
- [Manage Microsoft 365 with the Microsoft.Graph PowerShell module through GraphWarden](/docs/powershell/microsoft-graph-module): Once connected through the quickstart, Microsoft.Graph cmdlets work against GraphWarden transparently. This page covers common Microsoft 365 admin scenarios and how ruleset enforcement surfaces in scripts.
- [Route a PowerShell script through GraphWarden](/docs/powershell/quickstart): A PowerShell script using Microsoft.Graph cmdlets routes through GraphWarden by acquiring a proxy JWT and pointing Connect-MgGraph at the proxy. Every cmdlet you already run works unchanged.
- [Deploy GraphWarden and make your first proxied Graph call](/docs/quickstart): Deploy the GraphWarden proxy as a Windows Service or Docker container, provision one App Identity in the Admin app, and route one Graph call through the proxy. Expected time is about ten minutes on a prepared host.
- [Developer integration](/docs/developers): Route your applications through GraphWarden without rewriting your Microsoft Graph calls.
- [PowerShell integration](/docs/powershell): Route Microsoft Graph PowerShell scripts through GraphWarden without changing your cmdlets.
- [API reference](/docs/api-reference): Canonical specifications for the GraphWarden proxy, rulesets, and agent API.
- [ISV integration](/docs/isv): Declare GraphWarden compatibility and support customers who run their Microsoft Graph calls through the proxy.
- [CI/CD integration](/docs/ci-cd): Run GraphWarden proxy deployments and automated tests from your CI/CD pipeline.
- [Deployment](/docs/deployment): Install and operate the GraphWarden proxy on-premises or in hybrid mode.
- [AI agents](/docs/ai-agents): Build GraphWarden integrations using Claude Code, Cursor, Copilot, and ChatGPT.
- [Trust](/en/trust): Zero-knowledge credentials, seven aligned compliance frameworks, audit-ready logging.

## Compliance

- [GraphWarden and GDPR: how the proxy supports your compliance obligations](/en/compliance/gdpr): Article-by-article mapping of the European Union General Data Protection Regulation (GDPR) obligations to GraphWarden's technical capabilities, with explicit limits on what the proxy does and does not cover.
- [GraphWarden and HIPAA: how the proxy supports your compliance obligations](/en/compliance/hipaa): Section-by-section mapping of the HIPAA Security Rule Technical Safeguards (45 CFR §164.312) to GraphWarden's technical capabilities, with explicit limits on what the proxy does and does not cover.
- [GraphWarden and ISO 27001: how the proxy supports your Annex A controls](/en/compliance/iso-27001): Control-by-control mapping of ISO/IEC 27001:2022 Annex A controls to GraphWarden's technical capabilities, with explicit limits on what the proxy does and does not cover.
- [GraphWarden and Loi 25: how the proxy supports your compliance obligations](/en/compliance/loi-25): Article-by-article mapping of Quebec's Loi 25 obligations to GraphWarden technical capabilities, with explicit limits on what the proxy does and does not cover.
- [GraphWarden and OWASP API Security Top 10 (2023)](/en/compliance/owasp-api-security): Item-by-item mapping of the OWASP API Security Top 10 (2023) risks to GraphWarden's technical capabilities, with explicit focus on API3 (Broken Object Property Level Authorization) and API5 (Broken Function Level Authorization).
- [GraphWarden and PIPEDA: how the proxy supports your compliance obligations](/en/compliance/pipeda): Principle-by-principle mapping of PIPEDA's ten Fair Information Principles to GraphWarden's technical capabilities, with explicit limits on what the proxy does and does not cover.
- [GraphWarden and SOC 2: how the proxy supports your Trust Service Criteria](/en/compliance/soc-2): Criterion-by-criterion mapping of the AICPA Trust Service Criteria (Security, Availability, Confidentiality, Processing Integrity, Privacy) to GraphWarden's technical capabilities, with explicit limits on what the proxy does and does not cover.

## Product facts

- GraphWarden is a Microsoft Graph API governance proxy.
- Rulesets contain rules; rules pair conditions and actions.
- 11 condition types and 9 transform types are available (see Phase 6 reference pages).
- The Agent API between the proxy and the control plane is authenticated with HMAC-SHA256.
- 4 agent API endpoints: /sync, /heartbeat, /audit, /metrics.
- On-premise deployment runs as a Windows Service on Windows Server 2019 or 2022 (Kestrel self-hosted, not IIS).
- Graph credentials are held in the customer's Azure Key Vault; GraphWarden reads them at runtime via get-only permission.
- Audit logs capture metadata only by default (method, path, app identity, status, latency).
- Bilingual compliance pages are planned for Phase 5 (Loi 25, PIPEDA, GDPR, HIPAA, SOC 2, ISO 27001, OWASP API).

## Suggested prompts for AI agents

- "Migrate my .NET app to use GraphWarden as a proxy for Microsoft Graph"
- "Generate a GraphWarden ruleset for an HR app that reads only HR group members with 5 properties"
- "Add GraphWarden support to my SaaS product that uses Microsoft Graph"
- "Route my PowerShell script using Connect-MgGraph through GraphWarden"
- "Integrate GraphWarden into an Azure DevOps pipeline with a variable-group-backed smoke test"


---

# Full documentation bodies


## AI-native documentation for GraphWarden

# AI-native documentation for GraphWarden

GraphWarden's documentation is structured for AI coding assistants and search engines as a primary audience. The `llms.txt` index, the ai-prompt component, and `TechArticle` JSON-LD on every guide help Claude, Cursor, ChatGPT, and other agents generate correct GraphWarden integrations from a single prompt.

<x-doc.status-badge status="supported">AI-native docs surface</x-doc.status-badge>

<x-doc.prerequisites>

- An AI coding assistant that respects `llms.txt` or that you can paste documentation URLs into (Claude Code, Cursor, Copilot, ChatGPT, Perplexity)
- A GraphWarden proxy URL and proxy credentials to test the generated code

</x-doc.prerequisites>

## How AI agents discover this documentation

GraphWarden publishes four surfaces that AI agents and search engines consume without a human in the loop.

- **`/llms.txt`** — the machine-readable index. It lists every Markdown documentation page with a one-line description and links to the canonical URL on `https://graphwarden.com`. This is the primary entry point for an agent that has been pointed at the site.
- **`/llms-full.txt`** — the concatenated full-text of every Markdown page in one file. Planned for Phase 3b. Agents that prefer to ingest the entire corpus in a single request will read this file once rather than crawling individual pages.
- **Sitemap** — the XML sitemap at `/sitemap.xml` lists every canonical URL on the site, including the Blade landings that `llms.txt` deliberately omits. Search engines read this file when they crawl.
- **JSON-LD `TechArticle`** — every Markdown page ships structured data in a `<script type="application/ld+json">` block in its `<head>`. Search engines and some agents read this block to extract `headline`, `dateModified`, and `author` without parsing the rendered HTML.

The four surfaces answer different questions. An agent that needs to generate code reads `/llms.txt` plus the specific pages it links to. A search engine that indexes the site reads the sitemap plus the per-page JSON-LD. Both are supported.

## The ai-prompt component

Every developer-facing guide in these docs ships an ai-prompt block near the top of the page. The block renders a tinted panel with a copyable prompt body and a one-click copy button. The prompt body is written to be pasted into an AI coding assistant without editing — it names GraphWarden explicitly, references `https://graphwarden.com/llms.txt` for current documentation, and asks for the proxy-specific values the agent needs to produce working code.

- A developer reading a guide clicks the copy button and pastes the prompt into their agent.
- The agent reads the prompt, fetches `/llms.txt`, and follows the linked pages to produce integration code.
- The developer answers the agent's questions (proxy URL, credentials, paths) and receives code that already accounts for GraphWarden's quirks.

The component is anonymous Blade at `resources/views/components/doc/ai-prompt.blade.php`. Authors drop the component as a paired Blade tag into any Markdown page; the renderer tokenizes the block before handing the page to CommonMark, so the slot body can span multiple lines and contain arbitrary text.

## What's indexed for AI agents

The `/llms.txt` index lists all 22 Markdown documentation pages by path. The 6 Blade landings (`/docs/developers`, `/docs/powershell`, `/docs/api-reference`, `/docs/isv`, `/docs/ci-cd`, `/docs/deployment`, and now `/docs/ai-agents`) are intentionally omitted from `/llms.txt` because they are navigation surfaces — card grids linking to the Markdown pages below. An agent reading the card grid learns nothing new; an agent reading the Markdown pages learns the integration patterns.

The Markdown pages cover four surfaces: concepts, developer integration, PowerShell, CI/CD, ISV compatibility, API reference, on-premise deployment, and this ai-agents section. Agents that need specific integration code can fetch the one page that matches their task rather than ingesting the full corpus.

## Troubleshooting

### The agent generated code that calls `graph.microsoft.com` directly

The agent did not read (or did not apply) the base-URL override. Re-prompt with the proxy URL explicitly named — for example, "the Graph base URL for my GraphWarden proxy is `https://proxy.example.com`; every Graph call in the generated code must target that base URL, not `graph.microsoft.com`." Paste the proxy URL again if the agent dropped it from context.

### The agent did not find my `llms.txt`

Some agents only fetch `llms.txt` when explicitly told to. Share the full URL in the prompt: "Reference documentation is at `https://graphwarden.com/llms.txt` — fetch it before answering." If the agent still cannot reach the file, fall back to pasting the specific page URL the agent needs (for example, `https://graphwarden.com/docs/developers/dotnet`).

### The agent's output references an endpoint that doesn't exist in GraphWarden

The agent hallucinated or pulled from an outdated cache. Point it at `/docs/api-reference/agent-api` for the authoritative endpoint list and ask it to regenerate. The four endpoints GraphWarden ships are `sync`, `heartbeat`, `audit`, and `metrics`; anything else is an invention.

### Generated code uses the wrong credential format

GraphWarden issues proxy credentials (Proxy Client ID, Proxy Client Secret) — not Azure AD app registrations. If the agent writes code that expects Azure AD credentials against the proxy's token endpoint, re-prompt: "The credentials are issued by GraphWarden, not Azure AD. Send them to `{proxy-url}/proxy/token` with `grant_type=client_credentials`." Point the agent at `/docs/developers/migration-guide` for the before/after.

<x-doc.last-reviewed date="2026-04-19" />



## Prompts for common GraphWarden integration tasks

# Prompts for common GraphWarden integration tasks

Copy-paste prompts for AI coding assistants covering the most common GraphWarden integration tasks: migrating a .NET or PowerShell app, adding GraphWarden support to a SaaS product, routing CI/CD pipelines, and building rulesets. Each prompt references `https://graphwarden.com/llms.txt` so the agent pulls current documentation.

<x-doc.status-badge status="supported">Prompt catalogue</x-doc.status-badge>

<x-doc.prerequisites>

- An AI coding assistant
- Your GraphWarden proxy URL and credentials on hand (many prompts ask for them)

</x-doc.prerequisites>

## Migrate a .NET application

Paste this prompt into your assistant when you have an existing .NET application that calls Microsoft Graph directly and you want to route it through GraphWarden without rewriting the Graph SDK calls.

<x-doc.ai-prompt title="Migrate a .NET application">
Migrate my existing .NET application from direct Microsoft Graph API calls to use GraphWarden as a proxy.

My app currently uses ClientSecretCredential with https://graph.microsoft.com.

I need to:
1. Change the base URL to my GraphWarden proxy URL
2. Replace real Graph credentials with GraphWarden proxy credentials
3. Preserve all existing Graph SDK calls unchanged
4. Add error handling for GraphWarden-specific responses (401 invalid proxy credentials, 403 ruleset denial)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for:
- My GraphWarden proxy URL
- My proxy client_id and proxy client_secret
- Which Graph endpoints and scopes my app uses today
</x-doc.ai-prompt>

## Route a PowerShell script

Use this prompt when you have a PowerShell script that calls `Connect-MgGraph` with client-credential auth and you want every cmdlet in the script to flow through the GraphWarden proxy.

<x-doc.ai-prompt title="Route a PowerShell script">
Route my PowerShell script using Connect-MgGraph through GraphWarden.

My script currently calls Connect-MgGraph with client-credential auth against https://graph.microsoft.com.

I need:
1. The tested pattern to acquire a token from the GraphWarden proxy's token endpoint
2. A Connect-MgGraph invocation that uses that token against the proxy as the Graph endpoint
3. A sanity check that Get-MgContext confirms the endpoint is the proxy

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my proxy URL and proxy credentials.
</x-doc.ai-prompt>

## Add GraphWarden support to a SaaS product

Run this prompt when you ship a SaaS product that calls Microsoft Graph on behalf of your customers and you want to let enterprise customers route that traffic through their GraphWarden deployment.

<x-doc.ai-prompt title="Add GraphWarden support to a SaaS product">
Add GraphWarden compatibility to my SaaS product that uses Microsoft Graph.

Compatibility means my product reads the Graph base URL and credentials from customer configuration instead of hardcoding https://graph.microsoft.com.

I need:
1. Identification of every Graph reference in my codebase that needs to be externalized
2. A configuration surface change (env vars, admin UI settings, or similar)
3. A compatibility statement template for my customer-facing documentation

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my product's primary language/framework and paste the Graph initialization code.
</x-doc.ai-prompt>

## Integrate GraphWarden into an Azure DevOps pipeline

Use this prompt when you want a CI/CD smoke test that verifies your GraphWarden proxy is reachable from an Azure DevOps pipeline before promoting a build.

<x-doc.ai-prompt title="Integrate GraphWarden into an Azure DevOps pipeline">
Add a GraphWarden smoke test to my existing Azure DevOps YAML pipeline.

I want a pipeline stage that:
1. Acquires a token from my GraphWarden proxy's /oauth2/v2.0/token endpoint
2. Fails the build if token acquisition fails
3. Uses variable-group-backed secrets (not inline values)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my existing azure-pipelines.yml and whether my variable group is already configured.
</x-doc.ai-prompt>

## Generate a ruleset from a natural-language description

Use this prompt when you know what the rule should do in plain English and you need the equivalent GraphWarden YAML — for example, a ruleset that whitelists specific properties for a specific security group and denies write operations.

<x-doc.ai-prompt title="Generate a ruleset from a natural-language description">
Generate a GraphWarden YAML ruleset that allows reading users (displayName, mail only) from a specific security group and denies all write operations.

Reference documentation: https://graphwarden.com/llms.txt

Ask me for:
- The Azure AD security group UUID that should be allowed to read users
- Which Graph endpoints the ruleset should deny write operations on
- Whether the ruleset should log denied attempts or silently block them
</x-doc.ai-prompt>

## Troubleshooting

### The agent ignores my prompt and answers from training data

Prepend the prompt with a line that forces a fetch: "Before answering, fetch `https://graphwarden.com/llms.txt` and the specific pages it links to." Agents that do not fetch URLs cannot reach current docs; in that case, paste the relevant page text directly into the prompt instead.

### The agent keeps asking the same clarifying question

The prompt lists the values the agent needs to ask for. If the agent loops on a value you already provided, re-state the answer verbatim and confirm the agent has it: "My proxy URL is `https://proxy.example.com`. Acknowledge this value and proceed with the next step."

### The generated code is missing error handling for ruleset denials

The base prompts request handling for `401` (credential issues) and `403` (ruleset denial). If the agent skipped it, append: "Surface 403 responses to the end user with the matched `ruleId` from the response body. Reference: `/docs/isv/compatibility-guide`."

<x-doc.last-reviewed date="2026-04-19" />



## Agent API: HMAC-authenticated endpoints between the proxy and the control plane

# Agent API: HMAC-authenticated endpoints between the proxy and the control plane

The GraphWarden proxy communicates with the control plane over four HMAC-authenticated endpoints: `/sync`, `/heartbeat`, `/audit`, and `/metrics`. This page documents each endpoint, the HMAC signing convention, rate limits, and a complete worked example that reproduces the signature with any HMAC-SHA256 library.

<x-doc.status-badge status="supported">Agent API contract — HMAC-SHA256, hex-lowercase</x-doc.status-badge>

<x-doc.prerequisites>

- A proxy API key and HMAC secret issued by the GraphWarden Admin app (unique per proxy instance)
- An HMAC-SHA256 implementation — the standard library on any modern runtime (.NET `HMACSHA256`, PHP `hash_hmac`, Python `hmac`, Node `crypto.createHmac`, Go `crypto/hmac`)
- A clock synchronised to within ±300 seconds (5 minutes) of the control-plane server time

</x-doc.prerequisites>

## The four endpoints

Every endpoint lives under the control-plane base URL `https://{app-admin-host}/api/v1/agent/`. The base URL is configured via `RuleSync:SaasBaseUrl` and `Audit:IngestionUrl` on the proxy (see the environment variables reference).

| Endpoint | Method | Purpose | Rate limit |
|----------|--------|---------|------------|
| `/api/v1/agent/sync` | `GET` | Proxy fetches current rulesets, app identities, and metadata from the control plane. | Not rate-limited individually |
| `/api/v1/agent/heartbeat` | `POST` | Proxy signals liveness and reports version, uptime, loaded-rule count, and check statuses. | Not rate-limited individually |
| `/api/v1/agent/audit` | `POST` | Proxy ships audit event batches to Elasticsearch via the control plane. | 100 batches/min per org, 60 batches/min per proxy instance |
| `/api/v1/agent/metrics` | `POST` | Proxy reports performance counters (requests evaluated, allowed, blocked, filtered, latency). | Not rate-limited individually |

The `/audit` rate limits are applied by the `ThrottleAuditBatch` middleware on the control plane. Breaching either limit returns HTTP 429 with a `Retry-After` header; the two limits are configurable via `AUDIT_RATE_LIMIT_ORG` and `AUDIT_RATE_LIMIT_PROXY`.

## Request signing convention

Every request — regardless of method — carries three headers:

| Header | Value |
|--------|-------|
| `X-Api-Key` | Cleartext API key identifying the proxy instance. |
| `X-Timestamp` | Current Unix time in seconds (UTC). |
| `X-Hmac-Signature` | Hex-lowercase SHA256 signature of the canonical payload. |

The canonical payload concatenates the timestamp, a literal dot, and the raw request body:

```
payload = "{X-Timestamp}.{body}"
signature = HMAC-SHA256(hmac_secret, payload)
result = hex(signature).lowercase()
```

For `GET` requests, the body is empty — the canonical payload reduces to `"{timestamp}."` with nothing after the dot.

The control plane enforces a ±300 second skew tolerance on `X-Timestamp`. Requests outside that window are rejected with HTTP 401 even when the signature is otherwise well-formed. Clock drift is the leading cause of field-reported authentication failures; treat NTP sync as a prerequisite, not an optimisation.

The case of the hex digest matters: the control plane compares signatures case-sensitively against the hex-lowercase representation. Emitting an uppercase signature is rejected as a mismatch.

## Worked example: hand-verifiable

The example below fixes every input so a reader or an automated test can reproduce the signature with any HMAC-SHA256 library. The exact same numbers are asserted by the feature test that accompanies this page — if either drifts, the test fails.

### Example inputs (reproduce the signature with these)

| Field | Value |
|-------|-------|
| Endpoint | `GET /api/v1/agent/sync` |
| X-Timestamp (Unix) | `1745064000` |
| Body | (empty — this is a GET) |
| HMAC secret | `sk_example_key_for_docs_only` |

### Canonical payload

Because the method is `GET`, the body is empty and the canonical payload is the timestamp plus a literal dot:

```
1745064000.
```

### Computing the signature

Any HMAC-SHA256 implementation reproduces the same hex digest. The PHP one-liner below is the same one the feature test runs:

```php
echo hash_hmac('sha256', '1745064000.', 'sk_example_key_for_docs_only');
```

The equivalent in `bash` with `openssl`:

```bash
printf '%s' '1745064000.' | openssl dgst -sha256 -hmac 'sk_example_key_for_docs_only' -hex
```

The expected signature — 64 hex characters, lowercase — is:

```
1f783cff87e072de68de97218bc53bef4eb5b42459085ec37b7eef8f7cc8891b
```

<!-- hmac-timestamp: 1745064000 -->
<!-- hmac-secret: sk_example_key_for_docs_only -->
<!-- hmac-signature: 1f783cff87e072de68de97218bc53bef4eb5b42459085ec37b7eef8f7cc8891b -->

### Resulting headers

With all three inputs set, the proxy sends:

```
X-Api-Key: sk_example_key_for_docs_only
X-Timestamp: 1745064000
X-Hmac-Signature: 1f783cff87e072de68de97218bc53bef4eb5b42459085ec37b7eef8f7cc8891b
Authorization: HMAC key-id=sk_example_key_for_docs_only, signature=1f783cff87e072de68de97218bc53bef4eb5b42459085ec37b7eef8f7cc8891b
```

The `Authorization` header line is redundant with the three `X-*` headers and is included only for operators whose HTTP tooling shows `Authorization` lines by default. The control plane reads the `X-*` triple.

For a `POST` request, replace the empty body with the exact JSON the proxy sends — no whitespace changes, no re-serialisation. The payload becomes `"{timestamp}.{serialised_body}"` and the signature is recomputed over that concatenation.

## Rate limits per endpoint

| Endpoint | Scope | Default | Configuration key |
|----------|-------|---------|-------------------|
| `/audit` | Per org | 100 batches/min | `AUDIT_RATE_LIMIT_ORG` |
| `/audit` | Per proxy instance | 60 batches/min | `AUDIT_RATE_LIMIT_PROXY` |
| `/sync`, `/heartbeat`, `/metrics` | Global | No per-call rate limit applied | n/a |

When the proxy breaches either `/audit` limit, the control plane responds with HTTP 429 and a `Retry-After` header giving the number of seconds before the next batch will be accepted. The proxy queues the batch to local retention (`Audit:LocalRetentionPath`) and retries on the next `Audit:ReplayIntervalSeconds` tick.

## Error responses

| Status | Meaning | Remediation |
|--------|---------|-------------|
| `200 OK` | Request accepted (applies to `/sync`, `/heartbeat`, `/metrics`). | None. |
| `202 Accepted` | Audit batch accepted (applies to `/audit`). A body field `duplicate: true` indicates idempotent replay. | None. |
| `400 Bad Request` | Payload shape invalid — missing batch ID, cross-org event mix, malformed JSON. | Inspect the batch before send; check event-level `GWOrgId` uniformity. |
| `401 Unauthorized` | Signature mismatch OR timestamp outside ±300s OR API key not recognised. | Verify clock sync, re-derive the signature with the documented payload, confirm the API key. |
| `403 Forbidden` | API key valid but not authorised for the target tenant. | Re-issue the proxy credentials from the Admin app. |
| `409 Conflict` | Audit batch ID already processed beyond the 48h idempotency window. | Generate a new batch ID for subsequent retries. |
| `413 Payload Too Large` | Audit batch exceeds the 5 MB size limit. | Reduce `Audit:MaxBatchSize` to 500 events or lower. |
| `429 Too Many Requests` | Either audit rate limit breached. | Honour `Retry-After`; local retention queues the batch until the window reopens. |

## Troubleshooting

### The control plane returns 401 even though the signature computation matches in a local script

The leading cause is clock drift. Check the proxy host's NTP status and compare `X-Timestamp` sent against the control-plane server time. A ±300 second window sounds forgiving; a host drifted by six minutes from UTC falls outside it silently. Enable `ntp` (or `w32tm` on Windows) and restart the proxy.

### The local signature matches one library but differs from another

The canonical payload must be bytes, not a string with implicit encoding. Confirm the HMAC library receives ASCII bytes for the timestamp, a literal `.` (0x2E), and the exact body bytes with no trailing newline. Some libraries default to UTF-16 or append a CRLF; either changes every hex byte of the output. The PHP `hash_hmac` call above emits the canonical reference.

### The Authorization-header `key-id` is rejected but the `X-Api-Key` header works

The control plane reads only the three `X-*` headers. The `Authorization` line is a human-readable mirror and is not parsed. Operators who forward requests through an intermediate proxy that rewrites `Authorization` but preserves `X-*` headers encounter this scenario; rely on the `X-*` headers as the source of truth.

### The signature is correct bytewise but rendered uppercase

The control plane compares hex-lowercase. Many language standard libraries emit uppercase by default (`bin2hex` + `strtoupper`, `BitConverter.ToString` on .NET). Pipe through `.ToLower()` or equivalent before sending. The reference PHP snippet outputs lowercase; match its shape.

### The body bytes appear identical but the POST signature mismatches

A common cause: the proxy serialises the body with a trailing newline or a pretty-printer, while the local test script serialises without it. Compute the signature over the exact bytes the HTTP library will transmit. Hash the body before and after the HTTP client touches it; the `Content-Length` header reveals any mismatch.

For the detailed ruleset YAML format the `/sync` response returns, see the rule schema reference.

<x-doc.last-reviewed date="2026-04-19" />



## Condition types: all 11 matchers used in GraphWarden rulesets

# Condition types: all 11 matchers used in GraphWarden rulesets

GraphWarden rulesets evaluate each Microsoft Graph request against an ordered list of conditions attached to rules. Conditions match on Azure AD object attributes, the calling app identity, the time of day, the caller IP, and the shape of the outbound response. This page documents all eleven condition types, their YAML shape, a matching example, and the edge cases that catch authors out. See the [rule schema reference](./rule-schema) for the top-level YAML contract.

<x-doc.status-badge status="supported">Condition types — full inventory</x-doc.status-badge>

<x-doc.prerequisites>

- Familiarity with GraphWarden rulesets — see [Rulesets and rules](../concepts/rulesets-and-rules)
- A YAML-aware text editor (the proxy parses YAML 1.2)
- Read access to the [rule schema reference](./rule-schema) for the top-level `rules:` shape

</x-doc.prerequisites>

## Condition mechanics

A condition is a YAML object with a `type` field plus type-specific configuration fields. Conditions attach to a rule's `conditions:` list. Within a single rule, top-level conditions combine with AND semantics — every condition must evaluate true for the rule to match. For OR or NOT semantics, attach a `logic_group` key with `any_of` or `none_of` and a `variants:` list on the condition; see [Combining conditions](#combining-conditions) at the end of this page.

Each condition below is labelled as an **object** check (evaluates against the Graph response object — typically a user, group, or device), a **request** check (evaluates against the incoming HTTP request — caller identity, IP, time), or a **response** check (evaluates against the outgoing Graph response shape — result-set size).

## group_membership

An object check that matches if the target Graph object belongs to a specified Azure AD security group. Membership is resolved via a Graph call and cached.

**YAML shape**

```yaml
- type: group_membership
  group_id: "00000000-0000-0000-0000-000000000001"
```

**Example — restrict a response filter to the HR security group**

```yaml
rules:
  - id: hr-group-only
    match:
      app_id: "*"
      methods: ["GET"]
      endpoint_pattern: "/users*"
    conditions:
      - type: group_membership
        group_id: "00000000-0000-0000-0000-000000000001"
    response_filter:
      allow_properties:
        - id
        - displayName
        - mail
    action: filter
```

**Notes**

The condition issues one Graph call the first time it evaluates for a given object; the result is cached for 300 seconds. If the calling app identity lacks `GroupMember.Read.All`, the resolution returns an empty list and the condition evaluates false silently — confirm the scope is granted when matches do not fire as expected.

## object_attribute

An object check that matches on a directory attribute of the target Graph object. Supports three operators: `eq` (exact match), `contains` (substring match), and `regex` (PCRE).

**YAML shape**

```yaml
- type: object_attribute
  attribute: "userType"
  value: "Guest"
  operator: eq
```

**Example — block guest access to the members endpoint**

```yaml
rules:
  - id: block-guests-from-members
    match:
      app_id: "*"
      methods: ["GET"]
      endpoint_pattern: "/users*"
    conditions:
      - type: object_attribute
        attribute: "userType"
        value: "Guest"
        operator: eq
    action: block
```

**Notes**

`attribute` names a top-level property on the Graph object (for example, `userType`, `department`, `jobTitle`). Nested properties are reached with dot notation where supported by the response shape. The `regex` operator accepts PCRE; anchor the pattern explicitly (`^...$`) when you intend a full-string match.

## domain

An object check that matches when the target object's primary email domain is in a configured list.

**YAML shape**

```yaml
- type: domain
  domains:
    - contoso.com
    - fabrikam.com
```

**Example — allow only corporate domains on user reads**

```yaml
rules:
  - id: corporate-domains-only
    match:
      app_id: "*"
      methods: ["GET"]
      endpoint_pattern: "/users*"
    conditions:
      - type: domain
        domains:
          - contoso.com
    action: allow
```

**Notes**

Domain comparison is case-insensitive. The check reads the target object's `mail` or `userPrincipalName` domain — guest accounts with mismatched `mail` and `userPrincipalName` domains may match or miss depending on which the Graph payload carries. Log an evaluation sample before relying on this condition for sensitive routes.

## custom_attribute

An object check that matches on a Directory Extension attribute (also called a custom attribute in the Azure AD portal).

**YAML shape**

```yaml
- type: custom_attribute
  extension_name: "extension_abc123_employeeClass"
  value: "restricted"
```

**Example — block reads on users flagged with a custom restriction**

```yaml
rules:
  - id: restricted-employees-block
    match:
      app_id: "*"
      methods: ["GET"]
      endpoint_pattern: "/users*"
    conditions:
      - type: custom_attribute
        extension_name: "extension_abc123_employeeClass"
        value: "restricted"
    action: block
```

**Notes**

`extension_name` is the full Directory Extension property name as it appears in the Graph response — it includes the app registration GUID fragment (`extension_<guid-without-hyphens>_<schemaAttr>`). Copy the name from a Graph response body rather than re-deriving it from the schema extension definition.

<x-doc.callout type="note">

For the exact extension-property naming rules, see the Microsoft Graph Directory Extensions documentation. This condition compares string-equal against the value returned by Graph; numeric or boolean extensions are compared as their string rendering.

</x-doc.callout>

## administrative_unit

An object check that matches when the target object belongs to a specified Azure AD Administrative Unit.

**YAML shape**

```yaml
- type: administrative_unit
  au_id: "11111111-2222-3333-4444-555555555555"
```

**Example — restrict a rule to a regional Administrative Unit**

```yaml
rules:
  - id: eu-region-only
    match:
      app_id: "*"
      methods: ["GET", "PATCH"]
      endpoint_pattern: "/users*"
    conditions:
      - type: administrative_unit
        au_id: "11111111-2222-3333-4444-555555555555"
    action: allow
```

**Notes**

AU membership requires one Graph call to resolve; the result caches for 600 seconds (longer than `group_membership` because AU membership changes less often). The calling app identity must have `AdministrativeUnit.Read.All` or equivalent; without it, the condition returns false.

## assigned_license

An object check that matches when the target user has an assigned licence SKU.

**YAML shape**

```yaml
- type: assigned_license
  sku_id: "ENTERPRISEPACK"
```

**Example — limit password-reset endpoint to E3-licensed users**

```yaml
rules:
  - id: e3-only-password-reset
    match:
      app_id: "*"
      methods: ["POST"]
      endpoint_pattern: "/users/*/authentication/passwordMethods*"
    conditions:
      - type: assigned_license
        sku_id: "ENTERPRISEPACK"
    action: allow
```

**Notes**

`sku_id` accepts either the human-readable SKU part number (`ENTERPRISEPACK` for E3) or the SKU UUID. The match reads the user's `assignedLicenses` array from Graph; disabled service plans within an assigned SKU still count the SKU as assigned. Use `object_attribute` against `assignedPlans` if you need a service-plan-level check.

## caller_identity

A request check that matches on the GraphWarden App Identity making the request. Typically used to scope a rule to a specific calling application.

**YAML shape**

```yaml
- type: caller_identity
  app_id: "f63c4abc-0000-0000-0000-000000000000"
```

**Example — allow the HR app to read the full user list, block others**

```yaml
rules:
  - id: hr-app-full-read
    match:
      methods: ["GET"]
      endpoint_pattern: "/users*"
    conditions:
      - type: caller_identity
        app_id: "f63c4abc-0000-0000-0000-000000000000"
    action: allow

  - id: others-block
    match:
      methods: ["GET"]
      endpoint_pattern: "/users*"
    action: block
```

**Notes**

The `app_id` field is optional — a `caller_identity` condition without an `app_id` matches when the request was authenticated by any registered App Identity (useful as a presence check). Per-app routing is more commonly expressed via the rule-level `match.app_id` field; reserve `caller_identity` conditions for cases where the app-identity check composes with other gating logic via `logic_group`.

## time_window

A request check that matches when the request arrives within a configured time-of-day window.

**YAML shape**

```yaml
- type: time_window
  start_time: "09:00"
  end_time: "17:00"
  utc_offset: "-05:00"
```

**Example — allow destructive admin operations only during business hours**

```yaml
rules:
  - id: business-hours-only
    match:
      app_id: "*"
      methods: ["DELETE", "PATCH"]
      endpoint_pattern: "/users*"
    conditions:
      - type: time_window
        start_time: "09:00"
        end_time: "17:00"
        utc_offset: "-05:00"
    action: allow
```

**Notes**

`start_time` and `end_time` are 24-hour `HH:MM` strings. `utc_offset` accepts a signed `±HH:MM` offset — use it to pin the window to a business-hours zone regardless of where the proxy host runs. A window that crosses midnight (for example, `22:00` to `06:00`) is supported; the condition evaluates true if the current time is at or after `start_time` OR before `end_time`. Daylight-saving transitions track the host clock; pin `utc_offset` to the standard-time value if predictability across DST matters.

## rate_limit

A request check that enforces a sliding-window request cap per authenticated identity.

**YAML shape**

```yaml
- type: rate_limit
  max_requests: 100
  window_seconds: 60
```

**Example — throttle batch requests to 10 per minute**

```yaml
rules:
  - id: batch-rate-cap
    match:
      methods: ["POST"]
      endpoint_pattern: "/$batch"
    conditions:
      - type: rate_limit
        max_requests: 10
        window_seconds: 60
    action: block
```

**Notes**

The rate counter is keyed on the calling App Identity. When `max_requests` is exceeded within `window_seconds`, the condition evaluates true — pair with `action: block` to deny the over-limit request. The rate window is sliding, not fixed: each request is counted against the trailing `window_seconds` from its arrival. A proxy restart resets the in-memory counters.

## object_count_limit

A response check that matches when the Graph response result set exceeds a configured size.

**YAML shape**

```yaml
- type: object_count_limit
  max_count: 100
  threshold_percent: 90
```

**Example — block large enumeration responses**

```yaml
rules:
  - id: cap-user-list-size
    match:
      app_id: "*"
      methods: ["GET"]
      endpoint_pattern: "/users*"
    conditions:
      - type: object_count_limit
        max_count: 100
        threshold_percent: 90
    action: block
```

**Notes**

This condition evaluates after the Graph response arrives at the proxy, before the response is returned to the caller. `max_count` sets the hard cap; `threshold_percent` sets an early-warning level (log-only observation the proxy records when responses exceed the threshold but stay under the cap). Use this condition to catch accidental full-directory enumerations by narrowly scoped apps.

## ip_range

A request check that matches when the caller IP falls inside one or more CIDR ranges.

**YAML shape**

```yaml
- type: ip_range
  cidrs:
    - 10.0.0.0/8
    - 192.168.1.0/24
```

**Example — allow admin endpoints only from corporate network ranges**

```yaml
rules:
  - id: admin-from-corp-net
    match:
      app_id: "*"
      methods: ["POST", "DELETE"]
      endpoint_pattern: "/directoryRoles*"
    conditions:
      - type: ip_range
        cidrs:
          - 10.0.0.0/8
          - 192.168.1.0/24
    action: allow
```

**Notes**

The proxy reads the caller IP from the TCP connection by default. When the proxy runs behind a load balancer or reverse proxy, configure the upstream to forward `X-Forwarded-For` and enable `ForwardedHeaders` on the proxy host; otherwise every caller IP resolves to the load-balancer address. IPv4 and IPv6 CIDR ranges are accepted; mix them freely in the `cidrs` list.

## Combining conditions

Top-level conditions within a single rule combine with **AND** semantics — all conditions must evaluate true for the rule to match and its `action` to apply. Rules in a ruleset are evaluated **top-down, first-match-wins**: once a rule matches, evaluation stops and subsequent rules are not considered.

For OR or NOT semantics within a single condition, attach a `logic_group` key and a `variants:` list:

```yaml
conditions:
  - type: group_membership
    logic_group: "any_of"
    variants:
      - group_id: "00000000-0000-0000-0000-000000000001"
      - group_id: "00000000-0000-0000-0000-000000000002"

  - type: object_attribute
    attribute: "department"
    logic_group: "none_of"
    variants:
      - value: "HR"
      - value: "Finance"
```

`logic_group` accepts three values: `all_of` (the default AND semantics), `any_of` (OR — the condition matches if any variant matches), and `none_of` (NOT — the condition matches if none of the variants match).

When no rule matches an incoming request, the proxy's default behaviour is `allow` (pass through to Graph). Operators who want default-deny place a catch-all rule at the end of the ruleset with `match.methods: ["*"]` and `action: block`.

<x-doc.ai-prompt title="Generate a condition for a GraphWarden rule" uid="condition-types-generate">
Help me write a GraphWarden condition that matches {describe the scenario — which users or requests should trigger, under what gating logic, and what the rule should do when matched}. Use the 11 condition types documented at /docs/api-reference/condition-types, pick the smallest set that expresses the intent, and return a complete rule block including `match:`, `conditions:`, and `action:`. If the intent needs OR or NOT semantics, use `logic_group` with `any_of` or `none_of`. Do not invent new condition type names; only the 11 documented types exist.
</x-doc.ai-prompt>

## Troubleshooting

### A condition referencing a group UUID silently does not match

The `group_membership` and `administrative_unit` conditions issue Graph calls to resolve transitive membership. If the calling App Identity lacks `GroupMember.Read.All` or `AdministrativeUnit.Read.All`, the resolution returns an empty list and the condition evaluates false with no error surfaced to the caller. Confirm the scope is granted on the App Identity; the proxy logs a warning when resolution returns zero groups for a user who should have some.

### The regex operator on object_attribute does not match

The `regex` operator on `object_attribute` accepts PCRE. Anchor the pattern with `^` and `$` when you intend a full-string match — an unanchored pattern is treated as a substring search by most PCRE engines, which matches more values than operators often expect. Test the pattern against a known Graph response value before deploying.

### time_window matches off-by-one across daylight-saving transitions

The `utc_offset` field is a static signed offset, not a time-zone name. Pinning `utc_offset` to `-04:00` holds the window at Eastern Daylight Time year-round, which is one hour off during Standard Time. If the business rule is "09:00 to 17:00 in New York all year," pin `utc_offset` to the standard-time offset (`-05:00`) and accept the one-hour shift during DST, or split the rule across two rulesets swapped on the transition dates.

### ip_range matches every request to the load balancer IP

Behind a load balancer or reverse proxy, the TCP connection IP the proxy sees is the load-balancer IP, not the original caller. Configure the upstream to set `X-Forwarded-For` and enable forwarded-headers processing on the proxy host. Without that, every `ip_range` condition evaluates true or false uniformly based on the load-balancer address and not the real caller.

### A rule with multiple conditions never matches even though each condition is correct alone

Top-level conditions combine with AND semantics. If the intent was OR, wrap the alternatives inside a single condition with `logic_group: "any_of"` and a `variants:` list rather than listing them as separate top-level conditions. The Admin app's What-If simulator shows which conditions evaluated true and which did not — use it to isolate the failing branch.

For the response-side transformations that apply when a rule matches with `action: filter`, see [Transform types](./transform-types).

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden proxy environment variables

# 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.

<x-doc.status-badge status="supported">Proxy runtime configuration — shipped</x-doc.status-badge>

<x-doc.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)

</x-doc.prerequisites>

<x-doc.callout type="info">
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.
</x-doc.callout>

## Core identity

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

<table>
<thead>
<tr><th>Variable</th><th>Required</th><th>Default</th><th>Purpose</th></tr>
</thead>
<tbody>
<tr><td><code>Kestrel:MaxRequestBodySizeMb</code></td><td>No</td><td>10</td><td>Maximum HTTP request body size accepted by Kestrel, in megabytes.</td></tr>
<tr><td><code>GRAPHWARDEN__URL</code></td><td>No</td><td>(none)</td><td>Presence (non-empty) signals hosted deployment. When set, file-based config store writes are disabled.</td></tr>
</tbody>
</table>

## 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.

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

## Cache

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

<table>
<thead>
<tr><th>Variable</th><th>Required</th><th>Default</th><th>Purpose</th></tr>
</thead>
<tbody>
<tr><td><code>Cache:UseRedis</code></td><td>No</td><td><code>false</code></td><td>Enable Redis-backed cache. Requires <code>ConnectionStrings:Redis</code>.</td></tr>
<tr><td><code>ConnectionStrings:Redis</code></td><td>Yes (if <code>Cache:UseRedis=true</code>)</td><td>(empty)</td><td>Redis server address in <code>host:port</code> form.</td></tr>
</tbody>
</table>

## 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.

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

## Proxy JWT

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

<table>
<thead>
<tr><th>Variable</th><th>Required</th><th>Default</th><th>Purpose</th></tr>
</thead>
<tbody>
<tr><td><code>ProxyJwt:SigningKey</code></td><td>Yes</td><td>(empty)</td><td>Symmetric secret used to sign proxy JWTs. Minimum 32 characters recommended; treat as a production secret.</td></tr>
<tr><td><code>ProxyJwt:Issuer</code></td><td>No</td><td><code>graphproxy</code></td><td>JWT <code>iss</code> claim value.</td></tr>
<tr><td><code>ProxyJwt:Audience</code></td><td>No</td><td><code>graphproxy</code></td><td>JWT <code>aud</code> claim value.</td></tr>
</tbody>
</table>

## Admin and rules

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

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

## 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.

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

## 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.

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

## Audit ingestion

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

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

## Logging

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

<table>
<thead>
<tr><th>Variable</th><th>Required</th><th>Default</th><th>Purpose</th></tr>
</thead>
<tbody>
<tr><td><code>Logging:LogLevel:Default</code></td><td>No</td><td><code>Information</code></td><td>Serilog default level for framework and third-party namespaces.</td></tr>
<tr><td><code>Logging:LogLevel:GraphProxy</code></td><td>No</td><td><code>Debug</code></td><td>Serilog level for the <code>GraphProxy.*</code> namespaces.</td></tr>
</tbody>
</table>

## 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. |

<x-doc.callout type="note">
The three client-side names do not follow the proxy's <code>__</code> 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.
</x-doc.callout>

## 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.

<x-doc.last-reviewed date="2026-04-19" />



## Rule schema: the GraphWarden ruleset YAML format

# Rule schema: the GraphWarden ruleset YAML format

GraphWarden rulesets are YAML documents with a top-level `rules` list. Each rule pairs a `match` block with optional `conditions`, an optional `response_filter`, and an `action`. This page documents the top-level shape and lists the eleven condition types and nine transform types by name; per-type deep dives are deferred to Phase 6 documentation.

<x-doc.status-badge status="supported">Ruleset YAML — top-level shape and keys</x-doc.status-badge>

<x-doc.prerequisites>

- Access to the GraphWarden Admin app OR a ruleset YAML file on disk
- A YAML-aware editor (the proxy parses YAML 1.2)
- Familiarity with the rulesets and rules concept page

</x-doc.prerequisites>

## Top-level shape

A ruleset is a YAML document whose root key is `rules` — an ordered list of rule objects. The minimal ruleset below allows GET requests to `/users` and has no other rules.

```yaml
rules:
  - id: allow-user-read
    match:
      app_id: "*"
      methods: ["GET"]
      endpoint_pattern: "/users*"
    action: allow
```

The canonical reference ruleset from the proxy's fixture library exercises every top-level key:

```yaml
rules:
  - id: hr-app-restrict-users
    match:
      app_id: "f63c4abc-..."
      methods: ["GET"]
      endpoint_pattern: "/users*"
    conditions:
      - type: group_membership
        group_id: "00000000-0000-0000-0000-000000000001"
    response_filter:
      allow_properties:
        - id
        - displayName
        - mail
        - department
        - manager:
            - id
            - displayName
    action: filter
    cache_ttl: 300

  - id: block-sensitive-graph-paths
    match:
      app_id: "*"
      methods: ["DELETE", "PATCH"]
      endpoint_pattern: "/identityRiskDetections*"
    action: block
```

## Rule-level keys

Every rule object supports the following keys. `match.methods`, `match.endpoint_pattern`, and `action` are required; the rest are optional.

| Key | Type | Required | Purpose |
|-----|------|----------|---------|
| `id` | string | No | Human- or UUID-style identifier. Used in audit events to identify which rule matched. |
| `match.app_id` | UUID or `"*"` | No (default `"*"`) | The App Identity the rule applies to. `"*"` matches any calling app. |
| `match.methods` | list of strings | Yes | HTTP methods the rule considers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). |
| `match.endpoint_pattern` | string | Yes | OData-style endpoint pattern. Supports `*` as a suffix wildcard (for example, `/users*`). |
| `conditions` | list of condition objects | No | Gating logic evaluated with AND semantics by default. See condition types below. |
| `response_filter` | object | No | Applied when `action: filter`. Contains `allow_properties` (whitelist) OR `strip_properties` (blacklist). |
| `action` | string | Yes | Final verdict: `allow`, `filter`, `block`, or `log_only`. |
| `cache_ttl` | integer (seconds) | No | How long to cache the rule-to-object match. `0` or absent means no caching. |

### Action values

| Action | Behavior |
|--------|----------|
| `allow` | Return the Graph response unchanged. |
| `filter` | Apply `response_filter` transforms before returning. |
| `block` | Return HTTP 403, never call Graph. |
| `log_only` | Allow the request and emit an audit event. Useful for detection rules without enforcement. |

## Condition types (11 total)

The proxy supports eleven condition types. Each condition is a YAML object keyed on `type`, with type-specific fields. Per-type documentation — every field, every Graph call, every cache behaviour — is deferred to Phase 6.

- `group_membership` — match on Azure AD security-group membership of the target object.
- `object_attribute` — match on a directory attribute with `eq`, `contains`, or `regex` operators.
- `domain` — match on the email domain of the target object.
- `custom_attribute` — match on a Directory Extension attribute.
- `administrative_unit` — match on Administrative Unit membership.
- `assigned_license` — match on assigned SKU licence.
- `caller_identity` — match on the calling App Identity.
- `time_window` — match on time-of-day windows with UTC offset support.
- `rate_limit` — enforce a sliding-window request rate per identity.
- `object_count_limit` — cap the size of the returned result set.
- `ip_range` — match on caller IP against one or more CIDR ranges.

See Phase 6 for per-type documentation — field inventories, Graph call impact, cache behaviour, and worked examples.

### Condition composition

Top-level conditions within a single rule combine with AND semantics — all conditions must be true for the rule to match. For OR or NOT semantics, attach a `logic_group` key and a `variants` list to the condition:

```yaml
conditions:
  - type: group_membership
    logic_group: "any_of"
    variants:
      - group_id: "group-1-uuid"
      - group_id: "group-2-uuid"

  - type: object_attribute
    attribute: "department"
    logic_group: "none_of"
    variants:
      - value: "HR"
      - value: "Finance"
```

`logic_group` accepts `any_of` (OR), `all_of` (AND — the default behaviour), and `none_of` (NOT).

## Transform types (9 total)

Transforms apply to response properties when `action: filter` matches. Each transform is identified by name; per-type documentation with input/output examples is deferred to Phase 6.

- `mask_start` — hide the first N characters of a string.
- `mask_end` — hide the last N characters of a string.
- `redact` — replace the property value with a sentinel (for example, `[redacted]`).
- `hash` — replace the value with its SHA256 hex digest.
- `truncate` — trim a string to N characters.
- `regex_replace` — match a regex and substitute a template.
- `domain_only` — extract the domain portion of an email address.
- `initials` — extract initials from a display name.
- `noise` — append a random suffix to break aggregation.

See Phase 6 for per-transform documentation — input/output shapes, edge cases, and performance characteristics.

### Response filter usage

Without transforms, a response filter operates on property whitelisting or blacklisting alone:

```yaml
response_filter:
  allow_properties:
    - id
    - displayName
    - mail
    - manager:
        - id
        - displayName
  strip_properties:
    - passwordHash
    - onPremisesExtensionAttributes
```

`allow_properties` is a whitelist: only the listed properties pass through, and nested objects carry their own sub-list. `strip_properties` is a blacklist: the listed properties are removed, and all others pass through unchanged. A single `response_filter` uses one form or the other, not both.

## Evaluation order

Rules in a ruleset are evaluated top-down, **first-match-wins**. Once a rule matches:

1. The proxy evaluates the rule's `conditions` (AND of all top-level conditions unless `logic_group` overrides).
2. If all conditions are true, the `action` is applied.
3. Evaluation stops — subsequent rules are not considered.

If no rule matches the incoming request, the proxy's default behaviour is `allow` (pass through to Graph). Operators who want default-deny place a catch-all rule with `match.methods: ["*"]` and `action: block` at the end of the ruleset.

## Validating a ruleset

The GraphWarden Admin app validates a ruleset on save — schema errors surface immediately in the UI. For ad-hoc validation outside the Admin app, the proxy exposes a dry-run mode: load the ruleset file locally, start the proxy with `Rules:FilePath` pointing at it, and inspect the startup log. Parse errors surface as startup failures; logical issues (for example, a condition naming an unknown group UUID) surface on first request evaluation.

A dedicated `graphwarden rules validate <file>` CLI is deferred to Phase 6. For now, rely on the Admin app's editor validation or the startup-log signal.

## Troubleshooting

### The proxy refuses to start with "RuleLoader: invalid YAML"

The ruleset file has a YAML parse error — indentation mismatch, unterminated quotes, or tab characters where spaces are required. The log line names the offending file and line. Run the file through any YAML linter (for example, `yamllint`) to isolate the issue before restarting the proxy.

### A rule evaluates as "no match" even though the endpoint looks right

Check `match.endpoint_pattern` for a leading slash and a trailing wildcard where needed. Graph paths like `/users/{id}` match `/users*`, but `/users*` does not match `/users` alone unless the pattern is written `/users(/*)?` or listed as two entries. The pattern is a prefix-plus-wildcard, not a regex.

### A condition referencing a group UUID silently does not match

The `group_membership` condition issues a Graph call to resolve transitive membership. If the calling App Identity lacks the `GroupMember.Read.All` scope, the resolution returns an empty list and the condition evaluates false. Confirm the scope is granted; the proxy logs a warning when the resolution returns zero groups for a user who should have some.

### A `response_filter` returns 500 at request time

The most common cause: `allow_properties` names a property that does not exist on the Graph response (for example, a misspelled `manger` instead of `manager`). The proxy treats the filter as malformed and fails the request rather than silently shipping an empty object. Verify each property name against the Graph response shape for the endpoint.

### `action: filter` is set but the response is returned unchanged

The response filter is not applied when conditions on the rule evaluate false. Confirm that the rule actually matched: the audit event records the matched `rule_id` or `null` when no rule matched. A null `rule_id` means the default `allow` applied, not the filter-bearing rule.

For the HMAC-authenticated endpoints that ship rulesets from the control plane to the proxy, see the agent API reference.

<x-doc.last-reviewed date="2026-04-19" />



## Transform types: all 9 transformations used in GraphWarden rulesets

# Transform types: all 9 transformations used in GraphWarden rulesets

When a GraphWarden rule matches with `action: filter`, its `response_filter` can apply per-property transforms before the response returns to the caller. The nine transform types cover masking, redaction, hashing, truncation, regex substitution, domain extraction, initials, and noise injection. This page documents each transform with its YAML shape and a before/after example. See the [rule schema reference](./rule-schema) for the top-level YAML contract and [Condition types](./condition-types) for the gating layer that decides when a transform runs.

<x-doc.status-badge status="supported">Transform types — full inventory</x-doc.status-badge>

<x-doc.prerequisites>

- Familiarity with rulesets and conditions — see [Condition types](./condition-types)
- A YAML-aware text editor (the proxy parses YAML 1.2)
- Read access to the [rule schema reference](./rule-schema) for the top-level `rules:` shape

</x-doc.prerequisites>

## Transform mechanics

Transforms attach to properties inside a `response_filter:` block on a rule. The rule's `action` must be `filter` for transforms to run — any other action (`allow`, `block`, `log_only`) skips the response filter entirely. Each transform is a YAML object with a `type` field plus type-specific configuration fields, attached to the property whose value it should modify:

```yaml
response_filter:
  allow_properties:
    - id
    - displayName
    - mail:
        transform:
          type: mask_end
          visible: 5
```

<x-doc.callout type="note">

Transforms operate on string-valued properties unless noted otherwise. Non-string values (numbers, booleans, nested objects) pass through `allow_properties` unchanged. Use `strip_properties` to remove non-transformable properties entirely.

</x-doc.callout>

## mask_start

Hides the first N characters of a string with a mask character, preserving the suffix. Useful for partially revealing a value while hiding its start.

**YAML shape**

```yaml
type: mask_start
visible: 5
mask_char: "*"
```

**Before and after**

| Input | Output |
|-------|--------|
| `"Alice Wonderland"` | `"*********erland"` |
| `"0123456789"` | `"*****56789"` |

**Notes**

`visible` is the count of trailing characters that remain readable (the tail length). `mask_char` defaults to `*` and may be any single character. When the input is shorter than `visible`, the entire string is returned unmasked. Empty strings and `null` values pass through untouched.

## mask_end

Hides the last N characters of a string with a mask character, preserving the prefix. The mirror of `mask_start`.

**YAML shape**

```yaml
type: mask_end
visible: 5
mask_char: "*"
```

**Before and after**

| Input | Output |
|-------|--------|
| `"alice@example.com"` | `"alice************"` |
| `"4111111111111111"` | `"41111***********"` |

**Notes**

`visible` is the count of leading characters that remain readable. Commonly used for partial-visibility display of email addresses, phone numbers, and account numbers. When the input is shorter than `visible`, the entire string is returned unmasked.

## redact

Replaces the property value with a fixed sentinel string. Hides the value entirely without removing the property key from the response.

**YAML shape**

```yaml
type: redact
replacement: "[redacted]"
```

**Before and after**

| Input | Output |
|-------|--------|
| `"alice@contoso.com"` | `"[redacted]"` |
| `"555-1234"` | `"[redacted]"` |

**Notes**

`replacement` defaults to `"[redacted]"` and may be any string. Prefer `redact` over `strip_properties` when the caller's client code expects the property key to exist in the response — redaction preserves the schema shape while hiding the value. For complete removal (key absent from the response), use `strip_properties` instead.

## hash

Replaces the value with its SHA256 hex digest. Preserves uniqueness across responses while hiding the original value.

**YAML shape**

```yaml
type: hash
algorithm: sha256
encoding: hex
```

**Before and after**

| Input | Output |
|-------|--------|
| `"alice@contoso.com"` | `"4d5b2e1f..."` (64-char SHA256 hex) |
| `"bob@contoso.com"` | `"2a7f9c83..."` (64-char SHA256 hex) |

**Notes**

`algorithm` currently accepts `sha256` only; `encoding` accepts `hex` (default) or `base64`. Deterministic: the same input always yields the same output. Use when downstream consumers need a stable identifier for analytics or joins without the plaintext value. Because the algorithm is unsalted, the output is subject to rainbow-table inference for small value spaces — do not use `hash` as a substitute for encryption.

## truncate

Trims a string to a configured maximum length. Values longer than the limit are clipped; values shorter are returned unchanged.

**YAML shape**

```yaml
type: truncate
max_length: 50
suffix: "..."
```

**Before and after**

| Input | Output |
|-------|--------|
| `"This is a long description exceeding fifty characters here"` | `"This is a long description exceeding fifty chara..."` |
| `"Short text"` | `"Short text"` |

**Notes**

`max_length` counts characters of the truncated output **including** the `suffix`. `suffix` defaults to an empty string; set it to `"..."` to signal truncation explicitly. When `max_length` is less than the suffix length, the suffix is returned alone with no source characters. Byte-boundary handling treats multi-byte UTF-8 sequences as single characters — you will not split a code point.

## regex_replace

Matches a PCRE pattern against the input and substitutes the match with a template string. Supports capture-group references in the replacement.

**YAML shape**

```yaml
type: regex_replace
pattern: "(\\d{4})\\d{4}(\\d{4})"
replacement: "$1****$2"
```

**Before and after**

| Input | Output |
|-------|--------|
| `"411111112222 4444"` (card-like) | `"4111****4444"` (with pattern stripping spaces) |
| `"user@contoso.com"` with pattern `"^(.).*@"` and replacement `"$1***@"` | `"u***@contoso.com"` |

**Notes**

`pattern` is a PCRE regular expression. Backslashes inside YAML double-quoted strings must be escaped — prefer single-quoted YAML strings (`'(\d{4})\d{4}(\d{4})'`) to keep the pattern readable. `replacement` supports `$1`, `$2`, etc. for capture-group backreferences. When the pattern does not match, the input is returned unchanged. Use anchored patterns (`^...$`) for predictable behaviour on sensitive fields; unanchored patterns can match unintended substrings.

## domain_only

Extracts the domain portion of an email-shaped string. Drops the local part and the `@` separator.

**YAML shape**

```yaml
type: domain_only
```

**Before and after**

| Input | Output |
|-------|--------|
| `"alice@contoso.com"` | `"contoso.com"` |
| `"bob.smith@sub.fabrikam.com"` | `"sub.fabrikam.com"` |

**Notes**

The transform splits on the first `@` character and returns the suffix. Inputs without an `@` (for example, a display name) are returned unchanged — this is a silent pass-through rather than an error. Commonly paired with analytics pipelines that need domain-level aggregation without caller identity.

## initials

Extracts initials from a display-name string. Takes the first character of each whitespace-separated token and uppercases them.

**YAML shape**

```yaml
type: initials
max_length: 3
```

**Before and after**

| Input | Output |
|-------|--------|
| `"John Doe"` | `"JD"` |
| `"Alice May Wonderland"` | `"AMW"` |
| `"Jean-Luc Picard"` (hyphenated) | `"JP"` |

**Notes**

`max_length` caps the output length. Tokens are split on whitespace only; hyphenated or apostrophe-separated names produce a single initial per whitespace-separated token. Empty strings return empty. Diacritics on the first character are preserved (`"Élise Durand"` yields `"ÉD"`).

## noise

Appends a random suffix to a string, preserving the prefix. Breaks exact-match aggregation without fully redacting the value.

**YAML shape**

```yaml
type: noise
suffix_length: 6
separator: "_"
```

**Before and after**

| Input | Output |
|-------|--------|
| `"alice"` | `"alice_3f7k2b"` |
| `"alice"` (same input, second call) | `"alice_9m4p1q"` |

**Notes**

The suffix is non-deterministic — the same input produces a different output on each call. Use `noise` to defeat downstream correlation (for example, to prevent log aggregators from grouping by user identifier) without losing the readable prefix. Not suitable when downstream consumers rely on value equality across responses; reach for `hash` for that case.

## Transform ordering within a rule

When a property carries a transform, the transform runs after `allow_properties` whitelisting or `strip_properties` blacklisting and before the response is returned to the caller. A single property declares a single transform — chaining multiple transforms on the same property is not supported in a single rule. To chain (for example, `regex_replace` then `truncate` on the same field), split the logic across two rules whose `match:` blocks both cover the endpoint, ordered so the more-specific rule runs first under the ruleset's first-match-wins evaluation.

Within a single response filter, transforms on different properties run independently and order between them is not observable — each transform reads the original Graph response value for its property, not the output of any sibling transform.

## Interaction with response filtering vs request transformation

Transforms operate on the **outbound response** from Graph, never on the inbound request. Request-side shaping (blocking, rate-limiting, caller-identity checks) is expressed through [condition types](./condition-types) on the rule, not through transforms. A rule with `action: filter` runs its transforms after Graph returns; a rule with `action: block` rejects the request before it reaches Graph and never runs transforms.

When `response_filter` declares `allow_properties` with a transform, the whitelist step runs first — properties absent from `allow_properties` are removed unconditionally, and only surviving properties with a `transform:` key run their transform. When `response_filter` declares `strip_properties`, the blacklist runs first and the transform runs on surviving properties. You can attach a transform to a property only when that property survives the whitelist or blacklist step.

<x-doc.ai-prompt title="Generate a transform for a GraphWarden response filter" uid="transform-types-generate">
Help me write a GraphWarden transform that {describe the input property, the privacy or shaping goal, and whether the output should be deterministic or random}. Use the 9 transform types documented at /docs/api-reference/transform-types, pick the single transform type that expresses the intent, and return a complete `response_filter` block with the property path and the transform configuration. Do not invent new transform type names; only the 9 documented types exist. If the intent needs multiple transforms on the same property, split across two rules ordered under the first-match-wins evaluation.
</x-doc.ai-prompt>

## Troubleshooting

### The transform is declared but the response is returned unchanged

The response filter is applied only when `action: filter` is set on the rule AND the rule's conditions evaluate true. If `action` is any other value (`allow`, `block`, `log_only`), the transform is skipped. Check the audit event for the request — a `null` `rule_id` means no rule matched and the default `allow` applied, not the filter-bearing rule. The What-If simulator in the Admin app shows which rule matched and which transforms ran.

### regex_replace does not match the pattern I tested against in an online regex tool

Backslashes inside YAML double-quoted strings are interpreted by the YAML parser before reaching the regex engine. A pattern written `"\d{4}"` in double quotes reaches the regex engine as `d{4}`. Wrap regex patterns in single quotes (`'\d{4}'`) to pass the backslashes through verbatim, or double-escape them (`"\\d{4}"`). Prefer single quotes — they are the least error-prone.

### hash produces different outputs between two proxy instances for the same input

The `hash` transform is deterministic per algorithm and input — two instances running the same algorithm on the same input always produce the same hex digest. Differences indicate the input bytes differ across instances. Trailing whitespace, encoding differences (UTF-8 BOM), or case variations are the usual culprits; compare the raw bytes of the Graph response property across instances to isolate the divergence.

### mask_start or mask_end returns the full string unmasked

When `visible` is greater than or equal to the input length, the transform returns the input unchanged — there is nothing left to mask. Confirm the expected input length; a short value like `"ABC"` with `visible: 5` returns `"ABC"`. For properties with highly variable length (free-text fields), prefer `truncate` plus a fixed suffix or `regex_replace` with an anchored pattern.

### A transform on a nested property does not run

Transforms attach to property names inside `allow_properties`. Nested properties are reached through the response-shape nesting under the parent property — for example, `manager.mail` is a nested property under `manager`, not a top-level property. Declare the transform under the parent's nested list:

```yaml
response_filter:
  allow_properties:
    - id
    - displayName
    - manager:
        - id
        - mail:
            transform:
              type: mask_end
              visible: 5
```

For the gating layer that decides when each rule's transforms fire, see [Condition types](./condition-types).

<x-doc.last-reviewed date="2026-04-19" />



## Run GraphWarden proxy deployments from Azure DevOps Pipelines

# Run GraphWarden proxy deployments from Azure DevOps Pipelines

A complete Azure DevOps YAML pipeline that builds, tests, and smoke-tests a GraphWarden proxy deployment. Variable groups hold credentials and a banner comment prevents accidental commits of real secrets. The template below is runnable after replacing the marked values with your organization's tenant, client id, and secret.

<x-doc.status-badge status="supported">Azure DevOps Pipelines with variable groups</x-doc.status-badge>

<x-doc.prerequisites>

- An Azure DevOps organization and project where you can edit pipelines and create variable groups
- A variable group named `graphwarden-secrets` containing `GRAPHWARDEN_PROXY_URL`, `GRAPHWARDEN_CLIENT_ID`, and `GRAPHWARDEN_CLIENT_SECRET` (covered on the secrets-management page in this section)
- A Microsoft-hosted agent (the `ubuntu-latest` image used below) or a self-hosted agent that can reach your GraphWarden proxy URL

</x-doc.prerequisites>

<x-doc.ai-prompt title="Add a GraphWarden smoke test with an AI assistant">
Add a GraphWarden smoke test to my existing Azure DevOps YAML pipeline.

I want a pipeline stage that:
1. Acquires a token from my GraphWarden proxy's /oauth2/v2.0/token endpoint
2. Fails the build if token acquisition fails
3. Uses variable-group-backed secrets (not inline values)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my existing azure-pipelines.yml and whether my variable group is already configured.
</x-doc.ai-prompt>

## The pipeline, end to end

The YAML below is a complete Azure DevOps pipeline. Copy it into a file named `azure-pipelines.yml` at the root of your repository. Do not edit the variable references — the pipeline reads every secret from the `graphwarden-secrets` variable group at run time.

<x-doc.code-block lang="yaml">
# DO NOT COMMIT REAL SECRETS TO THIS FILE.
# Use the Azure DevOps UI to create a variable group "graphwarden-secrets"
# with GRAPHWARDEN_PROXY_URL, GRAPHWARDEN_CLIENT_ID, GRAPHWARDEN_CLIENT_SECRET.

trigger:
  branches:
    include:
      - main

variables:
  - group: graphwarden-secrets
  - name: dotnetVersion
    value: '8.0.x'

stages:
  - stage: BuildAndTest
    jobs:
      - job: Build
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: UseDotNet@2
            inputs:
              version: $(dotnetVersion)
          - script: dotnet restore
            displayName: 'Restore dependencies'
          - script: dotnet build --configuration Release --no-restore
            displayName: 'Build proxy'
          - script: dotnet test --configuration Release --no-build --logger trx
            displayName: 'Run proxy tests'
          - task: PublishTestResults@2
            condition: succeededOrFailed()
            inputs:
              testResultsFormat: 'VSTest'
              testResultsFiles: '**/*.trx'

  - stage: IntegrationTest
    dependsOn: BuildAndTest
    jobs:
      - job: SmokeTest
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: PowerShell@2
            displayName: 'Run GraphWarden smoke test'
            inputs:
              targetType: 'inline'
              script: |
                # Verify the proxy responds before promoting the build.
                $token = Invoke-RestMethod -Method Post `
                  -Uri "$(GRAPHWARDEN_PROXY_URL)/oauth2/v2.0/token" `
                  -Body @{
                    grant_type = 'client_credentials'
                    client_id = "$(GRAPHWARDEN_CLIENT_ID)"
                    client_secret = "$(GRAPHWARDEN_CLIENT_SECRET)"
                    scope = 'https://graph.microsoft.com/.default'
                  }
                if (-not $token.access_token) {
                  Write-Error "Token acquisition failed against GraphWarden."
                  exit 1
                }
                Write-Host "GraphWarden smoke test passed."
            env:
              GRAPHWARDEN_PROXY_URL: $(GRAPHWARDEN_PROXY_URL)
              GRAPHWARDEN_CLIENT_ID: $(GRAPHWARDEN_CLIENT_ID)
              GRAPHWARDEN_CLIENT_SECRET: $(GRAPHWARDEN_CLIENT_SECRET)
</x-doc.code-block>

<x-doc.callout type="warning">
The `# DO NOT COMMIT REAL SECRETS` banner at the top of the pipeline is there on purpose. A commit that replaces `$(GRAPHWARDEN_CLIENT_SECRET)` with a real value leaks the credential to every clone of the repository and every log line the secret shows up in. Keep the variable-group references unchanged.
</x-doc.callout>

## Variable group setup

The pipeline reads three values from a variable group. Create it once per project.

1. In Azure DevOps, open **Pipelines** > **Library** > **+ Variable group**.
2. Name the group `graphwarden-secrets` (the name the pipeline references).
3. Add three variables: `GRAPHWARDEN_PROXY_URL`, `GRAPHWARDEN_CLIENT_ID`, `GRAPHWARDEN_CLIENT_SECRET`.
4. Click the lock icon next to `GRAPHWARDEN_CLIENT_SECRET` to mark it as secret. Azure DevOps masks secret values in logs and prevents them from being displayed after saving.
5. On the variable group page, open **Pipeline permissions** and grant access to the pipeline that runs `azure-pipelines.yml`.
6. Save the group. The pipeline picks up the values on its next run.

The variable group is organization-scoped; multiple pipelines can reference the same group. For separate environments (staging, production), create one variable group per environment and use a conditional reference in `variables:` to select the correct group at run time.

## Handling ruleset-denied calls in CI

A smoke test that calls real Graph endpoints through a real GraphWarden deployment can hit a ruleset denial (`403 Forbidden` with a `ruleId` in the response body). Ruleset denials are expected behaviour: the customer's security policy has blocked the call. A CI pipeline that treats every 403 as a silent success hides real misconfigurations.

The pattern that works:

- For the smoke test above, use the `/oauth2/v2.0/token` endpoint rather than a Graph endpoint. Token acquisition does not require a specific rule; if it fails, the proxy is unreachable or the credentials are wrong — both are real build failures.
- If you add Graph-endpoint assertions, record the exact endpoints and methods your pipeline exercises. Add a test that asserts a specific rule permits them. A flexible approach: let the smoke test call an endpoint, assert the response status is either `200` or a known-expected `403` with a specific `ruleId`. Anything else is a failure.
- `continueOnError: true` silences denials but also silences network outages, token misconfiguration, and real regressions. Use it only when the denial is expected for the branch under test (for example, a pull-request pipeline that runs against a hardened production ruleset).

## Troubleshooting

### The pipeline reports `Variable group 'graphwarden-secrets' could not be accessed`

The variable group exists but the pipeline does not have permission to read it. Open the variable group in **Pipelines** > **Library**, click **Pipeline permissions**, and add the pipeline to the allow list. For classic pipelines not yet migrated to YAML, the UI asks for permission on the first run; click **Permit** in the pipeline summary.

### `dotnet restore` fails with `Unable to resolve host 'api.nuget.org'`

The agent lacks outbound internet access. Microsoft-hosted agents always have internet; self-hosted agents need outbound TCP 443 to `api.nuget.org`, `www.nuget.org`, and your private NuGet feeds. If you run behind a corporate proxy, set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables on the self-hosted agent service.

### `Invoke-RestMethod` returns `The remote server returned an error: (404) Not Found`

The proxy URL in `GRAPHWARDEN_PROXY_URL` is wrong, or the token endpoint path is wrong. The pipeline uses `/oauth2/v2.0/token` which is the proxy's standard token path; confirm your GraphWarden deployment exposes the same path (the default) and that the URL includes the scheme (`https://proxy.example.com`, not `proxy.example.com`). A trailing slash on `GRAPHWARDEN_PROXY_URL` produces a double-slash path that some proxies reject.

### `Token acquisition failed against GraphWarden` with an HTTP 401

The `GRAPHWARDEN_CLIENT_ID` and `GRAPHWARDEN_CLIENT_SECRET` pair is not the pair registered in the GraphWarden App Admin for this CI pipeline's App Identity. Rotate the credentials through GraphWarden Admin, update the variable group with the new values, and re-run the pipeline. Do not reuse App Identity credentials across environments.

### The pipeline succeeds locally but fails on the hosted agent

The hosted agent cannot reach your on-premise proxy. `ubuntu-latest` runs in Microsoft's Azure infrastructure; an on-premise proxy behind a corporate firewall is not reachable from there. Either expose the proxy on a publicly routable URL (behind its own authentication and TLS) or switch to a self-hosted agent running inside your network.

<x-doc.last-reviewed date="2026-04-19" />



## Run GraphWarden proxy deployments from GitHub Actions

# Run GraphWarden proxy deployments from GitHub Actions

A complete GitHub Actions workflow that builds, tests, and runs a GraphWarden smoke test. Repository secrets hold credentials and a banner comment prevents accidental commits. The workflow below runs as-is after you add the required repository secrets.

<x-doc.status-badge status="supported">GitHub Actions with repository secrets</x-doc.status-badge>

<x-doc.prerequisites>

- A GitHub repository containing your proxy deployment code or deployment scripts
- Three repository secrets: `GRAPHWARDEN_PROXY_URL`, `GRAPHWARDEN_CLIENT_ID`, and `GRAPHWARDEN_CLIENT_SECRET` (covered on the secrets-management page in this section)
- A GitHub-hosted runner (the `ubuntu-latest` image used below) or a self-hosted runner with network access to the proxy

</x-doc.prerequisites>

## The workflow, end to end

The workflow below is a complete GitHub Actions workflow. Copy it into `.github/workflows/graphwarden-proxy.yml` at the root of your repository. The `${{ secrets.* }}` references read from the repository secret store at run time.

```yaml
# DO NOT COMMIT REAL SECRETS TO THIS FILE.
# Add GRAPHWARDEN_PROXY_URL, GRAPHWARDEN_CLIENT_ID, GRAPHWARDEN_CLIENT_SECRET
# to Settings → Secrets and variables → Actions.

name: GraphWarden proxy CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Restore dependencies
        run: dotnet restore

      - name: Build
        run: dotnet build --configuration Release --no-restore

      - name: Test
        run: dotnet test --configuration Release --no-build --logger trx

  smoke-test:
    needs: build-and-test
    runs-on: ubuntu-latest
    steps:
      - name: GraphWarden token acquisition
        run: |
          # Verify the proxy responds before promoting the build.
          curl -sf -X POST \
            -d "grant_type=client_credentials" \
            -d "client_id=${{ secrets.GRAPHWARDEN_CLIENT_ID }}" \
            -d "client_secret=${{ secrets.GRAPHWARDEN_CLIENT_SECRET }}" \
            -d "scope=https://graph.microsoft.com/.default" \
            "${{ secrets.GRAPHWARDEN_PROXY_URL }}/oauth2/v2.0/token" \
            | jq -e '.access_token' > /dev/null
        env:
          GRAPHWARDEN_PROXY_URL: ${{ secrets.GRAPHWARDEN_PROXY_URL }}
          GRAPHWARDEN_CLIENT_ID: ${{ secrets.GRAPHWARDEN_CLIENT_ID }}
          GRAPHWARDEN_CLIENT_SECRET: ${{ secrets.GRAPHWARDEN_CLIENT_SECRET }}
```

<x-doc.callout type="warning">
The `# DO NOT COMMIT REAL SECRETS` banner at the top of the workflow is there on purpose. A commit that replaces one of the `${{ secrets.* }}` references with a real value leaks the credential to every fork of the repository and to every job log where the value appears. Keep the secret references unchanged.
</x-doc.callout>

## Repository secrets setup

The workflow reads three values from the repository secret store. Add them once per repository.

1. In GitHub, open your repository and navigate to **Settings** > **Secrets and variables** > **Actions**.
2. Click **New repository secret**.
3. Name the first secret `GRAPHWARDEN_PROXY_URL`. Paste the full proxy URL including the `https://` scheme. Click **Add secret**.
4. Repeat for `GRAPHWARDEN_CLIENT_ID` and `GRAPHWARDEN_CLIENT_SECRET`.
5. The workflow picks up the values on its next run. GitHub masks every secret value in job logs; a secret that leaks into stdout shows up as `***` in the log viewer.

For environment-specific secrets (staging versus production), use GitHub Environments. Each environment has its own secret scope and can require approval before a job runs. The workflow above uses repository-scoped secrets, which apply to every job in the repository.

## Protecting against secret leaks in logs

GitHub Actions auto-masks every `${{ secrets.* }}` reference in job logs — a secret value that appears in stdout renders as `***`. The masking is substring-based: if a secret value contains the literal string `abc123`, every occurrence of `abc123` in the log is masked, whether it came from the secret reference or from somewhere else.

The masking does not protect against all leak vectors.

- A `run:` step that prints a secret with `echo "$MY_SECRET"` is masked, but the same value encoded in Base64 or concatenated with other characters is not. `echo "$(echo $MY_SECRET | base64)"` leaks the Base64 form.
- A step that writes the secret to a file and uploads the file as an artifact leaks the raw value — artifacts are not masked.
- A secret used in an HTTP request to an external service reaches that service in plaintext. If the service logs the request body, the secret leaks to the service's log.

The smoke test above uses `curl -sf` (silent, fail-on-HTTP-error) and pipes to `jq -e '.access_token' > /dev/null`, so neither the request body nor the response body is printed. Keep that pattern when you add more secret-bearing steps.

## Troubleshooting

### The workflow reports `secret GRAPHWARDEN_CLIENT_SECRET not found`

The secret name does not match the reference in the workflow. Secret names are case-sensitive. Open **Settings** > **Secrets and variables** > **Actions** and confirm the three secrets are spelled exactly `GRAPHWARDEN_PROXY_URL`, `GRAPHWARDEN_CLIENT_ID`, `GRAPHWARDEN_CLIENT_SECRET`.

### The smoke test fails with `curl: (7) Failed to connect`

The runner cannot reach the proxy URL. `ubuntu-latest` runs in GitHub's cloud; an on-premise proxy behind a corporate firewall is not reachable. Either expose the proxy on a publicly routable URL (behind TLS and GraphWarden authentication) or run the workflow on a self-hosted runner that sits inside your network.

### `jq: error (at <stdin>:1): Cannot iterate over null` on the smoke test

The token response body did not contain an `access_token` field. The proxy returned either an error body or an empty body. Re-run the job with the `jq` filter removed (`| cat`) to see the real response body. The most common causes are wrong credentials (the secret pair does not match the GraphWarden App Identity) or a wrong proxy URL (the request hit a server that returned a generic 401 body).

### The workflow runs on `push` but not on pull requests from forks

GitHub does not pass secrets to workflows triggered by `pull_request` events from forks. This is a deliberate safeguard: a contributor could otherwise add a step that exfiltrates your secrets. If you need the smoke test on pull requests, use the `pull_request_target` trigger and gate the secret-bearing job on a label set by a maintainer. Read the GitHub documentation for `pull_request_target` carefully — the trigger has its own security model.

### The secret appears as the literal string `***` in the response body

The masking replaced the secret in a stdout dump, which means the secret leaked before the masking could be applied to the sink. Review the `run:` block for commands that print the environment (`env`, `printenv`) or the secret directly (`echo`). Remove the printing. The masking is a safety net, not a primary control.

<x-doc.last-reviewed date="2026-04-19" />



## Manage GraphWarden secrets across environments

# Manage GraphWarden secrets across environments

Store GraphWarden credentials in three places: Azure Key Vault for production proxies, your CI platform's secret store for pipelines, and a per-developer `.env` file for local work. Never commit real secrets to source. This page covers the rotation playbook and the detection of accidental commits.

<x-doc.status-badge status="supported">Three-tier secrets model</x-doc.status-badge>

<x-doc.prerequisites>

- An Azure Key Vault provisioned for your organization, with access granted to the identity that runs the proxy in production
- A CI platform with a secret store — Azure DevOps variable groups OR GitHub Actions repository secrets
- A `.env` convention for local development, with `.env` excluded from git via `.gitignore`

</x-doc.prerequisites>

## The three tiers

Each tier holds the credentials for one environment class. A credential never crosses tiers without an operator action.

### Tier 1: Azure Key Vault (production)

Production proxy instances read their credentials from Azure Key Vault. The proxy authenticates to Key Vault through Managed Identity — no vault credentials live on the host.

The two Key Vault settings the proxy reads come from the proxy environment variable inventory: `KeyVault:VaultUri` points at the vault (`https://my-vault.vault.azure.net/`), and `KeyVault:UseManagedIdentity` is `true` in production (the default). The Graph client secret and the GraphWarden rule-sync HMAC secret live in the vault as named secrets; the proxy resolves them at startup and on rotation.

Access to the vault is granted to the proxy's Managed Identity through an access policy or RBAC assignment — `Secret Get` is the minimum permission. Humans do not need to read the vault in daily operations; the proxy and the rotation script are the only callers.

### Tier 2: CI platform secret store (pipelines)

CI pipelines read their own copies of the GraphWarden App Identity credentials — a distinct Proxy Client ID and Proxy Client Secret pair issued specifically for the CI workload. The pipelines do not read from Key Vault; reading from Key Vault requires a Managed Identity that CI runners do not typically carry.

Two stores are supported:

- **Azure DevOps variable groups.** Create one variable group per environment (for example, `graphwarden-secrets-staging` and `graphwarden-secrets-production`). Mark each secret as secret (the lock icon) so Azure DevOps masks the value in logs.
- **GitHub Actions repository secrets.** Add each secret through **Settings** > **Secrets and variables** > **Actions**. Use GitHub Environments for per-environment scoping and for requiring approval before a secret-bearing job runs.

Rotate the CI credentials on the same cadence as the production credentials. If the CI workload and production share an App Identity, rotating one rotates both.

### Tier 3: Developer `.env` (local)

A developer working on the proxy or on a GraphWarden-compatible product needs credentials that point at a non-production GraphWarden instance. The pattern that scales: each developer has their own `.env` file, checked against a `.env.example` template that is committed to source, with real values filled in locally. The `.env` file is listed in `.gitignore` so it never reaches the repository.

The credentials in `.env` are for a dedicated development GraphWarden deployment (a shared dev instance or a per-developer local proxy). They are not the production credentials. If a developer needs to reproduce a production-only issue, the pattern is to obtain a time-limited scoped credential from GraphWarden Admin rather than to hand over the production vault entry.

## Rotation playbook

Rotate GraphWarden App Identity credentials on your organization's standard secret-rotation cadence — typically every 90 days, or immediately on any credential exposure. The steps are ordered so the rotation is zero-downtime.

1. **Rotate in Key Vault.** Open the production Azure Key Vault. Add a new version of the Graph client secret and the GraphWarden HMAC secret. Key Vault keeps the previous version available until you explicitly disable it; the proxy picks up the new version on its next rule-sync poll (default 60 seconds per the proxy environment variable inventory).
2. **Update the CI secret stores.** Open each Azure DevOps variable group and each GitHub Actions repository secret that holds the CI App Identity credentials. Paste the new values. The next pipeline run picks up the updated credentials.
3. **Notify developers to update `.env`.** If the developer tier uses credentials that were rotated, post in the team channel with the new values (through your organization's secure messaging channel — not in chat that archives to a searchable log). Developers replace the values in their local `.env` and restart their local dev tools.
4. **Verify the next pipeline run succeeds.** Trigger a pipeline on a safe branch and confirm the smoke test passes against the rotated credentials. A failure here indicates one of the three stores still holds the old value; trace the failing pipeline's secret store to find the outlier.
5. **Revoke the old secret in GraphWarden Admin.** Once every store is updated and verified, open GraphWarden Admin and revoke the previous App Identity credential version. This closes the window where a leaked old credential could still authenticate. Revoke only after verification — revoking before step 4 can take down a pipeline that still reads the old value.

A rotation that skips the verification step can cause a production outage. Always verify before revoking the old secret.

## Preventing accidental commits

The cheapest secret-leak incident is the one that never happens. Three layers protect the repository from accidental commits.

### `.gitignore`

Every repository that touches GraphWarden credentials excludes local secret files. At minimum:

```
.env
.env.local
.env.*.local
*.pem
*.pfx
**/secrets.json
**/appsettings.Development.json
```

The patterns above cover the common cases. `appsettings.Development.json` is excluded because the .NET proxy reads it during local development and developers paste credentials there; the committed template is `appsettings.json` without real secrets.

### Pre-commit hooks

Pre-commit hooks catch secrets before the commit lands locally. Two tools that work well with GraphWarden's credential shapes:

- **truffleHog** scans for high-entropy strings and known credential patterns. Install it once per developer machine; configure it through a `.pre-commit-config.yaml`.
- **gitleaks** runs the same kind of scan with a configurable ruleset. gitleaks ships with rules for Azure AD client secrets (the shape GraphWarden credentials follow) and for generic API tokens.

Neither tool catches everything — a sufficiently short secret or a secret embedded in a plausible-looking string can slip through. They are a cheap first line of defense, not the only line.

### GitHub push protection

GitHub's secret scanning service blocks pushes that contain recognized credential patterns before the push reaches the server. Enable it for every repository that could touch GraphWarden credentials: **Settings** > **Code security and analysis** > **Push protection**. For secrets GitHub does not recognize by default (GraphWarden does not yet ship a canonical detector), add custom patterns that match your issuer format — both the Proxy Client ID shape and the secret shape.

## Detecting leaked secrets post-commit

A secret that makes it into a git commit is not removable by deleting the file in a later commit — git history retains the value. If a secret leaks:

1. **Revoke the secret in GraphWarden Admin immediately.** The leak window ends when the credential stops working, not when the commit is rewritten. Revocation is the first action.
2. **Rotate the credential in Key Vault and the CI stores.** Follow the rotation playbook above. The old value is now unusable, so verification against pipelines confirms the new value propagated correctly.
3. **Rewrite history.** For public repositories, use `git filter-repo` (the actively maintained successor to `git filter-branch`) to strip the secret from every commit that contains it. Force-push the rewritten history. Collaborators need to re-clone. Note that GitHub retains the old commits in the fork network; any fork or unreachable commit may still contain the secret, which is why revocation must be the first action.
4. **Scan for other copies.** Run truffleHog or gitleaks across every repository your organization owns to confirm the same secret was not pasted elsewhere. A leaked credential often appears in multiple repositories because a developer copied it to "save time."
5. **Document the incident.** Record the commit SHA, the duration of exposure, the remediation steps, and the verification results. Your organization's security team will want this record.

## Troubleshooting

### `KeyVault:UseManagedIdentity is true but the proxy reports 403 on startup`

The Managed Identity does not have access to the vault. Open the Key Vault in Azure Portal, navigate to **Access policies** (or **Access control (IAM)** for RBAC-configured vaults), and confirm the proxy's Managed Identity has `Secret Get` permission. The identity name matches the host — for an Azure VM, it is the VM's Managed Identity; for an App Service, it is the App Service's Managed Identity.

### The pipeline runs but the proxy rejects every request with 401

The CI secret store holds the old credentials. A rotation updated Key Vault but skipped the pipeline variable group. Re-run the Update the CI secret stores step of the rotation playbook and re-trigger the pipeline.

### `.env` is not loading the expected values

The local proxy or dev tool is reading a different `.env` file, or the `.env` file is in a directory the tool does not scan. For the .NET proxy, `appsettings.Development.json` overrides environment variables on some hosting profiles; for Node and Python tooling, the `dotenv` library typically reads from the current working directory. Print the resolved values at startup to confirm what the tool actually loaded.

### A developer committed a `.env` file despite `.gitignore`

`git add -f .env` overrides `.gitignore`. The fix is to revoke the leaked secret, rewrite history, and follow the detection playbook above. Add a pre-commit hook that rejects the commit when `.env` is staged, to reduce the odds of recurrence.

### The rotation verification step fails but only on one pipeline

That pipeline reads from a secret store that did not receive the updated credentials. Azure DevOps pipelines inside the same project that reference the same variable group all receive updates at the same time; pipelines in different projects each need their own variable group updated. Trace the failing pipeline to the variable group it references and confirm the values are the post-rotation ones.

<x-doc.last-reviewed date="2026-04-19" />



## Provision GraphWarden infrastructure with Terraform

# Provision GraphWarden infrastructure with Terraform

A Terraform module that provisions the GraphWarden proxy as Azure Container Apps alongside its Key Vault, user-assigned managed identity, and required permissions. This page provides a runnable HCL module with variables for the proxy's configuration. The module is a starting point — adapt to your organization's naming conventions.

<x-doc.status-badge status="supported">Terraform 1.5+ with azurerm 3.80+</x-doc.status-badge>

<x-doc.prerequisites>

- Terraform 1.5 or later
- `azurerm` provider 3.80 or later
- Azure subscription with rights to create Container Apps, Key Vault, and role assignments
- The GraphWarden proxy image pushed to Azure Container Registry (see [Docker](../deployment/docker))
- A remote state backend (Azure Storage account is recommended — see "State management" below)

</x-doc.prerequisites>

<x-doc.callout type="note">
This module is a starting reference. Production usage should align with your organization's Terraform conventions: naming, tagging, module registry, state backend, and pipeline integration. Do not apply the module into a shared subscription without reviewing resource names and role assignments.
</x-doc.callout>

<x-doc.ai-prompt title="Generate a GraphWarden Terraform module with an AI assistant">
Generate a Terraform module for provisioning the GraphWarden proxy on Azure Container Apps.

I need the module to create:
1. An Azure Key Vault with access policies for the proxy's managed identity.
2. A user-assigned managed identity with Secret — Get on the vault.
3. An Azure Container Apps environment and container app pulling the proxy image from ACR.
4. All env vars wired from Terraform variables (tenant id, client id, vault uri).
5. Outputs for the proxy FQDN and the identity's principal id.

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my ACR name, my subscription and tenant ids, whether Key Vault already exists, and the Graph tenant and client id the proxy should authenticate as.
</x-doc.ai-prompt>

## Module structure

Keep the module under an `infra/modules/graphwarden/` directory in your repository:

```text
infra/
  modules/
    graphwarden/
      main.tf         # Resources
      variables.tf    # Input variables
      outputs.tf      # Output values
      versions.tf     # Required providers
      README.md       # Usage notes (module-local, not published docs)
  environments/
    production/
      main.tf         # Calls the module with production values
      backend.tf      # Remote state
```

The `environments/production/main.tf` file is the root module for one environment; it calls `modules/graphwarden` with production-specific variables. Duplicate `environments/production` for staging, dev, or per-tenant deployments.

## versions.tf

```hcl
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.80.0"
    }
  }
}
```

## variables.tf

All of the module's inputs are declared here. Required variables have no default; optional variables have conservative defaults.

```hcl
variable "resource_group_name" {
  type        = string
  description = "Resource group to deploy into. Must already exist."
}

variable "location" {
  type        = string
  description = "Azure region (for example 'eastus2' or 'westeurope')."
}

variable "name_prefix" {
  type        = string
  description = "Prefix for resource names (for example 'gw-prod'). Lowercase alphanumeric only."
}

variable "proxy_image_uri" {
  type        = string
  description = "Full image URI, for example 'myacr.azurecr.io/graphwarden-proxy:0.1.0'."
}

variable "acr_resource_id" {
  type        = string
  description = "Resource id of the Azure Container Registry holding the proxy image."
}

variable "log_analytics_workspace_id" {
  type        = string
  description = "Resource id of an existing Log Analytics workspace for the ACA environment."
}

variable "graph_tenant_id" {
  type        = string
  description = "Azure AD tenant id the proxy authenticates against for Microsoft Graph."
}

variable "graph_client_id" {
  type        = string
  description = "Azure AD app client id used by the proxy for Graph calls."
}

variable "graph_client_secret_name" {
  type        = string
  description = "Key Vault secret name holding the Graph client secret (for example 'graph-client-secret')."
  default     = "graph-client-secret"
}

variable "jwt_signing_key_secret_name" {
  type        = string
  description = "Key Vault secret name holding the ProxyJwt:SigningKey (32+ characters)."
  default     = "proxy-jwt-signing-key"
}

variable "cpu" {
  type        = number
  description = "vCPU allocation per replica. See the sizing guide."
  default     = 1.0
}

variable "memory" {
  type        = string
  description = "Memory allocation per replica (e.g. '2.0Gi'). See the sizing guide."
  default     = "2.0Gi"
}

variable "min_replicas" {
  type        = number
  description = "Minimum replica count. Use 0 for non-production scale-to-zero."
  default     = 1
}

variable "max_replicas" {
  type        = number
  description = "Maximum replica count."
  default     = 10
}

variable "tags" {
  type        = map(string)
  description = "Tags applied to every resource in the module."
  default     = {}
}
```

## main.tf — Key Vault and managed identity

The vault stores the Graph client secret and the JWT signing key. The user-assigned identity has `Secret — Get` on the vault and `AcrPull` on the container registry.

```hcl
data "azurerm_client_config" "current" {}

resource "azurerm_user_assigned_identity" "proxy" {
  name                = "${var.name_prefix}-proxy-identity"
  resource_group_name = var.resource_group_name
  location            = var.location
  tags                = var.tags
}

resource "azurerm_key_vault" "proxy" {
  name                      = "${var.name_prefix}-kv"
  resource_group_name       = var.resource_group_name
  location                  = var.location
  tenant_id                 = data.azurerm_client_config.current.tenant_id
  sku_name                  = "standard"
  enable_rbac_authorization = false
  purge_protection_enabled  = true
  tags                      = var.tags
}

resource "azurerm_key_vault_access_policy" "proxy_read" {
  key_vault_id = azurerm_key_vault.proxy.id
  tenant_id    = data.azurerm_client_config.current.tenant_id
  object_id    = azurerm_user_assigned_identity.proxy.principal_id

  secret_permissions = ["Get"]
}

resource "azurerm_role_assignment" "acr_pull" {
  scope                = var.acr_resource_id
  role_definition_name = "AcrPull"
  principal_id         = azurerm_user_assigned_identity.proxy.principal_id
}
```

The `azurerm_key_vault_access_policy` uses vault access policies rather than RBAC for broad compatibility. Switch to RBAC (`enable_rbac_authorization = true` and `azurerm_role_assignment` with `Key Vault Secrets User`) if your organization's vaults are RBAC-only.

## main.tf — Container Apps environment and container app

```hcl
resource "azurerm_container_app_environment" "proxy" {
  name                       = "${var.name_prefix}-env"
  resource_group_name        = var.resource_group_name
  location                   = var.location
  log_analytics_workspace_id = var.log_analytics_workspace_id
  tags                       = var.tags
}

resource "azurerm_container_app" "proxy" {
  name                         = "${var.name_prefix}-proxy"
  resource_group_name          = var.resource_group_name
  container_app_environment_id = azurerm_container_app_environment.proxy.id
  revision_mode                = "Single"
  tags                         = var.tags

  identity {
    type         = "UserAssigned"
    identity_ids = [azurerm_user_assigned_identity.proxy.id]
  }

  registry {
    server   = split("/", var.proxy_image_uri)[0]
    identity = azurerm_user_assigned_identity.proxy.id
  }

  ingress {
    external_enabled = true
    target_port      = 5000
    transport        = "auto"

    traffic_weight {
      percentage      = 100
      latest_revision = true
    }
  }

  template {
    min_replicas = var.min_replicas
    max_replicas = var.max_replicas

    container {
      name   = "proxy"
      image  = var.proxy_image_uri
      cpu    = var.cpu
      memory = var.memory

      env {
        name  = "GraphClient__TenantId"
        value = var.graph_tenant_id
      }
      env {
        name  = "GraphClient__ClientId"
        value = var.graph_client_id
      }
      env {
        name  = "KeyVault__VaultUri"
        value = azurerm_key_vault.proxy.vault_uri
      }
      env {
        name  = "KeyVault__UseManagedIdentity"
        value = "true"
      }
      env {
        name  = "AZURE_CLIENT_ID"
        value = azurerm_user_assigned_identity.proxy.client_id
      }
      env {
        name  = "Audit__Enabled"
        value = "true"
      }
      env {
        name  = "Audit__DeploymentType"
        value = "hosted"
      }

      liveness_probe {
        transport = "HTTP"
        port      = 5000
        path      = "/health"
        interval_seconds  = 30
        timeout           = 5
        failure_count_threshold = 3
      }
    }

    http_scale_rule {
      name              = "http-concurrency"
      concurrent_requests = 50
    }
  }

  depends_on = [
    azurerm_key_vault_access_policy.proxy_read,
    azurerm_role_assignment.acr_pull,
  ]
}
```

The `depends_on` block is load-bearing: if the container app is created before the identity has `AcrPull` on the registry, the image pull fails and the revision enters a retry loop. Explicit ordering avoids the race.

## outputs.tf

```hcl
output "proxy_fqdn" {
  description = "External FQDN of the GraphWarden proxy. Clients rewrite Microsoft Graph base URL to this host."
  value       = azurerm_container_app.proxy.ingress[0].fqdn
}

output "proxy_identity_principal_id" {
  description = "Object id of the user-assigned managed identity. Grant Graph API permissions to this id."
  value       = azurerm_user_assigned_identity.proxy.principal_id
}

output "proxy_identity_client_id" {
  description = "Client id of the user-assigned managed identity. Matches the AZURE_CLIENT_ID env var in the container."
  value       = azurerm_user_assigned_identity.proxy.client_id
}

output "key_vault_id" {
  description = "Resource id of the Key Vault. Use to seed secrets with azurerm_key_vault_secret."
  value       = azurerm_key_vault.proxy.id
}
```

The module does not write secrets into the vault — you provision the vault and its identity permissions, then add the Graph client secret and JWT signing key in a separate pipeline step (or via a separate `azurerm_key_vault_secret` resource outside the module). Mixing secret material into a shared module is a common source of state-file leakage.

## Usage example

From an environment root module:

```hcl
module "graphwarden_proxy" {
  source = "../../modules/graphwarden"

  resource_group_name        = "rg-graphwarden-prod"
  location                   = "eastus2"
  name_prefix                = "gw-prod"
  proxy_image_uri            = "gwprodacr.azurecr.io/graphwarden-proxy:0.1.0"
  acr_resource_id            = data.azurerm_container_registry.main.id
  log_analytics_workspace_id = data.azurerm_log_analytics_workspace.main.id

  graph_tenant_id = "00000000-0000-0000-0000-000000000000"
  graph_client_id = "11111111-1111-1111-1111-111111111111"

  cpu          = 1.0
  memory       = "2.0Gi"
  min_replicas = 2
  max_replicas = 10

  tags = {
    environment = "production"
    owner       = "platform-team"
  }
}

output "proxy_fqdn" {
  value = module.graphwarden_proxy.proxy_fqdn
}
```

After `terraform init && terraform plan` reports no errors, run `terraform apply`. The first apply creates the identity, vault, environment, and container app in that order; subsequent applies produce no changes unless inputs change.

## State management

Store Terraform state in Azure Storage with a lock-capable backend. Do not commit state to git — the state file contains resource identifiers and sometimes sensitive values.

```hcl
# backend.tf — in the environment root module, not the reusable module.
terraform {
  backend "azurerm" {
    resource_group_name  = "rg-tfstate"
    storage_account_name = "tfstateorg"
    container_name       = "graphwarden"
    key                  = "production.tfstate"
    use_azuread_auth     = true
  }
}
```

The `use_azuread_auth = true` option authenticates state reads and writes with the user's (or pipeline's) Azure AD identity rather than a shared storage account key. Grant `Storage Blob Data Contributor` on the state container to every identity that runs Terraform against the environment.

## Troubleshooting

### `Error: failed to create container app` with `ACR pull failed`

The `azurerm_role_assignment.acr_pull` was created but role propagation has not completed (Azure IAM propagation can take 60-120 seconds). Wait a minute and rerun `terraform apply`. If the error persists, verify the identity's principal id is correctly bound to `AcrPull` in the Azure portal and that the registry's resource id is correct.

### `Error: authorization failed` on `azurerm_key_vault_access_policy`

The identity running Terraform does not have rights to mutate Key Vault access policies. Grant `Key Vault Administrator` on the vault's resource group to the Terraform service principal, or switch to RBAC authorization (see the RBAC note in "main.tf — Key Vault" above) and pre-grant the Terraform identity `Key Vault Secrets Officer`.

### State file contains the Graph tenant id in plaintext

This is expected. Terraform state captures every resource attribute including variable values. Protect the state file at the storage layer (Azure Storage blob-level encryption + network ACLs + Azure AD auth as above). If you need to redact specific values, mark them `sensitive = true` in the variable declaration — Terraform output hides them from CLI logs but they remain in state.

### Plan shows changes to `traffic_weight` on every apply

The `azurerm_container_app` resource sometimes reports spurious diffs on `traffic_weight` because Azure normalizes the percentage to match the revision count. Setting `latest_revision = true` and leaving `revision_mode = "Single"` minimizes the drift. If diffs persist, add a `lifecycle { ignore_changes = [ingress[0].traffic_weight] }` block after confirming you are not using blue-green deployments.

### Module apply hangs on `azurerm_container_app` creation

Container app creation polls until the first revision is healthy. If the first revision fails liveness (for example Key Vault access is not yet propagated), the apply waits up to 30 minutes before failing. Run `az containerapp logs show` against the provisioned app in a separate shell to see real-time logs; common causes are missing AZURE_CLIENT_ID, wrong vault URI, or a typo in the image tag.

<x-doc.last-reviewed date="2026-04-19" />



## App identities: proxy credentials vs. real Graph credentials

# App identities: proxy credentials vs. real Graph credentials

An **App Identity** is GraphWarden's record of a client application that talks to Microsoft Graph through the proxy. It carries two credential pairs: the proxy pair your app uses to authenticate to GraphWarden, and the real Graph Client ID plus tenant secret that GraphWarden itself uses when calling Graph on your behalf. Your app only ever sees the proxy pair.

<x-doc.status-badge status="supported">Shipped — Credential rotation is a supported flow</x-doc.status-badge>

<x-doc.prerequisites>

- An Azure AD application registration in your tenant (this supplies the Graph App and its real `client_id`)
- Access to the customer Azure Key Vault so GraphWarden can read the Graph Client Secret
- The GraphWarden App Admin UI (you will create the App Identity there)

</x-doc.prerequisites>

## The two credential pairs

GraphWarden's zero-knowledge stance turns on this separation. Confusion about which credential does what is the single most common onboarding mistake.

| Credential | Issued by | Held by | Used to |
|------------|-----------|---------|---------|
| **Proxy Client ID** | GraphWarden App Admin | Your client application | Identify the caller on `POST /proxy/token` |
| **Proxy Client Secret** | GraphWarden App Admin | Your client application (hashed on the proxy) | Authenticate the caller on `POST /proxy/token` |
| **Graph Client ID** | Your Azure AD tenant | GraphWarden (in App Admin database) | Impersonate the real Graph App against Microsoft Graph |
| **Graph Client Secret** | Your Azure AD tenant | Your Azure Key Vault (GraphWarden reads at runtime) | Obtain a Graph token via MSAL client-credentials flow |

Your app embeds only the proxy pair. If your source code or CI environment contains the Graph Client Secret, you have bypassed GraphWarden entirely and the zero-knowledge property does not hold.

## Where credentials live

Each credential has one authoritative home. Copies elsewhere are drift.

- **Proxy Client ID** — issued and stored in the GraphWarden App Admin database (`app_identities.proxy_client_id`). Distributed to your client app by whoever provisions the App Identity. Non-secret.
- **Proxy Client Secret** — generated by App Admin at creation time, shown once, then stored only as a SHA-256 hash on each proxy instance (`proxy_client_secret_hash`). Regenerate by rotating (see below); the old secret is discarded the moment a new one is issued.
- **Graph Client ID** — copied from your Azure AD app registration into App Admin (`app_identities.real_client_id`). Non-secret; Azure AD treats this as a public identifier.
- **Graph Client Secret** — NEVER stored in App Admin or the proxy. Written directly to `microsoft_tenants.key_vault_url` by an operator using the GraphWarden Key Vault helper. The proxy reads it at runtime using Managed Identity (production) or an explicit service principal (development). A secret name of `tenant-{tenant_uuid}-identity-{real_client_id}` is the convention.

## Creating an App Identity

The canonical path is through the GraphWarden App Admin UI. The flow below is the conceptual sequence; the App Admin guide covers the click-by-click steps.

1. **Register the Graph App in Azure AD** — create the Azure AD application, grant it the application permissions you want GraphWarden to broker, and obtain the real `client_id` plus a fresh client secret.
2. **Write the Graph secret to Key Vault** — use the Key Vault helper to store the secret at the convention-named secret. GraphWarden never sees the cleartext.
3. **Create the App Identity in App Admin** — supply the `real_client_id`, pick the ruleset to bind, and submit. App Admin generates the `proxy_client_id` and a fresh `proxy_client_secret`, shows the secret ONCE, and records only the hash.
4. **Distribute the proxy pair to your application** — store the proxy credentials in your app's secret manager (environment variables, CI secrets, Azure Key Vault for your app, etc.). Ship the values via your existing secret-distribution channel; GraphWarden does not re-surface them.

## Rotating credentials

Both credential pairs rotate independently.

**Proxy pair** — in App Admin, open the App Identity and click Rotate Secret. A new secret is generated, the new hash replaces the old one on the next sync cycle (typically seconds), and the old cleartext is destroyed. Update your application's configuration to the new secret before the sync runs to avoid a token-request gap, or accept a brief `401` window.

**Graph pair** — rotate the Graph Client Secret in Azure AD first, then write the new secret to the same Key Vault entry. GraphWarden picks it up on the next MSAL token request (expired tokens are re-acquired transparently). The `real_client_id` rarely changes; if it does, update App Admin and re-provision the Key Vault entry under the new convention name.

<x-doc.callout type="info">
Rotation is a supported operation for both credential pairs. Automating rotation via a scheduled Azure DevOps or GitHub Actions job is a common pattern; the Key Vault helper exposes a CLI that fits into those pipelines.
</x-doc.callout>

## Troubleshooting

**`401` on `/proxy/token` immediately after a rotation** — the proxy instance has not yet resynced the new hash. Wait one sync cycle (`RuleSync:IntervalSeconds`, default 60 seconds) or hit the admin API to force a sync.

**Graph returns `401 AADSTS7000215` through the proxy** — the Graph Client Secret in Key Vault is expired or wrong. Confirm the entry exists at `tenant-{tenant_uuid}-identity-{real_client_id}` and that the value matches the secret shown in Azure AD.

**Proxy logs `KeyNotFound` for a Key Vault secret** — the proxy's Managed Identity lacks `get` permission on that specific secret. Grant `get` (NOT list or set) on the secret in Key Vault access policies or RBAC.

**Two App Identities for the same Graph App** — supported, and often useful when one app uses distinct rulesets for distinct workflows (e.g., a read-only reporting job and an admin-write job). Each App Identity carries its own proxy pair; the Graph App can be shared.

<x-doc.last-reviewed date="2026-04-19" />



## How requests flow through GraphWarden

# How requests flow through GraphWarden

GraphWarden is a reverse proxy that stands between a client application and Microsoft Graph. The client authenticates to the proxy, the proxy evaluates the ruleset bound to that client's App Identity, and allowed calls are forwarded to Graph with the real tenant credentials the proxy reads from your Key Vault.

<x-doc.status-badge status="supported">Shipped in Phase 1</x-doc.status-badge>

<x-doc.prerequisites>

- A Microsoft 365 tenant with an Azure AD application registration you can use against Microsoft Graph
- A deployed GraphWarden Proxy instance reachable from your client app (see deployment modes page)
- An App Identity issued by GraphWarden App Admin (`proxy_client_id` + `proxy_client_secret`)

</x-doc.prerequisites>

## The request lifecycle

A request traverses five numbered stages. Each stage is a decision point and a failure point; the troubleshooting section below maps each to its observable error.

1. **Client token request** — your app posts `client_id` + `client_secret` (the proxy pair issued by GraphWarden) to `POST /proxy/token` using the OAuth2 `client_credentials` grant. No Graph call happens at this stage.
2. **Proxy authenticates the client** — the proxy looks up the proxy `client_id` in its identity store, compares a SHA-256 hash of the supplied secret against the stored hash, and — if valid — reads the paired Graph client secret from your Azure Key Vault.
3. **Ruleset evaluation** — when your app subsequently calls a Graph endpoint (e.g. `GET /v1.0/users`), the proxy decodes its own JWT `Bearer` token, resolves the App Identity, loads the associated ruleset, and walks the rules top-down. The first rule whose `match` and `conditions` pass decides the verdict: `allow`, `filter`, `block`, or `log_only`.
4. **Forward to Graph** — for `allow`, `filter`, and `log_only`, the proxy issues the upstream request to `https://graph.microsoft.com` using the real tenant token it obtained from MSAL. The request path and query string are preserved byte-for-byte by the YARP catch-all route.
5. **Response transformation** — on the way back, `filter` rules apply `allow_properties` or `strip_properties` to the response body. `block` never reaches Graph and returns `403 Forbidden` directly. Every outcome (allowed, filtered, blocked) produces an audit event.

```text
┌──────────┐    ┌──────────────┐    ┌──────────────────┐
│ Your app │───▶│  GraphWarden │───▶│ Microsoft Graph  │
└──────────┘    │    Proxy     │    │   graph.ms.com   │
                └──────┬───────┘    └──────────────────┘
                       │
                       ▼
                ┌──────────────┐
                │  Audit log   │
                │ (Elastic)    │
                └──────────────┘
```

## Components

The runtime is a single self-hosted ASP.NET Core service. The pieces below are load-bearing and worth naming explicitly; everything else is auxiliary.

- **Kestrel** — the proxy runs as a Kestrel-hosted ASP.NET Core service. It is NOT hosted behind IIS. On Windows Server the binary registers as a Windows Service via `sc.exe create`; in hosted mode it runs as a container process.
- **YARP reverse proxy** — a catch-all route (`Match: { Path: "/{**catch-all}" }`) forwards every authenticated request to `https://graph.microsoft.com` with path and query preserved. No per-endpoint routing table is maintained.
- **MSAL client** — the proxy uses Microsoft Authentication Library to acquire Graph tokens via the client-credentials flow, keyed on the real Azure AD `client_id` resolved from the App Identity. Tokens are cached to their natural expiry.
- **YamlDotNet rule loader** — rulesets are YAML files read at startup and on each sync cycle. `RuleLoader.cs` parses the schema, validates conditions and transforms, and materializes an evaluation tree in memory.
- **Serilog** — structured JSON logs are emitted to stdout (container) or the Windows Event Log (service). An audit sink ships one event per Graph request to Elasticsearch when `Audit:ElasticsearchUrl` is configured.

## What the proxy does NOT do

GraphWarden's scope is narrow on purpose. Confusion about the proxy usually traces back to assuming it does one of the things below.

- **It does not sign users in.** GraphWarden speaks app-to-service OAuth2 only. User authentication (interactive sign-in, delegated scopes, MFA prompts) remains in Azure AD. If your app uses delegated flows today, you still acquire the user token from Azure AD; the proxy only intermediates app tokens.
- **It does not cache Graph response bodies by default.** Per-rule `cache_ttl` caches the rule verdict for a given caller and object, not the raw payload. Response bodies are forwarded fresh on every request unless a rule explicitly opts in.
- **It does not store user data.** Audit events are metadata: timestamp, caller App Identity, HTTP method, URI, status code, latency, matched rule. Request and response bodies are NOT written to the audit store unless a response-filter transform inspects them in-flight to redact fields.
- **It does not replace Azure RBAC or Conditional Access.** GraphWarden gates Graph API calls from your apps; it does not evaluate user role assignments, device compliance, or sign-in risk. Those continue to live in Azure AD and Microsoft Entra.

## Troubleshooting

**`401 Unauthorized` from `/proxy/token`** — the `client_id` or `client_secret` your app sent does not match any App Identity. Confirm the pair was issued by GraphWarden App Admin for this environment (proxy credentials differ per deployed proxy instance). Check the proxy log for `Unknown proxy client_id` or `Secret hash mismatch`.

**`403 Forbidden` on a Graph request with a valid `Bearer` token** — a ruleset evaluated the request and returned `block`, OR no rule matched and the default policy in your tenant is deny. Inspect the audit event for the correlation ID in the response header and find the `MatchedRuleId` field to see which rule fired.

**`502 Bad Gateway` returned from a Graph endpoint that normally works** — the proxy reached the upstream but Graph returned an error the proxy could not classify, OR MSAL failed to acquire a tenant token. Check Kestrel stdout for `Upstream Graph call failed` and confirm the Graph secret in Key Vault has not expired.

**Requests hang for minutes, then time out** — the proxy is failing to reach Key Vault. Managed Identity may be misconfigured, or the outbound egress rule from the proxy host blocks `*.vault.azure.net`. Confirm `az login --identity` works from the host if applicable.

## See it in production

Scenarios that anchor this architecture to concrete customer patterns — multi-tenant SaaS, internal HR integrations, SIEM-fed audit — are collected on the [use cases](/en/use-cases) page. For a walkthrough against your own Graph-integrated estate, [contact the GraphWarden team](/en/contact).

<x-doc.last-reviewed date="2026-04-19" />



## Deployment modes: hosted, on-premise, and hybrid

# 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.

<x-doc.status-badge status="supported">Shipped — Hybrid mode is supported for Phase-1 deployments</x-doc.status-badge>

<x-doc.prerequisites>

- A Microsoft 365 tenant you control
- An Azure Key Vault in that tenant for the Graph Client Secret
- For on-premise or hybrid: a Windows Server 2016+ host with .NET 8 runtime, OR a Linux/Windows container host running Docker

</x-doc.prerequisites>

## 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:

```powershell
# 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.).

```bash
# 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.

| Factor | Hosted | On-premise (Windows Service or container) | Hybrid |
|--------|--------|--------------------------------------------|--------|
| Time to deploy | Hours | Days (firewall + ops setup) | Days (same proxy as on-prem) |
| Data residency | Key Vault in your tenant; proxy in our cloud | Proxy and Key Vault both in your network | Key Vault in your tenant; proxy in your network; control plane in our cloud |
| Ops burden (patching, scaling) | We carry it | You carry it | You carry the proxy; we carry App Admin |
| Compliance posture (e.g., FedRAMP, sector-specific) | Check our hosted certifications | Your posture applies end-to-end | Yours on the data plane; ours on the control plane |
| Egress from your network | None needed for Graph calls | Required to Graph and Key Vault | Required to Graph, Key Vault, and our Agent API |
| Typical fit | Startups, mid-market, fast pilots | Regulated industries, air-gapped tenants | Most enterprise customers |

## 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.

<x-doc.last-reviewed date="2026-04-19" />



## Rulesets and rules: the GraphWarden data model

# Rulesets and rules: the GraphWarden data model

A **Ruleset** is a container. A **Rule** is a single policy that matches an endpoint, evaluates conditions, and applies an action. Every Graph request arriving at the proxy is evaluated against the ruleset bound to the caller's App Identity. Rules are walked top to bottom; the first rule whose `match` and `conditions` succeed decides the verdict.

<x-doc.status-badge status="supported">Shipped schema — reference table planned for Phase 6</x-doc.status-badge>

<x-doc.prerequisites>

- Familiarity with Microsoft Graph endpoints (`/v1.0/users`, `/v1.0/groups`, etc.)
- Basic YAML comfort
- An App Identity in GraphWarden App Admin so you have somewhere to attach a ruleset

</x-doc.prerequisites>

## Ruleset structure

A ruleset is a YAML document with one top-level `rules` array. Each entry defines a single rule. Rulesets live in GraphWarden App Admin (MySQL-backed) and are synced to each proxy instance on a timer (`RuleSync:IntervalSeconds`).

```yaml
# A minimal ruleset with two rules.
rules:
  - id: hr-app-allow-user-basics           # Stable identifier used in audit logs
    match:
      app_id: "f63c4abc-..."              # Target one App Identity, or "*" for any
      methods: ["GET"]                    # HTTP methods this rule covers
      endpoint_pattern: "/users*"         # Graph path prefix to match
    action: filter                         # Apply response_filter below
    response_filter:
      allow_properties:
        - id
        - displayName
        - mail

  - id: block-privileged-endpoints
    match:
      app_id: "*"
      methods: ["DELETE", "PATCH"]
      endpoint_pattern: "/identityRiskDetections*"
    action: block                          # Return 403 without calling Graph
```

## A rule's anatomy

A rule has three logical sections. Read them in this order when designing or reviewing a rule.

- **`match`** — a gate on the request envelope. `app_id` narrows to one App Identity (or `*`), `methods` is a list of HTTP verbs, and `endpoint_pattern` is a glob against the Graph path. All three fields of `match` are required; a rule with no `endpoint_pattern` will be rejected by the loader.
- **`conditions`** — zero or more predicates evaluated AFTER `match` passes. Conditions are AND-combined by default. For OR or NOT semantics a single condition exposes a `logic_group: any_of | none_of` plus a `variants` list. Conditions are what make GraphWarden more than a firewall: a rule can depend on the caller's group membership, a target object's attributes, the time of day, a rate budget, or the calling IP.
- **`action`** — the verdict. One of `allow`, `filter`, `block`, `log_only`. `filter` requires a sibling `response_filter` with `allow_properties` (whitelist) or `strip_properties` (blacklist). `block` short-circuits before Graph is called and returns HTTP 403.

## Condition types

Eleven condition types are shipped. Each has its own required fields; see the API reference (planned for Phase 6) for the full field schema per type.

| Type | Domain | What it matches |
|------|--------|-----------------|
| `group_membership` | Object | Target user or group is a member of a specified Azure AD security group |
| `object_attribute` | Object | A field on the response object equals, contains, or matches a regex against a value |
| `domain` | Object | Target user's UPN or mail domain is in a whitelist |
| `custom_attribute` | Object | A Directory Extension attribute on the target object matches a value |
| `administrative_unit` | Object | Target user or group belongs to a specified Administrative Unit |
| `assigned_license` | Object | Target user has a specified license SKU assigned |
| `caller_identity` | Request | Calling App Identity equals a specified UUID |
| `time_window` | Request | Request arrives within a configured `HH:MM` window for a given UTC offset |
| `rate_limit` | Request | Caller is within `max_requests` per `window_seconds` budget |
| `object_count_limit` | Response | Result set size is at or below `max_count` |
| `ip_range` | Request | Source IP is within one of the supplied CIDR ranges |

The `Domain` column tells you WHEN the proxy can evaluate the condition. Object-domain conditions need the Graph response in hand before they resolve, so they are evaluated on the outbound path. Request-domain conditions evaluate before the upstream call. One request-domain condition failing can therefore save a Graph call entirely.

## Transform types

Nine transforms are shipped. Transforms operate on individual properties referenced by a `response_filter`. The transform rewrites the value in-place on the response body before it is returned to the caller.

| Transform | Input shape | Output shape | Typical use |
|-----------|-------------|--------------|-------------|
| `mask_start` | string | First N chars hidden | Conceal given name on a full-name field |
| `mask_end` | string | Last N chars hidden | Redact a local-part while preserving domain |
| `redact` | any | `[redacted]` sentinel | Remove a field entirely from view |
| `hash` | string | SHA-256 hex digest | Emit a stable pseudonym for analytics |
| `truncate` | string | String capped to N chars | Cap long notes or descriptions |
| `regex_replace` | string | Template output | Redact SSN-shaped substrings |
| `domain_only` | email string | Domain part only | Keep `example.com`, drop `alice@` |
| `initials` | string | Initials only | `"John Doe"` becomes `"JD"` |
| `noise` | string | String plus random suffix | Break output-identity assumptions |

## Evaluation order

Rules in a ruleset are walked top-down. The first rule whose `match` and `conditions` both succeed decides the verdict — **first match wins**. Later rules are not consulted. If no rule matches, the proxy falls through to a default `allow` (requests pass to Graph unchanged).

<x-doc.callout type="info">
First-match-wins is the shipped semantic. There is no accumulating mode; each rule's action is final. To compose policies — for example, filter AND log — place a `log_only` rule BEFORE a `filter` rule with the same `match`: the walker stops at the first match, so log-then-filter is not a supported pattern. Use a single rule whose `action: filter` + audit event captures both concerns at once.
</x-doc.callout>

A `cache_ttl` on a rule caches the VERDICT (match decision and filter result) for a given caller + target object for the specified seconds. It does not cache the raw Graph response body.

## Troubleshooting

**My rule does not match and I expected it to** — walk the ruleset in order and find the first rule whose `match` envelope (`app_id`, `methods`, `endpoint_pattern`) succeeds on the request. If an earlier rule is matching with a broader `app_id: "*"`, its verdict wins and the later rule never runs. Narrow the earlier rule or reorder.

**A `filter` rule returns `403` instead of a redacted body** — the rule is declared `action: block` (or is missing `action: filter` entirely and the default is hitting somewhere else). The YAML loader logs `RuleLoader: rule {id} has no action` at startup — check Kestrel stdout.

**A condition appears valid but never passes** — confirm the condition type is spelled exactly as the table above lists it. Typos (`group_memberships`, `object_attributes`) are silently ignored by some older proxy builds. Run `php artisan doctor:rules` in App Admin to surface loader warnings.

**Transforms do not appear to run** — transforms only apply when `action: filter` AND the property appears in `response_filter.allow_properties` or `strip_properties`. A transform declared outside that block is syntactically valid YAML but has no effect.

## From model to rollout

The ruleset patterns above are illustrated against concrete scenarios on the [use cases](/en/use-cases) page — HR self-service, SIEM backfill, vendor isolation. To pressure-test the model against your own Graph estate, [contact the GraphWarden team](/en/contact).

<x-doc.last-reviewed date="2026-04-19" />



## Trust model: zero-knowledge credentials and what GraphWarden does not see

# Trust model: zero-knowledge credentials and what GraphWarden does not see

GraphWarden never holds your Graph API credentials at rest. Those credentials live in YOUR Azure Key Vault, in YOUR tenant. The proxy reads them at runtime through a Managed Identity, obtains a Graph token via MSAL, and forwards the token upstream. Audit logs capture metadata — timestamps, paths, statuses, rule verdicts — not request or response bodies.

<x-doc.status-badge status="supported">Implementation shipped — deep compliance audit scheduled for Phase 5</x-doc.status-badge>

<x-doc.prerequisites>

- An Azure Key Vault in your tenant with the Graph Client Secret written to a known entry
- A Managed Identity (or service principal, for dev) that the proxy runs as
- `get` permission for the proxy's identity on the specific Key Vault secret

</x-doc.prerequisites>

## Where your credentials live

Credential location is the whole foundation of the zero-knowledge claim. If any piece of it is wrong, the property does not hold.

- **Graph Client Secret** — stored in your Azure Key Vault (`microsoft_tenants.key_vault_url`) at a conventioned secret name. GraphWarden reads the value on demand using the proxy's Managed Identity. The value is kept in memory only for the lifetime of the Graph token MSAL issues from it.
- **Proxy Client Secret** — stored as a SHA-256 hash on each proxy instance (`proxy_client_secret_hash`). The cleartext is shown to the App Admin operator ONCE at creation time and then discarded.
- **HMAC secret for the agent API** — unique per proxy instance, generated at enrollment, stored encrypted in App Admin. Used to sign proxy-to-AppAdmin heartbeats and sync calls. Not a Graph credential; it never leaves the pair.

GraphWarden itself holds no copy of your Graph Client Secret at rest. An engineer with full access to the GraphWarden App Admin database cannot recover your Graph Client Secret from it.

## What GraphWarden sees vs. does not see

The table below lists every field GraphWarden observes about a Graph request. Everything not listed is NOT recorded.

| Data class | Seen by the proxy in-flight | Written to audit store |
|------------|------------------------------|------------------------|
| Request HTTP method | Yes | Yes |
| Request path and query string | Yes | Yes |
| Caller App Identity (by proxy `client_id`) | Yes | Yes |
| Response HTTP status | Yes | Yes |
| Latency in milliseconds | Yes | Yes |
| Matched rule ID and action | Yes | Yes |
| Correlation ID | Yes | Yes |
| Request body | Yes (forwarded) | No |
| Response body | Yes (forwarded) | No (default) |
| Individual field values in a Graph response | Only when a `response_filter` inspects them to redact | No |
| Azure AD user passwords, tokens, refresh tokens | Never | Never |
| Graph Client Secret cleartext | Only in memory during MSAL exchange; never persisted | Never |

<x-doc.callout type="note">
The implementation details above (Key Vault access via Managed Identity, secret name convention, in-memory lifetime of the Graph Client Secret) have been verified against the proxy architecture spec. A deeper compliance audit of Key Vault access patterns — covering break-glass scenarios, key rotation policies under Azure Policy, and audit-trail coverage of secret reads — is scheduled for the Phase 5 compliance pages.
</x-doc.callout>

## Audit logs

The audit store is metadata-only by default. Each Graph request produces one audit event with the fields listed above. Events are shipped to Elasticsearch at `graphwarden-audit-{org_uuid}-YYYY.MM` when `Audit:ElasticsearchUrl` is configured, and to a MySQL fallback table for small deployments.

Retention is controlled by `microsoft_tenants.audit_retention_tier`. Supported tiers: `base` (30 days), `90d`, `1y`, `7y`. The tier maps to an Elasticsearch ILM policy that enforces deletion automatically. Retention applies only to audit events; it does not affect your Graph data, which remains in your Azure AD tenant under Microsoft's retention terms.

## Response filtering

When a rule declares `action: filter`, the proxy DOES inspect the response body — this is the tradeoff you accept when you ask GraphWarden to redact fields. The inspection is in-memory on the outbound path: the body is parsed, the filter's `allow_properties` or `strip_properties` are applied, and the rewritten body is returned to the caller.

The rewritten body is NOT written to the audit store. Only the rule verdict (matched rule ID, whether a filter ran) is recorded. If your threat model requires that GraphWarden never parse response payloads at all, use only `allow`, `block`, and `log_only` rules and leave response filtering to your client application.

## Troubleshooting

**Proxy log shows `KeyVault: access denied`** — the proxy's Managed Identity does not have `get` on the specific secret. Azure Key Vault grants are per-secret when RBAC mode is enabled; grant `Key Vault Secrets User` scoped to the one secret.

**Audit events contain request bodies despite the default** — a custom `Audit:Destination` sink was added or the deployment is running with `Audit:CaptureBodies=true` (a development-only flag). Confirm in `appsettings.json` and disable for production.

**I want to prove GraphWarden never saw a rotated Graph secret** — Azure Key Vault access logs record every `get` call by caller identity and timestamp. Correlate the secret-write event (your rotation) with the first subsequent `get` (the next MSAL token request). The proxy's in-memory copy is discarded when the Graph token expires.

**`response_filter` is not running but I expected body redaction** — only `action: filter` triggers response inspection. `action: allow` passes bodies through unchanged, and `action: log_only` records the event without modifying the response.

## Take this to your security committee

The trust-model claims above map directly to customer [use cases](/en/use-cases) where a zero-knowledge credential story was the buying signal. To walk the mapping against your own Key Vault topology and Managed Identity layout, [contact the GraphWarden team](/en/contact).

<x-doc.last-reviewed date="2026-04-19" />



## Deploy the GraphWarden proxy to Azure Container Apps

# Deploy the GraphWarden proxy to Azure Container Apps

Azure Container Apps hosts the GraphWarden proxy as a managed container with auto-scaling, integrated Azure AD for Key Vault access, and Azure Monitor telemetry. This page covers ACA-specific deployment via Azure CLI and Bicep, ingress configuration, and scale rules tuned to your Graph request volume.

<x-doc.status-badge status="supported">Azure Container Apps — managed container runtime</x-doc.status-badge>

<x-doc.prerequisites>

- Azure subscription with the `Microsoft.App` resource provider registered
- Azure CLI 2.40+ OR Bicep CLI
- A container image published to Azure Container Registry (ACR) or Docker Hub (see [Docker deployment](./docker))
- A user-assigned managed identity with Key Vault `Secret — Get` permission
- A Log Analytics workspace (for the Container Apps environment)

</x-doc.prerequisites>

<x-doc.ai-prompt title="Generate an ACA Bicep module with an AI assistant">
Generate an Azure Container Apps Bicep module for the GraphWarden proxy.

I need a Bicep template that provisions:
1. A Container Apps environment bound to an existing Log Analytics workspace.
2. A container app pulling the GraphWarden proxy image from Azure Container Registry.
3. External ingress on port 5000 with HTTPS.
4. A user-assigned managed identity for Key Vault access, with AZURE_CLIENT_ID set in env.
5. An HTTP scale rule keyed to concurrent request count.

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my ACR name, Key Vault URI, Graph tenant id, and expected peak request rate.
</x-doc.ai-prompt>

## Why ACA

Azure Container Apps removes the node-management overhead of Kubernetes while retaining the container runtime model. For the GraphWarden proxy, the relevant ACA capabilities are:

- **Auto-scaling** on HTTP concurrency or CPU, including scale-to-zero for non-production environments.
- **Managed identity integration** — attach a user-assigned identity to the container app and access Key Vault without storing service-principal secrets.
- **Azure Monitor Log Analytics** — container stdout/stderr streams land in a workspace with no extra agent.
- **Revision-based rollouts** — traffic split between revisions for canary releases.

ACA is the default recommended deployment target for new proxy installations on Azure. On-premise Windows (see [Windows Service install](./on-premise-windows)) remains the path for air-gapped or customer-managed Windows environments.

## Azure CLI deployment

The snippet below provisions the proxy against an existing Container Apps environment and ACR. Replace the marker values (`<resource-group>`, `<environment-name>`, `<acr-name>`, `<identity-resource-id>`, `<vault-host>`, `<tenant-id>`, `<graph-client-id>`) with your values.

```bash
# Create the container app.
az containerapp create \
  --name graphwarden-proxy \
  --resource-group <resource-group> \
  --environment <environment-name> \
  --image <acr-name>.azurecr.io/graphwarden-proxy:0.1.0 \
  --target-port 5000 \
  --ingress external \
  --user-assigned <identity-resource-id> \
  --min-replicas 1 \
  --max-replicas 10 \
  --cpu 1.0 \
  --memory 2.0Gi \
  --env-vars \
    GraphClient__TenantId=<tenant-id> \
    GraphClient__ClientId=<graph-client-id> \
    KeyVault__VaultUri=https://<vault-host>/ \
    KeyVault__UseManagedIdentity=true \
    AZURE_CLIENT_ID=<identity-client-id> \
    Audit__Enabled=true \
    Audit__DeploymentType=hosted \
  --registry-server <acr-name>.azurecr.io \
  --registry-identity <identity-resource-id>
```

The `--registry-identity` flag tells ACA to authenticate to ACR with the attached user-assigned identity (grant the identity `AcrPull` on the registry first). This eliminates the need for admin credentials on the registry.

The `--env-vars` values above are the minimum for a hosted deployment. Any setting listed on the [environment variables reference](../api-reference/environment-variables) can be added to the same flag with an extra `key=value` entry.

## Bicep template

The Bicep snippet below provisions the container app in the same shape as the CLI command. Keep it in source control under an `infra/` folder.

```bicep
param containerAppName string = 'graphwarden-proxy'
param environmentResourceId string
param containerImage string
param identityResourceId string
param identityClientId string
param vaultUri string
param graphTenantId string
param graphClientId string

resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  name: containerAppName
  location: resourceGroup().location
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityResourceId}': {}
    }
  }
  properties: {
    managedEnvironmentId: environmentResourceId
    configuration: {
      ingress: {
        external: true
        targetPort: 5000
        transport: 'auto'
        allowInsecure: false
      }
      registries: [
        {
          server: split(containerImage, '/')[0]
          identity: identityResourceId
        }
      ]
    }
    template: {
      containers: [
        {
          name: 'proxy'
          image: containerImage
          resources: {
            cpu: json('1.0')
            memory: '2.0Gi'
          }
          env: [
            { name: 'GraphClient__TenantId', value: graphTenantId }
            { name: 'GraphClient__ClientId', value: graphClientId }
            { name: 'KeyVault__VaultUri', value: vaultUri }
            { name: 'KeyVault__UseManagedIdentity', value: 'true' }
            { name: 'AZURE_CLIENT_ID', value: identityClientId }
            { name: 'Audit__Enabled', value: 'true' }
            { name: 'Audit__DeploymentType', value: 'hosted' }
          ]
          probes: [
            {
              type: 'Liveness'
              httpGet: { path: '/health', port: 5000 }
              periodSeconds: 30
              timeoutSeconds: 5
              failureThreshold: 3
            }
          ]
        }
      ]
      scale: {
        minReplicas: 1
        maxReplicas: 10
        rules: [
          {
            name: 'http-concurrency'
            http: {
              metadata: {
                concurrentRequests: '50'
              }
            }
          }
        ]
      }
    }
  }
}

output proxyFqdn string = containerApp.properties.configuration.ingress.fqdn
```

Deploy with `az deployment group create --resource-group <rg> --template-file main.bicep --parameters environmentResourceId=... containerImage=...`. Output `proxyFqdn` is the external URL your client applications rewrite Graph calls to.

## Ingress and routing

Set `ingress.external: true` to publish the proxy at a platform-assigned FQDN on port 443. ACA terminates TLS at the ingress and forwards plaintext to the container on `targetPort`. The proxy does not need to terminate TLS itself — leave `ASPNETCORE_URLS` at `http://+:5000` inside the container.

For a custom domain (for example `proxy.contoso.com`):

1. Add the hostname to the container app with `az containerapp hostname add`.
2. Create a TXT and CNAME record at your DNS provider pointing to the ACA FQDN.
3. Bind a certificate — either an ACA-managed certificate (free, auto-renew) or a certificate uploaded to the Container Apps environment.

The proxy accepts identical Graph paths, so client applications rewrite the Graph base URL from `https://graph.microsoft.com` to `https://proxy.contoso.com` and send unchanged paths and query strings.

## Scale rules

ACA scale rules are based on metrics or HTTP concurrency. For the proxy, the HTTP concurrency rule is the most predictable: each replica handles a configured number of concurrent requests before ACA adds a replica.

A conservative starting configuration:

- `minReplicas: 1` for production (always-on), `minReplicas: 0` for non-production.
- `maxReplicas: 10` — tune upward after observing traffic.
- `concurrentRequests: 50` per replica — see [sizing](./sizing) for the reasoning behind this threshold.

For Graph request volume that bursts sharply (scheduled reporting jobs, for example), set `maxReplicas` high enough that the scale-up does not throttle the burst. ACA scale-up takes 15-60 seconds per replica; plan for the cold-start latency if you run at `minReplicas: 0`.

## Managed identity and Key Vault

Attach a user-assigned managed identity to the container app (see the `identity` block in the Bicep template). Grant the identity `Secret — Get` on the Key Vault holding the proxy's secrets. The proxy reads the Graph client secret, the `ProxyJwt:SigningKey`, and the `RuleSync:HmacSecret` (if sync is enabled) on startup.

Set `AZURE_CLIENT_ID` to the identity's client id (not the resource id). The `Azure.Identity` client inside the proxy uses this value to pick the correct identity when multiple are attached. Omitting it when the container has a single user-assigned identity usually works, but explicit is safer.

For multi-vault deployments (one vault per environment, for example), set `KeyVault__VaultUri` per revision or per environment rather than per image. Image rebuilds are not required when vault URIs change.

## Observability

ACA streams container stdout/stderr to the environment's Log Analytics workspace. The proxy emits Serilog JSON events; each line is a structured log with `Timestamp`, `Level`, `MessageTemplate`, and request-specific properties (`RequestId`, `ClientId`, `GraphPath`, `Decision`).

A Kusto query to find ruleset denials in the last hour:

```text
ContainerAppConsoleLogs_CL
| where TimeGenerated > ago(1h)
| where ContainerAppName_s == "graphwarden-proxy"
| where Log_s contains "\"Decision\":\"deny\""
| project TimeGenerated, Log_s
| order by TimeGenerated desc
```

For dashboards, extend the Log Analytics workspace with an Azure Monitor workbook or pipe events into Azure Data Explorer for long-term retention. The proxy emits the same events on-prem and in ACA — the sink differs, the schema does not.

## Troubleshooting

### Container app stuck in `Provisioning` for more than 5 minutes

The user-assigned managed identity does not have `AcrPull` on the container registry, or the image tag does not exist. Check `az containerapp logs show --name graphwarden-proxy` for image-pull errors. Assign `AcrPull` on the ACR with `az role assignment create --role AcrPull --assignee <identity-principal-id> --scope <acr-resource-id>` and redeploy.

### Ingress FQDN returns 502 Bad Gateway

The container is running but the liveness probe is failing. Inspect logs — the usual cause is `KeyVault: access denied`. Confirm the managed identity has `Secret — Get` on the vault and that `AZURE_CLIENT_ID` matches the identity's client id (not its principal id or resource id).

### Proxy issues tokens but Graph calls return 401

The Graph client secret in Key Vault is stale. Rotate the Azure AD app secret, write the new value to Key Vault under the same secret name, and restart the container app revision (`az containerapp revision restart`). The proxy re-reads Key Vault on startup.

### Scale never exceeds `minReplicas`

The HTTP scale rule is not activating because request rate is below the `concurrentRequests` threshold, OR the scale rule is misconfigured. Check the ACA portal "Scale" blade; the active rule should show the current concurrent requests per replica. If the value is climbing but replica count is not, verify `maxReplicas` is higher than `minReplicas` and that the environment is not at its quota.

### Cold start takes longer than 30 seconds

Running at `minReplicas: 0` with a large image (Windows containers are typical offenders) produces long cold starts. Options: switch to the Linux variant of the Docker image (see [Docker](./docker) "Running on Linux vs Windows"), or set `minReplicas: 1` to keep a warm replica. ACA charges per replica-second, so the tradeoff is cost vs latency.

<x-doc.last-reviewed date="2026-04-19" />



## Deploy the GraphWarden proxy with Docker

# Deploy the GraphWarden proxy with Docker

Run the GraphWarden proxy as a Docker container on any Linux or Windows Docker host. The image is built from the published .NET binaries; configuration is environment-driven (see the [environment variables reference](../api-reference/environment-variables)). This page covers a Dockerfile pattern, docker-compose orchestration, health checks, and Key Vault access from a container.

<x-doc.status-badge status="supported">Docker Engine 20.10+ on Linux or Windows</x-doc.status-badge>

<x-doc.prerequisites>

- Docker Engine 20.10+ OR Docker Desktop
- Access to the published GraphWarden proxy binaries (or a built image from your build pipeline)
- Azure Key Vault with a managed identity or service principal that the container can authenticate as
- Outbound firewall rules per [networking and firewall](./networking-firewall)
- An [Azure Container Apps](./azure-container-apps) environment or any container host of your choice for runtime

</x-doc.prerequisites>

<x-doc.ai-prompt title="Build a GraphWarden Docker image with an AI assistant">
Help me build a GraphWarden proxy Docker image from published binaries.

I have a directory of published .NET 8 binaries including GraphProxy.Proxy.dll (Linux) or GraphProxy.Proxy.exe (Windows). I want:
1. A minimal Dockerfile using mcr.microsoft.com/dotnet/aspnet:8.0 as the runtime base.
2. A docker-compose.yml for local development that injects env vars from a .env file.
3. A HEALTHCHECK that curls the proxy's /health endpoint on the Kestrel port.
4. Guidance on mounting a rules.yaml file and reading Key Vault credentials via managed identity or a service principal.

Reference documentation: https://graphwarden.com/llms.txt

Ask me whether my deployment target is Linux or Windows, and whether I'll use managed identity or a service principal for Key Vault access.
</x-doc.ai-prompt>

## Image source

The GraphWarden proxy ships as a set of published .NET binaries. The container image is built from those binaries; the project does not currently publish an official image. Your build pipeline copies the publish output into a base image, sets an entrypoint, and pushes the resulting image to your registry (Azure Container Registry, Docker Hub, or a private registry).

<x-doc.callout type="note">
An official published Docker image is planned. For now, build locally from the published .NET binaries. The Dockerfile pattern below is stable and tracks the proxy's binary layout.
</x-doc.callout>

The proxy is an ASP.NET Core self-hosted Kestrel service (not IIS). On Linux the entrypoint is `dotnet GraphProxy.Proxy.dll`. On Windows containers the entrypoint is `GraphProxy.Proxy.exe`. The binding port defaults to `5000` unless overridden by `Kestrel` configuration.

## Dockerfile pattern

The Dockerfile below uses the ASP.NET Core 8.0 runtime as its base, copies the publish output into `/app`, exposes the Kestrel port, and sets an entrypoint. Adapt the `COPY` source path to your build pipeline's publish directory.

```dockerfile
# Linux variant — use for Azure Container Apps, Kubernetes, and most container hosts.
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app

# Copy the published .NET 8 output produced by `dotnet publish -c Release`.
COPY ./publish/ .

# Kestrel binds to 5000 by default; override with ASPNETCORE_URLS if your host
# expects a different port.
ENV ASPNETCORE_URLS=http://+:5000
EXPOSE 5000

# Health check — the proxy exposes /health on the same Kestrel listener.
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -fsS http://localhost:5000/health || exit 1

ENTRYPOINT ["dotnet", "GraphProxy.Proxy.dll"]
```

For Windows container hosts, swap the base image and entrypoint:

```dockerfile
# Windows variant — use only when your container host runs Windows.
FROM mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime
WORKDIR C:\\app

COPY ./publish/ .

ENV ASPNETCORE_URLS=http://+:5000
EXPOSE 5000

ENTRYPOINT ["GraphProxy.Proxy.exe"]
```

Both variants read the same environment variables. The Windows image does not define a `HEALTHCHECK` with `curl` because `curl.exe` is not present in the base image by default — your orchestrator should probe `/health` out-of-band (Kubernetes `livenessProbe`, Azure Container Apps probe, or a custom PowerShell `HEALTHCHECK` script).

## Environment configuration

Every proxy setting is overridable by environment variable with double-underscore (`__`) nesting. For example, `GraphClient:TenantId` maps to `GraphClient__TenantId`. The [environment variables reference](../api-reference/environment-variables) lists every supported key and its default.

A minimal `.env` file for container orchestration looks like:

```bash
# Identity
GraphClient__TenantId=00000000-0000-0000-0000-000000000000
GraphClient__ClientId=11111111-1111-1111-1111-111111111111

# Key Vault — production path
KeyVault__VaultUri=https://myvault.vault.azure.net/
KeyVault__UseManagedIdentity=true

# JWT signing (32+ chars)
ProxyJwt__SigningKey=replace-with-a-32-plus-character-secret
ProxyJwt__Issuer=graphproxy
ProxyJwt__Audience=graphproxy

# Audit
Audit__Enabled=true
Audit__IngestionUrl=https://app.graphwarden.example.com/api/v1/agent/audit
Audit__DeploymentType=hosted
```

Do not commit this file. Use your platform's secret store (Azure Container Apps secrets, Kubernetes secrets, Docker Swarm secrets) to inject values at runtime.

## docker-compose example

The compose file below wires the proxy to a local `.env` file, exposes port 5000, and declares a health check that matches the Dockerfile's expectation.

```yaml
services:
  proxy:
    image: myregistry.azurecr.io/graphwarden-proxy:0.1.0
    container_name: graphwarden-proxy
    restart: unless-stopped
    ports:
      - "5000:5000"
    env_file:
      - ./.env
    volumes:
      - ./rules.yaml:/config/rules.yaml:ro
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:5000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
```

The `./rules.yaml` volume mount gives the proxy a read-only ruleset file. The proxy reads this file at startup and on `RuleSync` refresh (when `RuleSync__Enabled=true`). If your ruleset is managed entirely from the GraphWarden control plane, omit the volume and leave `Rules__FilePath` at its default.

## Health check

The proxy exposes `GET /health` on the same Kestrel listener as Graph traffic. A healthy response is `200 OK` with a JSON status object. The `HEALTHCHECK` directive above runs every 30 seconds; adjust the interval if your orchestrator polls liveness independently.

For Kubernetes, use a `livenessProbe` and `readinessProbe` pointing at `/health` on the same port. For Azure Container Apps, the platform probes the configured ingress port at a configurable path (see [Azure Container Apps](./azure-container-apps) for the ACA-specific snippet).

## Key Vault access from a container

The proxy reads Graph credentials, the JWT signing key, and the `RuleSync` HMAC secret from Azure Key Vault at startup. Three container-deployment patterns are supported.

**Workload identity (Azure Container Apps, AKS with workload identity)**. Set `AZURE_CLIENT_ID` to the user-assigned managed identity's client id. The proxy's `Azure.Identity` client acquires a token from the platform's workload-identity endpoint. `KeyVault__UseManagedIdentity=true` must be set. No secrets live in the container.

**System-assigned managed identity (Azure VMs, Azure Container Instances)**. Leave `AZURE_CLIENT_ID` unset; `Azure.Identity` uses the VM metadata service automatically. `KeyVault__UseManagedIdentity=true`.

**Service principal (non-Azure hosts, on-premise Kubernetes)**. Set `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET` on the container. `Azure.Identity` uses client-credential authentication against Azure AD, then accesses Key Vault. The service principal needs `Secret — Get` on the vault. This is the only pattern that places a secret in the container environment; store `AZURE_CLIENT_SECRET` in your platform's secret store, not a committed `.env` file.

For air-gapped deployments where Azure Key Vault is not reachable, the proxy supports an in-memory secret store for development. Set `KeyVault__UseManagedIdentity=false` and provide secrets through environment variables directly (for example `GraphClient__ClientSecret=...`). This path is not recommended for production.

## Running on Linux vs Windows

The Linux variant (`dotnet/aspnet:8.0`) is the recommended default. It is smaller, starts faster, and has a wider ecosystem of orchestrators. Azure Container Apps, AKS Linux node pools, and most Kubernetes distributions run Linux containers natively.

The Windows variant is useful when the proxy must run alongside other Windows containers that require Windows-specific APIs. It uses the larger Windows Server Core base image and takes longer to start. Path separators in volume mounts use backslashes (`C:\\config\\rules.yaml`) and the entrypoint executable is `GraphProxy.Proxy.exe` rather than a `dotnet` invocation.

Mixed-OS clusters require either separate node pools (one Linux, one Windows) or two distinct images. Do not try to run a Windows container on a Linux host or vice versa — the platform does not emulate.

## Troubleshooting

### Container starts but `/health` returns 503

The container process is running but the proxy cannot reach Key Vault. Inspect logs with `docker logs graphwarden-proxy` and look for `Azure.Identity.CredentialUnavailableException` or `KeyVault: access denied`. The usual cause is a missing `AZURE_CLIENT_ID` environment variable (for workload identity) or a service principal that lacks `Secret — Get` on the vault. Confirm the managed identity or service principal has the permission and that the container's `AZURE_*` environment variables match.

### `curl: command not found` in Windows container health check

The Windows Server Core base image does not include `curl.exe`. Either switch to the Linux variant, or replace the `HEALTHCHECK` with a PowerShell probe (`pwsh -Command "Invoke-WebRequest -UseBasicParsing http://localhost:5000/health"`), or rely on your orchestrator's out-of-band liveness probe.

### Proxy rejects token requests with `403 signing key mismatch`

The `ProxyJwt__SigningKey` differs between container restarts or between multiple instances behind a load balancer. Store the signing key in your secret manager once and inject the same value into every instance. A rolling restart with a changed signing key invalidates every issued proxy JWT.

### docker-compose cannot resolve the image from Azure Container Registry

The Docker daemon is not authenticated to ACR. Run `az acr login --name myregistry` before `docker compose up`, or configure `~/.docker/config.json` with an access token. For CI pipelines, use `docker login` with a service principal credential; anonymous pulls are disabled on private ACR registries.

### Container exits immediately with exit code 139 on Linux

The proxy hit a segmentation fault in the .NET runtime — almost always a mismatched base image architecture. Confirm you built the image with `--platform linux/amd64` if your Docker daemon runs a different default (common on Apple Silicon machines targeting Azure). Rebuilding with `docker buildx build --platform linux/amd64` resolves the mismatch.

<x-doc.last-reviewed date="2026-04-19" />



## Network and firewall requirements for the GraphWarden proxy

# 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.

<x-doc.status-badge status="supported">Outbound and inbound firewall rules for the proxy</x-doc.status-badge>

<x-doc.prerequisites>

- Firewall administrator access on the network segment hosting the proxy
- The GraphWarden control-plane URL (from your GraphWarden administrator — the value of `Audit:IngestionUrl` and `RuleSync:SaasBaseUrl` in the proxy configuration)
- The Key Vault URI the proxy reads secrets from (for example `https://myvault.vault.azure.net`, the value of `KeyVault:VaultUri`)

</x-doc.prerequisites>

## Outbound connections required

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

| Destination | Port | Protocol | Purpose |
|---|---|---|---|
| `login.microsoftonline.com` | 443 | HTTPS | Azure AD token acquisition for Microsoft Graph (MSAL client_credentials flow) |
| `graph.microsoft.com` | 443 | HTTPS | Microsoft Graph API — the upstream the proxy routes filtered requests to |
| `*.vault.azure.net` (or your specific vault) | 443 | HTTPS | Azure Key Vault — credential retrieval at startup and on secret refresh |
| `<your-control-plane-host>` | 443 | HTTPS | GraphWarden control plane — ruleset sync and audit ingestion |

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.

| Listener | Default port | Protocol | Who reaches it |
|---|---|---|---|
| Proxy token + Graph traffic | 5000 | HTTPS (TLS-terminated by Kestrel or a reverse proxy) | Client applications on the same network segment as the proxy |
| Health endpoint (`GET /health`) | 5000 | HTTPS | Monitoring tooling (for example the local Nagios / Zabbix agent) |
| Metrics endpoint (`GET /metrics`) | 5000 | HTTPS | Prometheus scraper or equivalent metrics collector |

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.

```powershell
# 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.

<x-doc.last-reviewed date="2026-04-19" />



## Install the GraphWarden proxy as a Windows Service

# Install the GraphWarden proxy as a Windows Service

Install the GraphWarden proxy as a Windows Service on Windows Server 2019 or 2022. The proxy runs a self-hosted Kestrel listener and is managed via `sc.exe` or the Services MMC snap-in. The proxy does NOT run under IIS. This page covers service-account setup, Key Vault permissions, and firewall prerequisites.

<x-doc.status-badge status="supported">Windows Server 2019 and 2022 (Server 2016 out of support)</x-doc.status-badge>

<x-doc.prerequisites>

- Windows Server 2019 or 2022 (Server 2016 is out of support)
- Administrative rights on the target server
- A service account with Key Vault `get` permission on the proxy's secrets
- .NET 8.0 runtime installed (the proxy is ASP.NET Core self-hosted)
- Outbound network access to Microsoft identity, Graph, Key Vault, and the GraphWarden control plane (see `./networking-firewall` for the full list)

</x-doc.prerequisites>

<x-doc.callout type="warning">
The GraphWarden proxy does NOT run under IIS. It is an ASP.NET Core self-hosted application using Kestrel. Do not create an IIS application pool for it. Do not place it behind `w3wp.exe`. The Windows Service wrapper described below is the supported hosting model.
</x-doc.callout>

## What the proxy runs as

The GraphWarden proxy is an ASP.NET Core application that hosts its own Kestrel HTTP listener. A Windows Service wrapper (`builder.Host.UseWindowsService()` in `Program.cs`) registers the process with the Service Control Manager so it starts at boot, restarts on crash per your recovery configuration, and logs to the Windows Event Log.

The proxy binds to a configurable port on startup; the health endpoint (`GET /health`) defaults to `http://localhost:5000/health` when no Kestrel binding is set. Production deployments override the listener via `appsettings.json` or environment variables to bind to a specific hostname and port.

## Step 1: Prepare the service account

Create a dedicated account for the proxy rather than running it as `LocalSystem`. The account needs read access to the proxy's Key Vault secrets and the right to log on as a service.

1. Create a domain or local account (for example `DOMAIN\graphwarden-svc`). Set a strong password and store it in your secret management system — the password is supplied to `sc.exe` in Step 4.
2. Grant `Log on as a service` to the account. Open **Local Security Policy** > **Local Policies** > **User Rights Assignment** > **Log on as a service**, then add the account.
3. Grant the account the Key Vault `get` secrets permission. In the Azure portal, open the target Key Vault, navigate to **Access policies** (or **Access control (IAM)** for RBAC-mode vaults), and grant the account `Secret — Get`. The proxy reads the Graph client secret, the `ProxyJwt:SigningKey`, and the `RuleSync:HmacSecret` (if sync is enabled) from Key Vault at startup.

If you use Managed Identity instead of a traditional service account, assign the VM's system-assigned identity the same `Secret — Get` permission. Managed Identity is the production-recommended pattern per the proxy architecture recon.

## Step 2: Install .NET 8.0 runtime

The proxy targets .NET 8.0 and requires the ASP.NET Core runtime (hosting bundle) on the server. Install it from an elevated PowerShell session:

```powershell
# Install .NET 8.0 runtime (hosting bundle includes runtime + ASP.NET Core runtime).
winget install Microsoft.DotNet.HostingBundle.8
```

Verify with `dotnet --list-runtimes`; you should see `Microsoft.AspNetCore.App 8.0.x` in the output. If `winget` is not available on the server, download the hosting bundle from the Microsoft .NET site and install it interactively.

## Step 3: Deploy the proxy binaries

Unzip the published GraphWarden Proxy artifacts to `C:\Program Files\GraphWarden\Proxy\` (or your preferred path). Copy your `appsettings.json` into the same directory. Ensure the service account from Step 1 has **Read & Execute** on the directory.

The directory layout after deployment looks like:

```text
C:\Program Files\GraphWarden\Proxy\
  GraphProxy.Proxy.exe
  appsettings.json
  appsettings.Production.json   (optional overrides)
  (other runtime DLLs)
```

Keep the `appsettings.json` free of real secrets — the proxy pulls secrets from Key Vault at startup based on `KeyVault:VaultUri` and `KeyVault:UseManagedIdentity`.

## Step 4: Create the Windows Service

Register the service with `sc.exe`. Run the commands below from an elevated command prompt (not PowerShell — `sc.exe` argument parsing differs in PowerShell).

```powershell
# Replace the following paths and account name with your values.
sc.exe create GraphWardenProxy binPath= "C:\Program Files\GraphWarden\Proxy\GraphProxy.Proxy.exe" start= auto obj= "DOMAIN\graphwarden-svc" password= "<stored in secure secret store>"
sc.exe description GraphWardenProxy "GraphWarden proxy for Microsoft Graph API governance."
sc.exe failure GraphWardenProxy reset= 60 actions= restart/5000/restart/5000/restart/5000
```

The `failure` command configures automatic restart: three consecutive restarts at 5-second intervals, with the failure counter reset after 60 seconds of uptime. The space after each `=` in `sc.exe` is intentional — without it the argument parser rejects the command.

If you prefer Managed Identity over a domain account, omit `obj=` and `password=`; the service runs as `LocalSystem` and Managed Identity handles Key Vault authentication through the VM's metadata endpoint.

## Step 5: Configure environment

The proxy reads configuration from `appsettings.json`, `appsettings.Production.json`, and environment variables (with environment variables taking precedence). The full inventory of settings — including `KeyVault:VaultUri`, `KeyVault:UseManagedIdentity`, `GraphClient:TenantId`, `ProxyJwt:SigningKey`, and the `RuleSync:*` / `Audit:*` families — is documented on [the environment variables reference](../api-reference/environment-variables).

For a minimum on-premise install, set `KeyVault:VaultUri`, `KeyVault:UseManagedIdentity`, `GraphClient:TenantId`, and `GraphClient:ClientId` in `appsettings.json`, and store `GraphClient:ClientSecret` and `ProxyJwt:SigningKey` in Key Vault under the names the proxy expects.

## Step 6: Start the service

Start the service and confirm it reports `RUNNING`:

```powershell
sc.exe start GraphWardenProxy
sc.exe query GraphWardenProxy
```

The `query` output should show `STATE : 4 RUNNING`. The Services MMC snap-in (`services.msc`) is an equivalent UI — find `GraphWardenProxy` in the list and confirm the status.

## Verifying the installation

Once the service reports `RUNNING`, verify the proxy is healthy from the server itself:

```powershell
# From the proxy host; adjust the port if you overrode the Kestrel binding.
curl http://localhost:5000/health
```

A healthy proxy returns a JSON status object. The `/metrics` endpoint at the same host and port returns Prometheus-compatible counters (request rates, latency percentiles, and audit-buffer state). If either endpoint does not respond, check the Windows Event Log under **Applications and Services Logs** — the proxy emits Serilog JSON events to the `Application` log with `GraphWardenProxy` as the source.

## Upgrading the proxy

Upgrade is a stop-replace-start cycle. The Windows Service wrapper waits for in-flight requests to complete before the process exits, but long-running Graph operations may be cut off if your stop-timeout is aggressive.

1. Stop the service: `sc.exe stop GraphWardenProxy`.
2. Wait for `sc.exe query GraphWardenProxy` to report `STOPPED`.
3. Replace the binaries in `C:\Program Files\GraphWarden\Proxy\` with the new version. Keep `appsettings.json` in place unless the release notes flag a configuration change.
4. Start the service: `sc.exe start GraphWardenProxy`.
5. Verify `/health` returns the new version string.

Roll back by reversing Step 3 and restarting the service. Because configuration is external (Key Vault + `appsettings.json`), downgrades and upgrades are symmetric.

## Troubleshooting

### Service fails to start (Error 1053)

Error 1053 (`The service did not respond to the start or control request in a timely fashion`) almost always means the .NET 8.0 runtime is missing or the wrong architecture. Run `dotnet --list-runtimes` as the service account; if `Microsoft.AspNetCore.App 8.0.x` is not listed, repeat Step 2. On a 64-bit Windows Server the x64 hosting bundle is required — the x86 bundle will not host a 64-bit proxy binary.

### Service starts but proxy returns 503

The service process is running but the proxy cannot reach Key Vault. Check the Windows Event Log for `Azure.Identity.CredentialUnavailableException` or `KeyVault: access denied`. The most common cause is the service account lacking `Secret — Get` on the vault; repeat Step 1.3. For Managed Identity, confirm the VM has a system-assigned identity and that identity has the same permission.

### 503 on token endpoint only

The proxy starts, Key Vault access works for the `ProxyJwt:SigningKey`, but `/proxy/token` returns 503. The Graph client secret stored in Key Vault is stale — the Azure AD app's secret has been rotated but Key Vault still holds the old version. Retrieve the current secret from the Azure AD app registration, write it to Key Vault under the same secret name, and restart the service. The proxy re-reads secrets at startup.

### Port already in use

Service start fails with `Kestrel: Failed to bind to address`. Another process is bound to the listener port. Run `netstat -ano | findstr :5000` (or whichever port you configured) to find the PID, then `tasklist /fi "pid eq <PID>"` to identify the process. Either stop the conflicting service or override the Kestrel binding in `appsettings.json` to a free port.

### IIS returns 404 for proxy URL

You accidentally created an IIS site that binds the same hostname or port as the proxy. The proxy does NOT run under IIS — it is a self-hosted Kestrel service. Open **IIS Manager** and remove any site or application pool that references `GraphWardenProxy` or the proxy's binaries. After removing the IIS configuration, restart the `GraphWardenProxy` Windows Service.

<x-doc.last-reviewed date="2026-04-19" />



## Sizing the GraphWarden proxy for your request volume

# Sizing the GraphWarden proxy for your request volume

The GraphWarden proxy's CPU and memory needs scale with request rate and response-body transform complexity. This page gives conservative starting-point recommendations and a methodology for profiling your workload. Adjust based on your observed CPU and memory during load testing — these numbers are reference baselines, not guarantees.

<x-doc.status-badge status="beta">Reference baselines — validate against your workload</x-doc.status-badge>

<x-doc.prerequisites>

- A deployed proxy — [Windows Service](./on-premise-windows), [Docker](./docker), or [Azure Container Apps](./azure-container-apps)
- Representative test traffic OR production request-rate data
- Resource monitoring — Azure Monitor, Prometheus, Task Manager, or your preferred telemetry stack

</x-doc.prerequisites>

<x-doc.callout type="warning">
These are reference-authored baselines. Your workload may vary by 2-3× based on response-filter complexity and request-body size. Profile before production. Do not use the numbers below as a capacity guarantee.
</x-doc.callout>

<x-doc.ai-prompt title="Size a proxy deployment with an AI assistant">
Help me size a GraphWarden proxy for my expected workload.

Given my request profile (peak requests per minute, average response body size, and response filter complexity), recommend:
1. Starting CPU and memory allocation per replica.
2. Minimum and maximum replica counts.
3. A profiling plan to validate the recommendation against real traffic.

Reference documentation: https://graphwarden.com/llms.txt

Ask me for peak request rate, the kinds of Graph endpoints my clients hit most often, and whether my rulesets apply heavy response filters (many allow_properties or deep nested filtering).
</x-doc.ai-prompt>

## Reference baseline (for initial provisioning)

The table below is a starting point for CPU and memory allocation per proxy replica. Rows target peak request rates, not averages. Provision for peak; auto-scaling handles the rest.

| Req/min | vCPU | RAM | Notes |
|---|---|---|---|
| ≤ 100 | 0.5 | 512 MB | Single replica. Typical dev/test workload. |
| 100-1000 | 1.0 | 1 GB | Single replica. Light production. |
| 1000-5000 | 2.0 | 2 GB | Single replica with headroom, or 2 small replicas. |
| 5000-20000 | 4.0 | 4 GB | Consider horizontal scale: 2-4 replicas of 2 vCPU / 2 GB each. |
| > 20000 | — | — | Horizontal scale mandatory: multiple replicas behind a load balancer. See "Horizontal scale considerations" below. |

Memory is driven primarily by response-body buffering. Graph responses can be large (a `GET /users?$expand=...` call against a large tenant returns megabytes per page), and the proxy holds the response in memory while applying filters. Doubling the RAM column is a safe first response to sustained memory pressure — doubling vCPU is the right response to sustained CPU pressure.

## Dimensions that affect sizing

Four dimensions dominate proxy resource use:

- **Response transform complexity**. Rulesets with many `allow_properties` entries, deep nested filtering, or hash/mask transforms over large objects consume more CPU per request. A rule that filters a single property is cheap; a rule with 20 transforms over a nested object adds measurable CPU.
- **Request body size**. Write operations (POST, PATCH, DELETE) with large request bodies consume memory proportional to body size. The proxy's default `Kestrel:MaxRequestBodySizeMb` is 10 MB — raising it raises the memory ceiling per request.
- **Concurrent connection count**. Each concurrent request holds a connection, a request buffer, and (usually) a response buffer. Connection count is the best proxy for "current memory demand" and is what the ACA HTTP scale rule keys on.
- **Logging verbosity**. At `Logging:LogLevel:GraphProxy=Debug` the proxy logs every decision; at `Information` it logs only denials and errors. Debug logging can add 10-20% CPU at high request rates and produces significant log volume.

## Profiling methodology

Profiling against real traffic is the only way to size accurately. A four-step process:

**Step 1 — Capture baseline at representative rate**. Deploy the proxy at the table's baseline for your expected peak. Run representative traffic (either production mirror or synthetic load at production-like endpoint mix) for 30-60 minutes. Capture CPU, memory, and request latency percentiles.

**Step 2 — Increase linearly**. Double the request rate. Observe which metric saturates first — CPU will cap at 100%, memory will trigger GC pressure and eventually OOM. Note the request rate at which either saturates. This is your current capacity ceiling.

**Step 3 — Identify headroom**. Your production target is the capacity ceiling minus 30-40%. Running at 70% of capacity leaves room for Graph-side latency spikes (which fan out into more concurrent proxy requests at the same rate) and rule evaluations that periodically fan out Graph calls of their own (`group_membership` checks, for example).

**Step 4 — Validate under fault conditions**. Run the load test with Graph API artificially delayed (use an outbound proxy that injects 2-3 second latency). Confirm the proxy's resource use stays stable rather than spiking — if memory climbs unbounded, the concurrent-request count is too high and max-replicas needs to rise.

Repeat every major ruleset change and every quarterly review. Rulesets accrete transforms over time; a ruleset that fit on 1 vCPU at launch may need 2 vCPU six months later.

## Horizontal scale considerations

The proxy is stateless. All state (ruleset, Graph tokens, audit buffer) is either read-only (ruleset, refreshed from control plane) or per-request (audit events are flushed on a timer and replayed from local retention if the cloud is unreachable).

Because the proxy is stateless, horizontal scale requires no session affinity. A simple round-robin or least-connections load balancer distributes traffic evenly. For Azure Container Apps, the built-in ingress handles this automatically. For on-premise deployments, any TCP or HTTPS load balancer (Azure Load Balancer, F5, HAProxy, nginx) works without special configuration.

Two caveats:

- **`ProxyJwt:SigningKey` must be identical across replicas**. A token issued by replica A must validate at replica B. Store the signing key in Key Vault once and inject it into every replica; do not generate per-replica keys.
- **Audit retention is per-replica**. If a replica with undelivered audit events in its local retention path is destroyed (scale-down, pod eviction), those events are lost. For strict compliance deployments, pin the retention path to a persistent volume that survives replica churn, or set `Audit:FlushIntervalSeconds` low enough that the in-memory buffer is small.

## Troubleshooting

### CPU sits at 100% with modest request rate

The ruleset is doing too much work per request. Inspect your `response_filter` blocks — deeply nested `allow_properties` lists, hash or noise transforms applied to large string fields, and `regex_replace` with complex expressions all accumulate CPU. Simplify the most expensive rule first (measure which rule dominates with Serilog's `Decision` events filtered by `RuleId`).

### Memory climbs until OOM or GC pause spike

Response bodies from Graph are large enough to pressure the heap. Two fixes: increase `memory` allocation (doubling is the usual starting point), or reduce the client's `$select` footprint on hot endpoints so Graph returns fewer bytes per page. Server-side `$select` is almost always cheaper than proxy-side filtering of full objects.

### Intermittent 503 under peak load

The Key Vault client is throttling. Azure Key Vault caps request rate per vault (2000 requests per 10 seconds at the standard tier). The proxy reads secrets on startup and on rotation, not per request — intermittent 503s from vault throttling usually indicate a rapid-scale event where many replicas started simultaneously. Increase `minReplicas` to reduce the churn, or stagger startup across replicas if your orchestrator supports it.

### Request latency doubles at a specific request rate threshold

Kestrel's default thread pool saturates. The proxy's CPU is below 100% but the per-request latency climbs — work is queued waiting for a thread. Increase CPU allocation (Kestrel thread pool sizes based on `Environment.ProcessorCount`) or add a replica. This symptom is a clearer signal to scale horizontally than vertical CPU growth.

<x-doc.last-reviewed date="2026-04-19" />



## Integrate GraphWarden with a .NET application

# Integrate GraphWarden with a .NET application

A .NET application using `Microsoft.Identity.Client` (MSAL) and `Microsoft.Graph` (the Microsoft Graph SDK for .NET) can route every Graph call through GraphWarden by overriding two values: the token endpoint and the Graph base URL. The rest of the SDK surface — request builders, entity models, pagination, `$select` and `$filter` — keeps working unchanged. This page shows a complete working sample.

<x-doc.status-badge status="supported">MSAL 4.x + Microsoft.Graph 5.x</x-doc.status-badge>

<x-doc.prerequisites>

- .NET 6 or later (the sample targets .NET 8; earlier LTS versions also work)
- `Microsoft.Graph` v5.x NuGet package
- `Microsoft.Identity.Client` v4.x NuGet package (pulled in transitively by Graph, or installed explicitly for the token flow)
- A GraphWarden proxy URL reachable from your app
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this application

</x-doc.prerequisites>

<x-doc.ai-prompt title="Migrate a .NET application with an AI assistant">
Migrate my existing .NET application from direct Microsoft Graph API calls to use GraphWarden as a proxy.

My app currently uses ClientSecretCredential with https://graph.microsoft.com.

I need to:
1. Change the base URL to my GraphWarden proxy URL
2. Replace real Graph credentials with GraphWarden proxy credentials
3. Preserve all existing Graph SDK calls unchanged
4. Add error handling for GraphWarden-specific responses (401 invalid proxy credentials, 403 ruleset denial)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for:
- My GraphWarden proxy URL
- My proxy client_id and proxy client_secret
- Which Graph endpoints and scopes my app uses today
</x-doc.ai-prompt>

## The two overrides

A direct-to-Graph .NET app configures two things: a `ConfidentialClientApplication` pointed at Azure AD, and a `GraphServiceClient` that defaults to `https://graph.microsoft.com`. To route through GraphWarden you override both.

- **Token acquisition** — build the `ConfidentialClientApplication` against the proxy's token endpoint (`/proxy/token`) instead of Azure AD, and pass the Proxy Client ID and Proxy Client Secret in place of the Azure AD app credentials. The token you receive is a proxy JWT, not a Graph token; treat it as an opaque Bearer value.
- **Graph base URL** — construct the `GraphServiceClient` with an `HttpClient` whose `BaseAddress` points at the proxy. The Graph SDK composes request URIs against that base address, so `graphClient.Users.GetAsync(...)` issues `GET {proxy-host}/v1.0/users` with the proxy JWT attached.

## Minimal working sample

The program below acquires a proxy JWT and lists display names for the first page of users. The two overrides are named explicitly so the shape of the change is obvious. Production apps should pull the proxy URL and credentials from configuration (see the next section) rather than hardcoding them.

<x-doc.code-block lang="csharp">
using System.Net.Http.Headers;
using Microsoft.Graph;
using Microsoft.Identity.Client;

// 1. Configuration — in production, load these from IConfiguration / env vars.
string proxyBaseUrl    = "https://proxy.example.com";                 // Issued when the proxy was deployed
string tokenEndpoint   = $"{proxyBaseUrl}/proxy/token";               // GraphWarden-issued proxy JWT endpoint
string proxyClientId   = "00000000-0000-0000-0000-000000000000";      // Proxy Client ID from App Admin
string proxyClientSec  = "REDACTED";                                  // Proxy Client Secret from App Admin

// 2. Acquire a proxy JWT via client_credentials against the proxy token endpoint.
//    Note: Authority is the proxy, NOT Azure AD. The proxy issues its own token.
var cca = ConfidentialClientApplicationBuilder
    .Create(proxyClientId)
    .WithClientSecret(proxyClientSec)
    .WithAuthority(new Uri(tokenEndpoint), validateAuthority: false)
    .Build();

var tokenResult = await cca
    .AcquireTokenForClient(new[] { "https://graph.microsoft.com/.default" })
    .ExecuteAsync();

string proxyJwt = tokenResult.AccessToken;

// 3. Build a GraphServiceClient whose HttpClient points at the proxy.
//    Every SDK call now hits {proxyBaseUrl}/{graph-path}.
var http = new HttpClient
{
    BaseAddress = new Uri(proxyBaseUrl),
};
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", proxyJwt);

var graphClient = new GraphServiceClient(http);

// 4. Standard Graph SDK call — unchanged from a direct-Graph integration.
var users = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Select = new[] { "displayName" };
    config.QueryParameters.Top    = 10;
});

foreach (var user in users?.Value ?? new List<Microsoft.Graph.Models.User>())
{
    Console.WriteLine(user.DisplayName);
}
</x-doc.code-block>

The important call is `graphClient.Users.GetAsync(...)`. The SDK call is identical to what you would write for a direct Graph integration — no request rewriting, no URL string building, no custom middleware. The `HttpClient.BaseAddress` override is what points the SDK at the proxy.

<x-doc.callout type="info">
The proxy accepts the same Graph paths and query strings Microsoft Graph accepts, byte-for-byte. `$select`, `$filter`, `$expand`, pagination with `@odata.nextLink`, and batch requests all pass through unchanged. If a rule's Response Filter removes properties, the missing keys will not appear in the deserialized entity — a `User` with `GivenName` stripped will have `GivenName == null`.
</x-doc.callout>

## Configuration via environment

In production, read the proxy URL and credentials from environment variables or your configuration provider of choice. The conventional names below align with the proxy's own `__` double-underscore override pattern.

<x-doc.code-block lang="csharp">
// Program.cs — Generic Host sample. Adjust for ASP.NET Core startup.
var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<GraphServiceClient>(sp =>
{
    var cfg = sp.GetRequiredService<IConfiguration>();

    string proxyBaseUrl  = cfg["GRAPHWARDEN_PROXY_URL"]
        ?? throw new InvalidOperationException("GRAPHWARDEN_PROXY_URL is required.");
    string proxyClientId = cfg["GRAPHWARDEN_CLIENT_ID"]
        ?? throw new InvalidOperationException("GRAPHWARDEN_CLIENT_ID is required.");
    string proxyClientSec= cfg["GRAPHWARDEN_CLIENT_SECRET"]
        ?? throw new InvalidOperationException("GRAPHWARDEN_CLIENT_SECRET is required.");

    var cca = ConfidentialClientApplicationBuilder
        .Create(proxyClientId)
        .WithClientSecret(proxyClientSec)
        .WithAuthority(new Uri($"{proxyBaseUrl}/proxy/token"), validateAuthority: false)
        .Build();

    var token = cca
        .AcquireTokenForClient(new[] { "https://graph.microsoft.com/.default" })
        .ExecuteAsync()
        .GetAwaiter()
        .GetResult()
        .AccessToken;

    var http = new HttpClient { BaseAddress = new Uri(proxyBaseUrl) };
    http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

    return new GraphServiceClient(http);
});
</x-doc.code-block>

Real code should refresh the proxy JWT before expiry rather than acquiring once at startup — MSAL's token cache handles the refresh for you if you keep the same `IConfidentialClientApplication` instance around and call `AcquireTokenForClient` on each use. MSAL returns a cached token when one is still valid.

## Error handling

The .NET Graph SDK surfaces proxy failures as standard `ServiceException` instances. Inspect `ServiceException.ResponseStatusCode` to branch on outcome.

- **401 Unauthorized** — the proxy JWT is expired, never issued, or the Proxy Client ID/Secret was rejected by `/proxy/token`. Request a new token through MSAL before retrying.
- **403 Forbidden** — a rule returned a `block` verdict. The response body names the matched rule. Do not retry automatically; the caller or the App Identity lacks permission for this endpoint.
- **502 Bad Gateway** — Microsoft Graph returned a non-2xx upstream. Treat it as a transient Graph failure; back off and retry with jitter.
- **429 Too Many Requests** — forwarded from Graph with `Retry-After` intact. Honour the header exactly as you would against direct Graph.

## Troubleshooting

The five failure modes below cover the common onboarding surprises when wiring a .NET app against GraphWarden for the first time.

### `MsalServiceException: AADSTS700016` from `AcquireTokenForClient`

MSAL is trying to authenticate against Azure AD, not the proxy. Confirm you passed `WithAuthority(new Uri($"{proxyBaseUrl}/proxy/token"), validateAuthority: false)`. The `validateAuthority: false` flag is required because the proxy is not an Azure AD authority and would fail MSAL's default authority validation.

### `HttpRequestException: The SSL connection could not be established`

The proxy is reachable by DNS but its TLS certificate is not trusted by the .NET runtime. In development, verify the certificate chain; in production, use a publicly trusted certificate or install the issuing CA in the machine trust store. Never disable certificate validation in production code.

### Graph SDK calls go to `graph.microsoft.com` instead of the proxy

The `HttpClient.BaseAddress` override was missed. The Graph SDK uses whatever `HttpClient` you pass to `GraphServiceClient`; if you rely on the default, the SDK composes URIs against `https://graph.microsoft.com`. Instantiate the `HttpClient` with `BaseAddress = new Uri(proxyBaseUrl)` and inject it through the `GraphServiceClient` constructor.

### All calls return `403 Forbidden` with the same rule id

A rule in the ruleset bound to the App Identity is matching aggressively. Review the rule's `match.endpoint_pattern` and `conditions` in App Admin, or use the What-If Simulator to replay a specific request and see which rule fires first.

### SDK version mismatch — methods missing or renamed

The sample targets `Microsoft.Graph` v5.x. v4.x uses `IGraphServiceUsersCollectionRequest` and a different request-builder shape; v5.x uses the `GetAsync` overload with a delegate configurator. Pin your project to v5.x to match the sample verbatim, or adapt the call sites to your installed major version.

<x-doc.last-reviewed date="2026-04-19" />



## Integrate GraphWarden with a Go application

# Integrate GraphWarden with a Go application

A Go application using `github.com/microsoftgraph/msgraph-sdk-go` (the official Microsoft Graph SDK for Go) and `github.com/Azure/azure-sdk-for-go/sdk/azidentity` can route every Graph call through GraphWarden by overriding two values: the token endpoint and the Graph base URL. The rest of the SDK surface — fluent request builders, pagination, `$select` and `$filter` — keeps working unchanged. This page shows a complete working sample.

<x-doc.status-badge status="supported">msgraph-sdk-go v1.x + azidentity v1.x</x-doc.status-badge>

<x-doc.prerequisites>

- Go 1.22 or later (the SDK requires 1.21+; 1.22 is the current stable baseline)
- `github.com/microsoftgraph/msgraph-sdk-go` v1.x
- `github.com/Azure/azure-sdk-for-go/sdk/azidentity` v1.x
- `github.com/microsoft/kiota-http-go` v1.x (pulled in transitively)
- A GraphWarden proxy URL reachable from your app
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this application

</x-doc.prerequisites>

<x-doc.ai-prompt title="Migrate a Go application with an AI assistant">
Migrate my existing Go application from direct Microsoft Graph API calls to use GraphWarden as a proxy.

My app currently uses azidentity.NewClientSecretCredential with https://graph.microsoft.com.

I need to:
1. Change the base URL to my GraphWarden proxy URL
2. Replace real Graph credentials with GraphWarden proxy credentials
3. Preserve all existing Graph SDK calls unchanged
4. Add error handling for GraphWarden-specific responses (401 invalid proxy credentials, 403 ruleset denial)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for:
- My GraphWarden proxy URL
- My proxy client_id and proxy client_secret
- Which Graph endpoints and scopes my app uses today
- Whether my binary runs in a container (affects TLS trust store setup)
</x-doc.ai-prompt>

## The two overrides

A direct-to-Graph Go app configures two things: an `azidentity.ClientSecretCredential` pointed at Azure AD, and a `msgraphsdk.GraphServiceClient` whose request adapter defaults to `https://graph.microsoft.com`. To route through GraphWarden you override both.

- **Token acquisition** — build `ClientSecretCredential` with `ClientOptions.Cloud` pointing at a custom `cloud.Configuration` whose `ActiveDirectoryAuthorityHost` is the proxy's token endpoint (`/proxy/token`) instead of Azure AD, and pass the Proxy Client ID and Proxy Client Secret in place of the Azure AD app credentials. The token you receive is a proxy JWT, not a Graph token; treat it as an opaque Bearer value.
- **Graph base URL** — after constructing the `GraphServiceClient`, call `client.RequestAdapter().SetBaseUrl(proxyBaseUrl)`. The SDK composes request URIs against that base, so `client.Users().Get(ctx, nil)` issues `GET {proxy-host}/v1.0/users` with the proxy JWT attached.

## Install

```bash
go get github.com/microsoftgraph/msgraph-sdk-go@latest
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity@latest
# Pin exact versions in go.mod for reproducibility (see Troubleshooting below).
```

## Minimal working sample

The program below acquires a proxy JWT and lists display names for the first page of users. Both overrides are named explicitly so the shape of the change is obvious. Production apps should pull the proxy URL and credentials from environment variables (see the next section) rather than hardcoding them.

```go
// main.go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore"
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/cloud"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
    "github.com/microsoftgraph/msgraph-sdk-go/users"
)

func main() {
    // 1. Configuration — in production, read these from os.Getenv.
    proxyBaseURL   := "https://proxy.example.com"                        // Issued when the proxy was deployed
    proxyClientID  := "00000000-0000-0000-0000-000000000000"             // Proxy Client ID from App Admin
    proxyClientSec := "REDACTED"                                         // Proxy Client Secret from App Admin

    // 2. Build a cloud.Configuration pointed at the proxy, NOT Azure AD.
    //    azidentity consults the configuration to decide where to POST the token request.
    proxyCloud := cloud.Configuration{
        ActiveDirectoryAuthorityHost: proxyBaseURL + "/proxy/token",     // GraphWarden token endpoint
        Services: map[cloud.ServiceName]cloud.ServiceConfiguration{},
    }

    credential, err := azidentity.NewClientSecretCredential(
        "proxy",                                                         // tenant ID — placeholder; proxy ignores it
        proxyClientID,
        proxyClientSec,
        &azidentity.ClientSecretCredentialOptions{
            ClientOptions: azcore.ClientOptions{Cloud: proxyCloud},
        },
    )
    if err != nil {
        log.Fatalf("credential build failed: %v", err)
    }

    // 3. Build the GraphServiceClient with the custom credential, then rebind
    //    the request adapter's base URL to the proxy.
    client, err := msgraphsdk.NewGraphServiceClientWithCredentials(
        credential,
        []string{"https://graph.microsoft.com/.default"},
    )
    if err != nil {
        log.Fatalf("graph client build failed: %v", err)
    }
    client.RequestAdapter.SetBaseUrl(proxyBaseURL)                       // GraphWarden base URL override

    // 4. Standard Graph SDK call — unchanged from a direct-Graph integration.
    selectCols := []string{"displayName"}
    topVal     := int32(10)
    config := &users.UsersRequestBuilderGetRequestConfiguration{
        QueryParameters: &users.UsersRequestBuilderGetQueryParameters{
            Select: selectCols,
            Top:    &topVal,
        },
    }

    page, err := client.Users().Get(context.Background(), config)
    if err != nil {
        log.Fatalf("users.Get failed: %v", err)
    }

    for _, user := range page.GetValue() {
        if user.GetDisplayName() != nil {
            fmt.Println(*user.GetDisplayName())
        }
    }
    _ = os.Stdout.Sync()
}
```

The important call is `client.Users().Get(ctx, config)`. It is identical to what you would write for a direct Graph integration — no request rewriting, no URL string building. The `SetBaseUrl` call is what points the SDK at the proxy.

<x-doc.callout type="info">
The proxy accepts the same Graph paths and query strings Microsoft Graph accepts, byte-for-byte. `$select`, `$filter`, `$expand`, pagination with `@odata.nextLink`, and batch requests all pass through unchanged. If a rule's Response Filter removes properties, the missing keys return `nil` from the generated getters — a user with `givenName` stripped will have `user.GetGivenName() == nil`.
</x-doc.callout>

## Configuration via environment

In production, read the proxy URL and credentials from environment variables. The conventional names below align with the proxy's own `__` double-underscore override pattern used elsewhere in the documentation.

```go
// graphwarden/client.go
package graphwarden

import (
    "fmt"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore"
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/cloud"
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
)

func requireEnv(name string) (string, error) {
    v := os.Getenv(name)
    if v == "" {
        return "", fmt.Errorf("%s is required", name)
    }
    return v, nil
}

func NewClient() (*msgraphsdk.GraphServiceClient, error) {
    proxyBaseURL, err := requireEnv("GRAPHWARDEN_PROXY_URL")
    if err != nil {
        return nil, err
    }
    clientID, err := requireEnv("GRAPHWARDEN_CLIENT_ID")
    if err != nil {
        return nil, err
    }
    clientSec, err := requireEnv("GRAPHWARDEN_CLIENT_SECRET")
    if err != nil {
        return nil, err
    }

    proxyCloud := cloud.Configuration{
        ActiveDirectoryAuthorityHost: proxyBaseURL + "/proxy/token",
        Services: map[cloud.ServiceName]cloud.ServiceConfiguration{},
    }

    cred, err := azidentity.NewClientSecretCredential("proxy", clientID, clientSec,
        &azidentity.ClientSecretCredentialOptions{
            ClientOptions: azcore.ClientOptions{Cloud: proxyCloud},
        })
    if err != nil {
        return nil, err
    }

    client, err := msgraphsdk.NewGraphServiceClientWithCredentials(
        cred, []string{"https://graph.microsoft.com/.default"},
    )
    if err != nil {
        return nil, err
    }
    client.RequestAdapter.SetBaseUrl(proxyBaseURL)
    return client, nil
}
```

`azidentity.ClientSecretCredential` caches the proxy JWT in memory and refreshes transparently before expiry. Construct one `GraphServiceClient` at program startup and reuse it — the SDK is safe to use from multiple goroutines.

## Error handling

The Graph SDK surfaces proxy failures as `*abstractions.ApiError` (or derived types) returned from each request. Inspect the `StatusCode` field to branch on outcome.

- **401 Unauthorized** — the proxy JWT is expired, never issued, or the Proxy Client ID/Secret was rejected by `/proxy/token`. `ClientSecretCredential` will request a fresh token on the next call automatically.
- **403 Forbidden** — a rule returned a `block` verdict. The response body names the matched rule. Do not retry automatically; the caller or the App Identity lacks permission for this endpoint.
- **502 Bad Gateway** — Microsoft Graph returned a non-2xx upstream. Treat it as a transient Graph failure; back off and retry with jitter.
- **429 Too Many Requests** — forwarded from Graph with `Retry-After` intact. Honour the header exactly as you would against direct Graph.

## Troubleshooting

The failure modes below cover the common onboarding surprises when wiring a Go app against GraphWarden for the first time.

### 401 from `/proxy/token` — `invalid_client`

The Proxy Client ID or Proxy Client Secret sent to `/proxy/token` does not match the hash stored for your App Identity. Confirm both values were copied from GraphWarden App Admin for the right App Identity. In container deployments, check whether `docker run -e` or the Kubernetes secret mount trimmed a trailing newline — Go's `os.Getenv` preserves newlines literally and they become part of the secret.

### 403 Forbidden on every Graph call

A rule in the ruleset bound to your App Identity is matching aggressively. The response body names the rule id. Review the rule's `match.endpoint_pattern` and `conditions` in App Admin, or use the What-If Simulator to replay a specific request and see which rule fires first.

### 502 Bad Gateway

Microsoft Graph returned a non-2xx upstream response and the proxy forwarded it as 502. Check Microsoft's Graph status page and the proxy's `/health` endpoint. Retry with exponential backoff and jitter; a transient Graph outage is the most common cause.

### 503 Service Unavailable on startup

The proxy could not read the real Graph credentials from Azure Key Vault. In on-prem deployments this usually means the Managed Identity is missing or the Key Vault access policy was not granted. The proxy operator, not your application, resolves this. Your app should retry with backoff — once the proxy recovers, token acquisition succeeds.

### `x509: certificate signed by unknown authority` in containers

The proxy's TLS certificate is not trusted by the minimal base image. Scratch, distroless, and Alpine images ship without a full CA bundle. In a `Dockerfile`, add `RUN apk --no-cache add ca-certificates` on Alpine or `COPY --from=alpine /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/` when building on scratch. For self-signed certificates in development, set the `SSL_CERT_FILE` environment variable to the CA bundle path. Never disable verification in production.

### Module-version pinning

Microsoft's Graph SDK pulls in a deep dependency graph (Kiota abstractions, HTTP client, serialisation). Upgrading one module without the others can produce compilation errors against generated types. Pin the major version set in `go.mod` and use `go mod tidy` to reconcile. When upgrading, bump `msgraph-sdk-go`, `kiota-abstractions-go`, `kiota-http-go`, and `kiota-serialization-*-go` together.

### SDK calls go to `graph.microsoft.com` instead of the proxy

The `SetBaseUrl` call on the request adapter was missed. Without it the SDK composes URIs against `https://graph.microsoft.com`. Re-run the setup and confirm `proxyBaseURL` has no trailing slash — `https://proxy.example.com` is correct.

<x-doc.last-reviewed date="2026-04-19" />



## Route an existing app through GraphWarden

# Route an existing app through GraphWarden

Switching to GraphWarden changes two things in your code: the Graph base URL and the credentials your app sends. The SDK calls, the scopes, and the response shapes stay identical. This page shows the before/after at the language-agnostic level; the language-specific guides show the exact code for each stack.

<x-doc.status-badge status="supported">Applies to every client language</x-doc.status-badge>

<x-doc.prerequisites>

- A working Microsoft Graph integration in any language (C#, PowerShell, Python, Node, Java, Go, ...)
- A GraphWarden proxy URL reachable from your app (issued when the proxy is deployed)
- Proxy credentials — a Proxy Client ID and Proxy Client Secret issued by the GraphWarden App Admin for the App Identity that represents your app

</x-doc.prerequisites>

<x-doc.ai-prompt title="Produce a migration plan with an AI assistant">
Analyze my existing Microsoft Graph API integration and produce a migration plan to route it through GraphWarden.

Walk through my code and identify:
1. Every location the Graph base URL is referenced
2. Every location Graph credentials are read from
3. Any hardcoded endpoints or scopes that a GraphWarden ruleset must permit

Then produce a before/after summary of the changes needed.

Reference documentation: https://graphwarden.com/llms.txt

Ask me for the path to my repository or paste the relevant code.
</x-doc.ai-prompt>

## What changes and what doesn't

Two values move from Azure AD + Microsoft Graph to GraphWarden. Everything downstream stays on the Graph side.

| Item | Before (direct to Graph) | After (via GraphWarden) |
|------|--------------------------|-------------------------|
| Base URL | `https://graph.microsoft.com` | `https://<proxy-host>` (issued by GraphWarden) |
| `client_id` sent with token request | Your Azure AD app's real `client_id` | The Proxy Client ID issued by GraphWarden |
| `client_secret` sent with token request | Your Azure AD app's real secret | The Proxy Client Secret issued by GraphWarden |
| Token endpoint | `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token` | `https://<proxy-host>/proxy/token` |
| Scopes | `https://graph.microsoft.com/.default` | Same — scopes are still declared against Graph |
| Graph paths | `/v1.0/users`, `/beta/groups`, ... | Identical — paths and query strings pass through byte-for-byte |
| SDK calls | `graphClient.Users.GetAsync(...)`, `Get-MgUser`, ... | Identical — the SDK talks to the proxy as though it were Graph |
| Response shapes | Microsoft Graph JSON | Identical, except where a rule's Response Filter transforms a property |

The real Azure AD `client_id` and `client_secret` move out of your app entirely. The proxy reads the real Graph credentials from your Azure Key Vault at runtime and uses them to call Graph on your behalf. Your app never sees them again.

## The before/after pattern

The sequence below is the same in every language. The names of the methods change per SDK; the shape of the call does not.

<x-doc.code-tabs :tabs="[
    [
        'name' => 'Before (direct)',
        'lang' => 'text',
        'code' => '1. POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' . PHP_EOL
            . '   body: grant_type=client_credentials' . PHP_EOL
            . '         client_id={real_client_id}' . PHP_EOL
            . '         client_secret={real_client_secret}' . PHP_EOL
            . '         scope=https://graph.microsoft.com/.default' . PHP_EOL
            . '   -> receives a Graph access_token' . PHP_EOL
            . PHP_EOL
            . '2. GET https://graph.microsoft.com/v1.0/users?$select=displayName' . PHP_EOL
            . '   Authorization: Bearer {graph_access_token}' . PHP_EOL
            . '   -> Microsoft Graph response JSON',
    ],
    [
        'name' => 'After (via GraphWarden)',
        'lang' => 'text',
        'code' => '1. POST https://<proxy-host>/proxy/token' . PHP_EOL
            . '   body: grant_type=client_credentials' . PHP_EOL
            . '         client_id={proxy_client_id}' . PHP_EOL
            . '         client_secret={proxy_client_secret}' . PHP_EOL
            . '   -> receives a proxy JWT (still a Bearer token)' . PHP_EOL
            . PHP_EOL
            . '2. GET https://<proxy-host>/v1.0/users?$select=displayName' . PHP_EOL
            . '   Authorization: Bearer {proxy_jwt}' . PHP_EOL
            . '   -> same Microsoft Graph response JSON, potentially filtered by a rule',
    ],
]" />

The client_credentials grant shape is preserved. The token the proxy returns is a proxy JWT, not a Graph token, and the proxy validates it on every subsequent request. From your app's perspective the token is still an opaque Bearer value — you pass it through the `Authorization` header the same way you always did.

## What your app still owns

GraphWarden covers application-to-Graph traffic only. The responsibilities below stay on your side and do not move to the proxy.

- **User sign-in.** If your app uses delegated flows (interactive sign-in, MFA, On-Behalf-Of), the user still authenticates to Azure AD directly. MSAL, passport-azure-ad, and equivalent libraries stay in your app.
- **Token caching.** Cache the proxy JWT the same way you cache a Graph token — one in-memory entry keyed on the token's expiry. Treat a 401 as an eviction signal and request a fresh token.
- **Retry and backoff.** The proxy forwards Graph's `429 Too Many Requests` responses with their `Retry-After` header intact. Your existing backoff logic keeps working.
- **Error handling.** 4xx from Graph comes back as 4xx from the proxy. Non-Graph failures (proxy auth, ruleset denial, upstream Graph unavailable) are reported with distinct status codes — see the troubleshooting table below.

## What the proxy now owns

Four responsibilities move into GraphWarden the moment you switch. Your app stops managing them.

- **Graph credentials.** The real Azure AD `client_id` and `client_secret` live in your Key Vault. The proxy reads them at runtime through a Managed Identity and acquires Graph tokens via MSAL. Your app does not need them in config or environment variables anymore.
- **Ruleset enforcement.** Every Graph request is evaluated against the ruleset bound to your App Identity. `allow`, `filter`, `block`, and `log_only` verdicts happen inside the proxy before or after the Graph call.
- **Audit trail.** Each request produces an audit event — method, path, caller, status, rule verdict. Bodies are not captured by default.
- **Retention.** Audit retention tiers (base / 90 days / 1 year / 7 years) are configured per Microsoft Tenant in GraphWarden App Admin; your app does not need to ship logs anywhere.

## Testing the switch

A brief checklist for verifying the migration before you cut production traffic over.

1. Call an endpoint you already know returns data against direct Graph — `/v1.0/users?$top=1` is a safe smoke test.
2. Repeat the call against the proxy URL with the Proxy Client ID and Proxy Client Secret. Expect the same response shape. A `filter` rule may remove properties; expected keys should still be present.
3. Open GraphWarden App Admin, find the audit log for your App Identity, and confirm the request is recorded with the matched rule and verdict.
4. Trigger a known-deny path (for example, a `DELETE` that a rule blocks) and confirm you receive `403 Forbidden` with a GraphWarden error body.

## Troubleshooting

The proxy returns distinct status codes for distinct failure modes. Use the table below to map a response to a cause.

### 401 Unauthorized on `/proxy/token`

The Proxy Client ID or Proxy Client Secret sent to `/proxy/token` does not match the hash stored for your App Identity. Confirm you copied both values from GraphWarden App Admin for the right App Identity and that nothing in your pipeline is trimming the secret.

### 403 Forbidden on a Graph call

A rule in the ruleset bound to your App Identity returned a `block` verdict for this request. The response body names the rule id. Review the ruleset in GraphWarden App Admin and check the match pattern, the conditions, and any IP or time gates. The What-If Simulator in App Admin lets you replay the request without touching production Graph.

### 502 Bad Gateway

Microsoft Graph returned a non-2xx upstream response and the proxy is forwarding it as 502. Check the proxy's health endpoint and Graph's status page. Retry with the same payload after a short backoff.

### Response differs from direct Graph

A `filter` rule is applying a Response Filter — either `allow_properties` (whitelist) or `strip_properties` (blacklist). Open the matched rule in App Admin and inspect the transform list. The audit log entry for the request names the rule and the transforms applied.

<x-doc.callout type="info">
If you need code rather than pseudo-code, the .NET guide shows a complete working sample that points a `GraphServiceClient` at the proxy base URL. The PowerShell quickstart covers the same pattern for `Connect-MgGraph`.
</x-doc.callout>

<x-doc.last-reviewed date="2026-04-19" />



## Integrate GraphWarden with a Node.js application

# Integrate GraphWarden with a Node.js application

A Node.js application using `@microsoft/microsoft-graph-client` (the Microsoft Graph JavaScript SDK) and `@azure/msal-node` can route every Graph call through GraphWarden by overriding two values: the token endpoint and the Graph base URL. The rest of the SDK surface — fluent builders, pagination, `$select` and `$filter` — keeps working unchanged. This page shows a complete working sample.

<x-doc.status-badge status="supported">@microsoft/microsoft-graph-client 3.x + @azure/msal-node 2.x</x-doc.status-badge>

<x-doc.prerequisites>

- Node.js 18 LTS or later (the sample targets Node 20; earlier LTS versions also work if `fetch` or `undici` is available)
- `@microsoft/microsoft-graph-client` v3.x from npm
- `@azure/msal-node` v2.x from npm
- A GraphWarden proxy URL reachable from your app
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this application

</x-doc.prerequisites>

<x-doc.ai-prompt title="Migrate a Node.js application with an AI assistant">
Migrate my existing Node.js application from direct Microsoft Graph API calls to use GraphWarden as a proxy.

My app currently uses @azure/msal-node with https://graph.microsoft.com.

I need to:
1. Change the base URL to my GraphWarden proxy URL
2. Replace real Graph credentials with GraphWarden proxy credentials
3. Preserve all existing Graph SDK calls unchanged
4. Add error handling for GraphWarden-specific responses (401 invalid proxy credentials, 403 ruleset denial)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for:
- My GraphWarden proxy URL
- My proxy client_id and proxy client_secret
- Which Graph endpoints and scopes my app uses today
- Whether I use ESM or CommonJS
</x-doc.ai-prompt>

## The two overrides

A direct-to-Graph Node app configures two things: a `ConfidentialClientApplication` pointed at Azure AD, and a `Client` instance from `@microsoft/microsoft-graph-client` that defaults to `https://graph.microsoft.com`. To route through GraphWarden you override both.

- **Token acquisition** — build `ConfidentialClientApplication` against the proxy's token endpoint (`/proxy/token`) instead of Azure AD, and pass the Proxy Client ID and Proxy Client Secret in place of the Azure AD app credentials. The token you receive is a proxy JWT, not a Graph token; treat it as an opaque Bearer value.
- **Graph base URL** — initialise the `Client` with a `baseUrl` option pointing at the proxy. The SDK composes request URIs against that base, so `client.api('/users').get()` issues `GET {proxy-host}/v1.0/users` with the proxy JWT attached.

## Install

```bash
npm install @microsoft/microsoft-graph-client@^3 @azure/msal-node@^2
# The Graph SDK uses the global `fetch` on Node 18+. No isomorphic-fetch polyfill is needed.
```

## Minimal working sample

The program below acquires a proxy JWT and lists display names for the first page of users. Both overrides are named explicitly so the shape of the change is obvious. Production apps should pull the proxy URL and credentials from environment variables (see the next section) rather than hardcoding them.

```typescript
// graphwarden-sample.ts
import { ConfidentialClientApplication } from '@azure/msal-node';
import { Client } from '@microsoft/microsoft-graph-client';

// 1. Configuration — in production, read these from process.env.
const proxyBaseUrl   = 'https://proxy.example.com';                  // Issued when the proxy was deployed
const tokenEndpoint  = `${proxyBaseUrl}/proxy/token`;                // GraphWarden-issued proxy JWT endpoint
const proxyClientId  = '00000000-0000-0000-0000-000000000000';       // Proxy Client ID from App Admin
const proxyClientSec = 'REDACTED';                                   // Proxy Client Secret from App Admin

// 2. Build an MSAL confidential client whose authority is the proxy, NOT Azure AD.
//    knownAuthorities tells MSAL to trust this host as a valid authority.
const cca = new ConfidentialClientApplication({
    auth: {
        clientId: proxyClientId,
        clientSecret: proxyClientSec,
        authority: tokenEndpoint,                                    // Proxy token endpoint
        knownAuthorities: [new URL(proxyBaseUrl).host],
    },
});

// 3. Acquire a proxy JWT via client_credentials.
const tokenResponse = await cca.acquireTokenByClientCredential({
    scopes: ['https://graph.microsoft.com/.default'],
});

if (!tokenResponse?.accessToken) {
    throw new Error('GraphWarden token acquisition failed.');
}

const proxyJwt = tokenResponse.accessToken;

// 4. Build a Graph Client pointed at the proxy. Every SDK call now hits {proxyBaseUrl}/{graph-path}.
const graphClient = Client.init({
    baseUrl: proxyBaseUrl,                                           // GraphWarden base URL override
    authProvider: (done) => done(null, proxyJwt),                    // Supplies the proxy JWT
});

// 5. Standard Graph SDK call — unchanged from a direct-Graph integration.
const page = await graphClient.api('/users').select('displayName').top(10).get();

for (const user of page.value) {
    console.log(user.displayName);
}
```

The important call is `graphClient.api('/users').get()`. It is identical to what you would write for a direct Graph integration — no request rewriting, no URL string building, no custom middleware. The `baseUrl` option is what points the SDK at the proxy.

<x-doc.callout type="info">
The proxy accepts the same Graph paths and query strings Microsoft Graph accepts, byte-for-byte. `$select`, `$filter`, `$expand`, pagination with `@odata.nextLink`, and batch requests all pass through unchanged. If a rule's Response Filter removes properties, the missing keys will not appear on the deserialised object — a user with `givenName` stripped will have `givenName === undefined`.
</x-doc.callout>

## Configuration via environment

In production, read the proxy URL and credentials from environment variables. The conventional names below align with the proxy's own `__` double-underscore override pattern used elsewhere in the documentation.

```typescript
// graphwarden-client.ts
import { ConfidentialClientApplication } from '@azure/msal-node';
import { Client } from '@microsoft/microsoft-graph-client';

function requireEnv(name: string): string {
    const value = process.env[name];
    if (!value) throw new Error(`${name} is required.`);
    return value;
}

const proxyBaseUrl   = requireEnv('GRAPHWARDEN_PROXY_URL');
const proxyClientId  = requireEnv('GRAPHWARDEN_CLIENT_ID');
const proxyClientSec = requireEnv('GRAPHWARDEN_CLIENT_SECRET');

// Keep a single MSAL instance — its in-memory token cache returns the cached
// proxy JWT until it is near expiry and silently refreshes afterwards.
const cca = new ConfidentialClientApplication({
    auth: {
        clientId: proxyClientId,
        clientSecret: proxyClientSec,
        authority: `${proxyBaseUrl}/proxy/token`,
        knownAuthorities: [new URL(proxyBaseUrl).host],
    },
});

export async function getGraphClient(): Promise<Client> {
    const result = await cca.acquireTokenByClientCredential({
        scopes: ['https://graph.microsoft.com/.default'],
    });
    if (!result?.accessToken) throw new Error('Proxy token acquisition failed.');

    return Client.init({
        baseUrl: proxyBaseUrl,
        authProvider: (done) => done(null, result.accessToken),
    });
}
```

MSAL Node's token cache is in-memory by default. Call `acquireTokenByClientCredential` on each request — MSAL returns the cached token when one is still valid and transparently refreshes before expiry. If you run multiple processes (a worker pool, a serverless runtime), each process keeps its own cache; the cost of an occasional refresh is low because proxy tokens last one hour.

## Error handling

The Graph SDK surfaces proxy failures as `GraphError` instances with a `statusCode` field. Inspect the code to branch on outcome.

- **401 Unauthorized** — the proxy JWT is expired, never issued, or the Proxy Client ID/Secret was rejected by `/proxy/token`. Request a new token through MSAL before retrying.
- **403 Forbidden** — a rule returned a `block` verdict. The response body names the matched rule. Do not retry automatically; the caller or the App Identity lacks permission for this endpoint.
- **502 Bad Gateway** — Microsoft Graph returned a non-2xx upstream. Treat it as a transient Graph failure; back off and retry with jitter.
- **429 Too Many Requests** — forwarded from Graph with `Retry-After` intact. Honour the header exactly as you would against direct Graph.

## Troubleshooting

The failure modes below cover the common onboarding surprises when wiring a Node.js app against GraphWarden for the first time.

### 401 from `/proxy/token` — `invalid_client`

The Proxy Client ID or Proxy Client Secret sent to `/proxy/token` does not match the hash stored for your App Identity. Confirm both values were copied from GraphWarden App Admin for the right App Identity. Watch for trailing whitespace introduced by shell redirection (`echo $SECRET > .env`) — a newline at the end of the secret string is a common culprit.

### 403 Forbidden on every Graph call

A rule in the ruleset bound to your App Identity is matching aggressively. The response body names the rule id. Review the rule's `match.endpoint_pattern` and `conditions` in App Admin, or use the What-If Simulator to replay a specific request and see which rule fires first.

### 502 Bad Gateway

Microsoft Graph returned a non-2xx upstream response and the proxy forwarded it as 502. Check Microsoft's Graph status page and the proxy's `/health` endpoint. Retry with exponential backoff and jitter; a transient Graph outage is the most common cause.

### 503 Service Unavailable on startup

The proxy could not read the real Graph credentials from Azure Key Vault. In on-prem deployments this usually means the Managed Identity is missing or the Key Vault access policy was not granted. The proxy operator, not your application, resolves this. Your app should retry with backoff — once the proxy recovers, token acquisition succeeds.

### `UNABLE_TO_VERIFY_LEAF_SIGNATURE` or TLS errors

The proxy is reachable by DNS but its TLS certificate is not trusted by the Node.js runtime. In development, verify the certificate chain. In production, use a publicly trusted certificate or install the issuing CA in the system trust store (Node honours the `NODE_EXTRA_CA_CERTS` environment variable as a last resort). Never disable certificate validation in production code.

### SDK calls go to `graph.microsoft.com` instead of the proxy

The `baseUrl` option was not passed to `Client.init`. Without it the SDK composes URIs against `https://graph.microsoft.com`. Double-check the init call and confirm `proxyBaseUrl` has no trailing slash — `https://proxy.example.com` is correct; `https://proxy.example.com/` can produce double slashes in composed URIs on some SDK versions.

<x-doc.last-reviewed date="2026-04-19" />



## Integrate GraphWarden with a PHP or Laravel application

# Integrate GraphWarden with a PHP or Laravel application

A PHP or Laravel application using `microsoft/microsoft-graph` (the official Microsoft Graph PHP SDK) can route every Graph call through GraphWarden by overriding two values: the token endpoint and the Graph base URL. The rest of the SDK surface — `GraphServiceClient` request builders, pagination, `$select` and `$filter` — keeps working unchanged. This page shows a plain-PHP working sample and a Laravel service-container binding.

<x-doc.status-badge status="supported">microsoft/microsoft-graph 2.x</x-doc.status-badge>

<x-doc.prerequisites>

- PHP 8.2 or later (the SDK requires 8.1+; 8.2 is the broadly-deployed LTS baseline)
- `microsoft/microsoft-graph` v2.x via Composer
- `guzzlehttp/guzzle` v7.x (pulled in transitively by the Graph SDK)
- A GraphWarden proxy URL reachable from your app
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this application
- For the Laravel binding section: Laravel 10.x or 11.x

</x-doc.prerequisites>

<x-doc.ai-prompt title="Migrate a PHP or Laravel application with an AI assistant">
Migrate my existing PHP or Laravel application from direct Microsoft Graph API calls to use GraphWarden as a proxy.

My app currently uses microsoft/microsoft-graph with https://graph.microsoft.com.

I need to:
1. Change the base URL to my GraphWarden proxy URL
2. Replace real Graph credentials with GraphWarden proxy credentials
3. Preserve all existing Graph SDK calls unchanged
4. Add error handling for GraphWarden-specific responses (401 invalid proxy credentials, 403 ruleset denial)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for:
- My Laravel version (or "plain PHP" if not using Laravel)
- My service container setup — whether I register Graph as a singleton or resolve it per-request
- Whether I use Horizon or queue workers (affects credential lifetime)
- My GraphWarden proxy URL
- My proxy client_id and proxy client_secret
- Which Graph endpoints and scopes my app uses today
</x-doc.ai-prompt>

## The two overrides

A direct-to-Graph PHP app configures two things: a client-credentials token request to Azure AD, and a `GraphServiceClient` that defaults to `https://graph.microsoft.com`. To route through GraphWarden you override both.

- **Token acquisition** — issue the `client_credentials` request against the proxy's token endpoint (`/proxy/token`) instead of Azure AD, and pass the Proxy Client ID and Proxy Client Secret in place of the Azure AD app credentials. The token you receive is a proxy JWT, not a Graph token; treat it as an opaque Bearer value.
- **Graph base URL** — when constructing the `GraphServiceClient`, pass a Guzzle HTTP client configured with the proxy as the base URI and call `setBaseUrl` on the request adapter. Every SDK call then issues `GET {proxy-host}/v1.0/users` with the proxy JWT attached.

## Install

```bash
composer require microsoft/microsoft-graph:^2 guzzlehttp/guzzle:^7
# guzzlehttp/guzzle is a transitive dependency — listed explicitly to anchor the version.
```

## Minimal working sample (plain PHP)

The program below acquires a proxy JWT and lists display names for the first page of users. Both overrides are named explicitly so the shape of the change is obvious. Production apps should pull the proxy URL and credentials from environment variables (see the Laravel section) rather than hardcoding them.

```php
<?php
// graphwarden-sample.php
declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use GuzzleHttp\Client as GuzzleClient;
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Kiota\Abstractions\Authentication\AccessTokenProvider;
use Microsoft\Kiota\Abstractions\Authentication\AllowedHostsValidator;
use Microsoft\Kiota\Abstractions\Authentication\BaseBearerTokenAuthenticationProvider;
use Microsoft\Kiota\Http\GuzzleRequestAdapter;

// 1. Configuration — in production, load these from $_ENV or a framework config layer.
$proxyBaseUrl   = 'https://proxy.example.com';                         // Issued when the proxy was deployed
$tokenEndpoint  = $proxyBaseUrl.'/proxy/token';                        // GraphWarden-issued proxy JWT endpoint
$proxyClientId  = '00000000-0000-0000-0000-000000000000';              // Proxy Client ID from App Admin
$proxyClientSec = 'REDACTED';                                          // Proxy Client Secret from App Admin

// 2. Acquire a proxy JWT via client_credentials against the proxy token endpoint.
$tokenClient = new GuzzleClient();
$tokenResp = $tokenClient->post($tokenEndpoint, [
    'form_params' => [
        'grant_type'    => 'client_credentials',
        'client_id'     => $proxyClientId,
        'client_secret' => $proxyClientSec,
        'scope'         => 'https://graph.microsoft.com/.default',
    ],
]);
$proxyJwt = json_decode((string) $tokenResp->getBody(), true)['access_token'];

// 3. A minimal token provider that returns the proxy JWT from the request above.
//    A production implementation refreshes the token before expiry.
$tokenProvider = new class($proxyJwt) implements AccessTokenProvider {
    public function __construct(private string $token) {}
    public function getAuthorizationTokenAsync(string $url, array $additionalAuthenticationContext = []): \Http\Promise\Promise {
        return \Http\Promise\FulfilledPromise::create($this->token);
    }
    public function getAllowedHostsValidator(): AllowedHostsValidator {
        return new AllowedHostsValidator();
    }
};

// 4. Build the Graph Client with a request adapter whose Guzzle base_uri is the proxy.
$authProvider = new BaseBearerTokenAuthenticationProvider($tokenProvider);
$guzzle = new GuzzleClient(['base_uri' => $proxyBaseUrl]);                // GraphWarden base URL override
$adapter = new GuzzleRequestAdapter($authProvider, null, null, $guzzle);
$adapter->setBaseUrl($proxyBaseUrl);
$graph = new GraphServiceClient($adapter);

// 5. Standard Graph SDK call — unchanged from a direct-Graph integration.
$page = $graph->users()->get(function ($config) {
    $config->queryParameters->select = ['displayName'];
    $config->queryParameters->top    = 10;
})->wait();

foreach ($page->getValue() ?? [] as $user) {
    echo $user->getDisplayName().PHP_EOL;
}
```

The important call is `$graph->users()->get(...)`. It is identical to what you would write for a direct Graph integration — no request rewriting, no URL string building. The Guzzle `base_uri` and `setBaseUrl` call are what point the SDK at the proxy.

<x-doc.callout type="info">
The proxy accepts the same Graph paths and query strings Microsoft Graph accepts, byte-for-byte. `$select`, `$filter`, `$expand`, pagination with `@odata.nextLink`, and batch requests all pass through unchanged. If a rule's Response Filter removes properties, the missing keys will return `null` from the generated getters — a `User` with `givenName` stripped will have `$user->getGivenName() === null`.
</x-doc.callout>

## Laravel integration

In a Laravel application, bind the `GraphServiceClient` as a singleton in a service provider. Reading the proxy URL and credentials from `.env` via Laravel's `config()` helper keeps secrets out of the codebase.

```php
<?php
// app/Providers/GraphWardenServiceProvider.php
declare(strict_types=1);

namespace App\Providers;

use GuzzleHttp\Client as GuzzleClient;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\ServiceProvider;
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Kiota\Abstractions\Authentication\AccessTokenProvider;
use Microsoft\Kiota\Abstractions\Authentication\AllowedHostsValidator;
use Microsoft\Kiota\Abstractions\Authentication\BaseBearerTokenAuthenticationProvider;
use Microsoft\Kiota\Http\GuzzleRequestAdapter;

class GraphWardenServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(GraphServiceClient::class, function () {
            $proxyBaseUrl   = config('services.graphwarden.url');        // GRAPHWARDEN_PROXY_URL
            $proxyClientId  = config('services.graphwarden.client_id');  // GRAPHWARDEN_CLIENT_ID
            $proxyClientSec = config('services.graphwarden.secret');     // GRAPHWARDEN_CLIENT_SECRET

            // Cache the proxy JWT for 55 minutes (tokens last 1 hour). Cached
            // across queued jobs and web requests within one Laravel process.
            $proxyJwt = Cache::remember('graphwarden:token', 3300, function () use (
                $proxyBaseUrl, $proxyClientId, $proxyClientSec
            ) {
                $resp = (new GuzzleClient())->post($proxyBaseUrl.'/proxy/token', [
                    'form_params' => [
                        'grant_type'    => 'client_credentials',
                        'client_id'     => $proxyClientId,
                        'client_secret' => $proxyClientSec,
                        'scope'         => 'https://graph.microsoft.com/.default',
                    ],
                ]);
                return json_decode((string) $resp->getBody(), true)['access_token'];
            });

            $tokenProvider = new class($proxyJwt) implements AccessTokenProvider {
                public function __construct(private string $token) {}
                public function getAuthorizationTokenAsync(string $url, array $ctx = []): \Http\Promise\Promise {
                    return \Http\Promise\FulfilledPromise::create($this->token);
                }
                public function getAllowedHostsValidator(): AllowedHostsValidator {
                    return new AllowedHostsValidator();
                }
            };

            $auth = new BaseBearerTokenAuthenticationProvider($tokenProvider);
            $guzzle = new GuzzleClient(['base_uri' => $proxyBaseUrl]);
            $adapter = new GuzzleRequestAdapter($auth, null, null, $guzzle);
            $adapter->setBaseUrl($proxyBaseUrl);

            return new GraphServiceClient($adapter);
        });
    }
}
```

Add matching keys to `config/services.php`:

```php
// config/services.php
return [
    // ... existing entries
    'graphwarden' => [
        'url'       => env('GRAPHWARDEN_PROXY_URL'),
        'client_id' => env('GRAPHWARDEN_CLIENT_ID'),
        'secret'    => env('GRAPHWARDEN_CLIENT_SECRET'),
    ],
];
```

Register the provider in `bootstrap/providers.php` (Laravel 11) or `config/app.php` (Laravel 10). Controllers and jobs then type-hint `GraphServiceClient` in their constructor and Laravel resolves the singleton.

### Horizon and long-lived workers

If your app uses Laravel Horizon or a long-running queue worker, the singleton binding means one `GraphServiceClient` instance lives for the worker's lifetime. The `Cache::remember` wrapper above keeps repeated token fetches off the hot path; the first job in a process window pays the `/proxy/token` cost and the rest reuse the cached JWT.

## Error handling

The PHP Graph SDK surfaces proxy failures as `Microsoft\Kiota\Abstractions\ApiException` instances with an HTTP status code. Catch and branch on outcome.

- **401 Unauthorized** — the proxy JWT is expired, never issued, or the Proxy Client ID/Secret was rejected by `/proxy/token`. Invalidate your cached token and request a fresh one.
- **403 Forbidden** — a rule returned a `block` verdict. The response body names the matched rule. Do not retry automatically; the caller or the App Identity lacks permission for this endpoint.
- **502 Bad Gateway** — Microsoft Graph returned a non-2xx upstream. Treat it as a transient Graph failure; back off and retry with jitter.
- **429 Too Many Requests** — forwarded from Graph with `Retry-After` intact. Honour the header exactly as you would against direct Graph.

## Troubleshooting

The failure modes below cover the common onboarding surprises when wiring a PHP or Laravel app against GraphWarden for the first time.

### 401 from `/proxy/token` — `invalid_client`

The Proxy Client ID or Proxy Client Secret sent to `/proxy/token` does not match the hash stored for your App Identity. Confirm both values were copied from GraphWarden App Admin for the right App Identity. A common Laravel cause is `.env` caching: if you ran `php artisan config:cache` before updating the secret, run `php artisan config:clear` or re-run `config:cache` so the new value is picked up.

### 403 Forbidden on every Graph call

A rule in the ruleset bound to your App Identity is matching aggressively. The response body names the rule id. Review the rule's `match.endpoint_pattern` and `conditions` in App Admin, or use the What-If Simulator to replay a specific request and see which rule fires first.

### 502 Bad Gateway

Microsoft Graph returned a non-2xx upstream response and the proxy forwarded it as 502. Check Microsoft's Graph status page and the proxy's `/health` endpoint. Retry with exponential backoff and jitter; a transient Graph outage is the most common cause.

### 503 Service Unavailable on startup

The proxy could not read the real Graph credentials from Azure Key Vault. In on-prem deployments this usually means the Managed Identity is missing or the Key Vault access policy was not granted. The proxy operator, not your application, resolves this. Your app should retry with backoff — once the proxy recovers, token acquisition succeeds.

### `cURL error 60: SSL certificate problem`

Guzzle uses libcurl which on older Windows PHP builds (pre PHP 8.1, WAMP, XAMPP) ships without a bundled CA store. Download Mozilla's `cacert.pem`, place it somewhere readable, and set `curl.cainfo` and `openssl.cafile` in `php.ini` to its absolute path. On modern Linux distributions and Homebrew PHP this works out of the box.

### Composer autoload collisions with older Graph SDKs

The PHP Graph SDK went through a major rewrite between v1.x (legacy) and v2.x (Kiota-based). Mixing both in one `composer.json` produces fatal autoload errors because the PSR-4 roots overlap. Remove any `microsoft/microsoft-graph-beta` or `microsoft/microsoft-graph:^1` entries, run `composer remove` followed by `composer require microsoft/microsoft-graph:^2`, then `composer dump-autoload`.

### SDK calls go to `graph.microsoft.com` instead of the proxy

Both the Guzzle `base_uri` and `GuzzleRequestAdapter::setBaseUrl` must be set. If only the Guzzle `base_uri` is set, the adapter still composes absolute URIs against `https://graph.microsoft.com`. Set both — the sample above does this.

<x-doc.last-reviewed date="2026-04-19" />



## Integrate GraphWarden with a Python application

# Integrate GraphWarden with a Python application

A Python application using `msgraph-sdk` (the modern Microsoft Graph SDK for Python) and `azure-identity` can route every Graph call through GraphWarden by overriding two values: the token endpoint and the Graph base URL. The rest of the SDK surface — `GraphServiceClient` request builders, pagination, `$select` and `$filter` — keeps working unchanged. This page shows a complete working sample.

<x-doc.status-badge status="supported">msgraph-sdk 1.x + azure-identity 1.x</x-doc.status-badge>

<x-doc.prerequisites>

- Python 3.10 or later (the sample targets 3.11; earlier 3.x versions also work)
- `msgraph-sdk` v1.x from PyPI (the modern `GraphServiceClient`, not the legacy `msgraph-core`)
- `azure-identity` v1.x from PyPI
- A GraphWarden proxy URL reachable from your app
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this application

</x-doc.prerequisites>

<x-doc.ai-prompt title="Migrate a Python application with an AI assistant">
Migrate my existing Python application from direct Microsoft Graph API calls to use GraphWarden as a proxy.

My app currently uses azure-identity.ClientSecretCredential with https://graph.microsoft.com.

I need to:
1. Change the base URL to my GraphWarden proxy URL
2. Replace real Graph credentials with GraphWarden proxy credentials
3. Preserve all existing Graph SDK calls unchanged
4. Add error handling for GraphWarden-specific responses (401 invalid proxy credentials, 403 ruleset denial)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for:
- My GraphWarden proxy URL
- My proxy client_id and proxy client_secret
- Which Graph endpoints and scopes my app uses today
- Whether my app is synchronous or async (asyncio)
</x-doc.ai-prompt>

## The two overrides

A direct-to-Graph Python app configures two things: a `ClientSecretCredential` pointed at Azure AD, and a `GraphServiceClient` whose underlying request adapter defaults to `https://graph.microsoft.com`. To route through GraphWarden you override both.

- **Token acquisition** — point `ClientSecretCredential` at the proxy's token endpoint (`/proxy/token`) by supplying `authority=proxyBaseUrl` and pass the Proxy Client ID and Proxy Client Secret in place of the Azure AD app credentials. The token you receive is a proxy JWT, not a Graph token; treat it as an opaque Bearer value.
- **Graph base URL** — after constructing the `GraphServiceClient`, set `client.request_adapter.base_url` to the proxy URL. The SDK composes request URIs against that base, so `await client.users.get()` issues `GET {proxy-host}/v1.0/users` with the proxy JWT attached.

## Install

```bash
pip install msgraph-sdk azure-identity
# msgraph-sdk depends on kiota-abstractions and httpx; pip resolves these transitively.
```

## Minimal working sample

The program below acquires a proxy JWT and lists display names for the first page of users. Both overrides are named explicitly so the shape of the change is obvious. Production apps should pull the proxy URL and credentials from environment variables (see the next section) rather than hardcoding them.

```python
# graphwarden_sample.py
import asyncio
import os
from azure.identity.aio import ClientSecretCredential
from msgraph import GraphServiceClient

# 1. Configuration — in production, load these from environment variables.
proxy_base_url   = "https://proxy.example.com"                       # Issued when the proxy was deployed
proxy_client_id  = "00000000-0000-0000-0000-000000000000"            # Proxy Client ID from App Admin
proxy_client_sec = "REDACTED"                                        # Proxy Client Secret from App Admin


async def main() -> None:
    # 2. azure-identity credential pointed at the proxy token endpoint, NOT Azure AD.
    #    The `authority` kwarg overrides the default login.microsoftonline.com host.
    credential = ClientSecretCredential(
        tenant_id="proxy",                                           # Placeholder — the proxy ignores it
        client_id=proxy_client_id,
        client_secret=proxy_client_sec,
        authority=proxy_base_url,                                    # GraphWarden-issued proxy host
    )

    # 3. Build the GraphServiceClient, then rebind its request adapter base URL to the proxy.
    #    The credential supplies the Bearer token on every request; setting base_url points the
    #    SDK at the proxy for all Graph path composition.
    client = GraphServiceClient(
        credentials=credential,
        scopes=["https://graph.microsoft.com/.default"],
    )
    client.request_adapter.base_url = proxy_base_url                 # GraphWarden base URL override

    # 4. Standard Graph SDK call — unchanged from a direct-Graph integration.
    from msgraph.generated.users.users_request_builder import UsersRequestBuilder
    query = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
        select=["displayName"], top=10,
    )
    config = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
        query_parameters=query,
    )
    page = await client.users.get(request_configuration=config)

    for user in (page.value or []):
        print(user.display_name)

    await credential.close()


if __name__ == "__main__":
    asyncio.run(main())
```

The important call is `await client.users.get(...)`. It is identical to what you would write for a direct Graph integration — no request rewriting, no URL string building, no custom adapter. The `base_url` rebind is what points the SDK at the proxy.

<x-doc.callout type="info">
The proxy accepts the same Graph paths and query strings Microsoft Graph accepts, byte-for-byte. `$select`, `$filter`, `$expand`, pagination with `@odata.nextLink`, and batch requests all pass through unchanged. If a rule's Response Filter removes properties, the missing keys will be `None` on the deserialised object — a `User` with `given_name` stripped will have `user.given_name is None`.
</x-doc.callout>

## Configuration via environment

In production, read the proxy URL and credentials from environment variables. The conventional names below align with the proxy's own `__` double-underscore override pattern used elsewhere in the documentation.

```python
# graphwarden_client.py
import os
from azure.identity.aio import ClientSecretCredential
from msgraph import GraphServiceClient


def _require_env(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise RuntimeError(f"{name} is required.")
    return value


def build_graph_client() -> GraphServiceClient:
    proxy_base_url   = _require_env("GRAPHWARDEN_PROXY_URL")
    proxy_client_id  = _require_env("GRAPHWARDEN_CLIENT_ID")
    proxy_client_sec = _require_env("GRAPHWARDEN_CLIENT_SECRET")

    credential = ClientSecretCredential(
        tenant_id="proxy",
        client_id=proxy_client_id,
        client_secret=proxy_client_sec,
        authority=proxy_base_url,
    )

    client = GraphServiceClient(
        credentials=credential,
        scopes=["https://graph.microsoft.com/.default"],
    )
    client.request_adapter.base_url = proxy_base_url
    return client
```

`ClientSecretCredential` caches the proxy JWT until it nears expiry and transparently refreshes it on the next call. Keep a single credential instance for the lifetime of your application to take advantage of the cache. If you run multiple processes (a gunicorn worker pool, a Celery worker fleet), each process keeps its own cache; the cost of an occasional refresh is low because proxy tokens last one hour.

## Sync vs async

The sample uses `azure.identity.aio` and the async `GraphServiceClient`. If your application is synchronous, import `ClientSecretCredential` from `azure.identity` (non-aio) and wrap Graph calls with `asyncio.run(...)` at the entry point — the SDK itself remains async, so a small sync shim is unavoidable. New codebases should prefer async; the Graph SDK is async-first and every request builder returns an awaitable.

## Error handling

The Graph SDK surfaces proxy failures as `APIError` instances (`kiota_abstractions.api_error.APIError`) with a `response_status_code` attribute. Catch and branch on outcome.

- **401 Unauthorized** — the proxy JWT is expired, never issued, or the Proxy Client ID/Secret was rejected by `/proxy/token`. `ClientSecretCredential` will request a fresh token on the next call automatically.
- **403 Forbidden** — a rule returned a `block` verdict. The response body names the matched rule. Do not retry automatically; the caller or the App Identity lacks permission for this endpoint.
- **502 Bad Gateway** — Microsoft Graph returned a non-2xx upstream. Treat it as a transient Graph failure; back off and retry with jitter.
- **429 Too Many Requests** — forwarded from Graph with `Retry-After` intact. Honour the header exactly as you would against direct Graph.

## Troubleshooting

The failure modes below cover the common onboarding surprises when wiring a Python app against GraphWarden for the first time.

### 401 from `/proxy/token` — `invalid_client`

The Proxy Client ID or Proxy Client Secret sent to `/proxy/token` does not match the hash stored for your App Identity. Confirm both values were copied from GraphWarden App Admin for the right App Identity. A common cause in Python is loading `.env` files with `python-dotenv` where the secret contains a `$` or `#` character and quoting was missed — wrap secrets in single quotes inside `.env` to keep interpolation off.

### 403 Forbidden on every Graph call

A rule in the ruleset bound to your App Identity is matching aggressively. The response body names the rule id. Review the rule's `match.endpoint_pattern` and `conditions` in App Admin, or use the What-If Simulator to replay a specific request and see which rule fires first.

### 502 Bad Gateway

Microsoft Graph returned a non-2xx upstream response and the proxy forwarded it as 502. Check Microsoft's Graph status page and the proxy's `/health` endpoint. Retry with exponential backoff and jitter; a transient Graph outage is the most common cause.

### 503 Service Unavailable on startup

The proxy could not read the real Graph credentials from Azure Key Vault. In on-prem deployments this usually means the Managed Identity is missing or the Key Vault access policy was not granted. The proxy operator, not your application, resolves this. Your app should retry with backoff — once the proxy recovers, token acquisition succeeds.

### `httpx.ConnectError` or SSL verification errors

The proxy is reachable by DNS but its TLS certificate is not trusted. The Graph SDK uses `httpx` under the hood, which in turn reads the `SSL_CERT_FILE` environment variable and the system CA bundle. In production, use a publicly trusted certificate or install the issuing CA in the system trust store. Never disable verification in production code.

### `aiohttp` vs `httpx` considerations

The modern `msgraph-sdk` uses `httpx` as its HTTP transport — there is no `aiohttp` dependency. Older tutorials and the legacy `msgraph-core` package referenced `aiohttp`; if you see import errors mentioning `aiohttp`, you are on the deprecated path. Pin `msgraph-sdk >= 1.0.0` to stay on the supported stack.

### SDK calls go to `graph.microsoft.com` instead of the proxy

The `client.request_adapter.base_url` rebind was missed. Without it the SDK composes URIs against `https://graph.microsoft.com`. Re-run the setup and confirm `proxy_base_url` has no trailing slash — `https://proxy.example.com` is correct.

<x-doc.last-reviewed date="2026-04-19" />



## What GraphWarden does and when to use it

# 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.

<x-doc.status-badge status="supported">Phase-1 documentation baseline</x-doc.status-badge>

<x-doc.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.

</x-doc.prerequisites>

<x-doc.callout type="info">
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.
</x-doc.callout>

## 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.

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden-compatible partners

# GraphWarden-compatible partners

This page lists third-party products whose vendors have published a GraphWarden compatibility statement. Inclusion here reflects a vendor-published declaration, not a GraphWarden-issued certification. To appear on this page, complete the [compatibility statement template](./compatibility-statement) and contact us.

<x-doc.status-badge status="supported">Content-as-a-service — curated from vendor-published declarations</x-doc.status-badge>

<x-doc.prerequisites>

- Your product supports GraphWarden per the [compatibility guide](./compatibility-guide)
- Your product documentation includes a published compatibility statement

</x-doc.prerequisites>

<x-doc.callout type="note">
This page is content-as-a-service — partner entries are curated by GraphWarden based on vendor-published declarations. It is not a certification program.
</x-doc.callout>

<x-doc.ai-prompt title="Request inclusion in the GraphWarden partners list">
Help me publish a GraphWarden compatibility statement for my product and request inclusion in the partners list.

My product calls Microsoft Graph and reads the Graph base URL and credentials from configuration. I have reviewed the compatibility guide at https://graphwarden.com/docs/isv/compatibility-guide and run the eight-step test checklist.

I need:
1. Review of my draft compatibility statement against the template at https://graphwarden.com/docs/isv/compatibility-statement
2. The email address or form to send the URL of my published statement for partner-list review
3. An expected timeline between submission and link-check completion

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my product name, my published statement URL, and the Graph endpoints my product uses.
</x-doc.ai-prompt>

## How this list is maintained

The partner list reflects vendor-published declarations. The flow below describes how an entry lands on the table and how it stays there.

1. A vendor publishes a GraphWarden compatibility statement on their own documentation site, using the [compatibility statement template](./compatibility-statement) as the base.
2. The vendor contacts GraphWarden with the URL of the published statement, the product name, and a short description.
3. GraphWarden runs a link check against the submitted URL. If the page resolves (HTTP 200) and contains the four required sections from the template (integration overview, supported Graph endpoints, known limitations, customer responsibilities), the entry is added in the next docs release.
4. The partner table below is the canonical list. Entries are added in alphabetical order by product name.

GraphWarden does not test the partner's product. The partner self-declares compatibility by publishing the statement; the curation on this page is limited to confirming the statement exists and matches the template's scope.

## Listed partners

| Partner | Product | Compatibility statement | Last verified |
|---------|---------|-------------------------|---------------|
| No partners listed yet. [Contact us](./compatibility-statement) to be added. | — | — | — |

The table above is a placeholder. When vendors submit their statements, entries replace this row in alphabetical order by product name.

## How to appear on this list

The four-step process below takes a vendor from first reading the compatibility guide to landing on this page.

1. **Read the [compatibility guide](./compatibility-guide).** Confirm your product reads the Graph base URL and credentials from configuration. Run the eight-step test checklist against a GraphWarden test instance.
2. **Publish your compatibility statement.** Copy the [template](./compatibility-statement), replace the `{curly brace}` markers with your product specifics, and publish the result under your own documentation site. A title like "{Your product} compatibility with GraphWarden" works well for discoverability.
3. **Contact GraphWarden with the URL.** Email the URL of your published statement, your product name, and your primary support contact to the address listed at the bottom of this page.
4. **Link-check and addition.** GraphWarden confirms the URL resolves and that the statement matches the template's four sections. Once confirmed, the entry lands in the next docs release. You receive a confirmation email with the published entry.

The entire flow is documentation work on the vendor side plus a link check on the GraphWarden side. There is no contract, no fee, and no technical integration with GraphWarden infrastructure — your product never talks to GraphWarden directly.

## Removal policy

Entries remain on the list as long as the published statement resolves at the URL the vendor submitted. The curation process applies two removal rules.

- **Statement URL returns 404 for more than 30 days.** GraphWarden runs a periodic link check against every listed URL. A URL that returns 404 on three consecutive weekly checks is flagged; the vendor receives an email at the contact on file. If the URL does not resolve within 30 days of the first failed check, the entry is removed from the table.
- **Vendor requests removal.** A vendor can request removal at any time by contacting GraphWarden from the address on file. Removals are processed in the next docs release.

A vendor whose entry was removed can resubmit once the statement URL resolves again — the rejoining flow is the same as the initial submission.

## Troubleshooting

The entries below cover the questions vendors ask most often during the submission flow.

### My statement submission was rejected

The most common rejection reason is warranty language that GraphWarden cannot endorse on the partner's behalf. Phrasing that reads as a blanket commitment or a forward-looking guarantee lands as "GraphWarden endorses this product indefinitely" — which is not a commitment GraphWarden can make for a third-party vendor. Rework the wording to describe what your product does ("{Product} reads the Graph base URL from configuration and routes calls through the configured endpoint") rather than what it guarantees. The [template](./compatibility-statement) models the acceptable tone.

### My statement URL changed

Contact GraphWarden with both the old URL and the new URL from the address on file. The entry updates in the next docs release; there is no interruption to your listing as long as the new URL resolves when the change is submitted.

### I want my entry removed

Contact GraphWarden from the address on file and request removal. Removals are processed in the next docs release. If the address on file has changed, include the entry name and a proof-of-ownership reference (for example, a mention on the vendor's primary support page linking to this list).

### My product version changed in ways that affect compatibility

The published compatibility statement should reflect the current supported version range. Update the `{Minimum version}` section in your published statement and — if the change is material — notify GraphWarden so the `Last verified` column reflects the re-verification date. Minor version bumps without a compatibility change do not require a re-verification.

<x-doc.last-reviewed date="2026-04-19" />



## Add GraphWarden compatibility to your product

# Add GraphWarden compatibility to your product

GraphWarden-compatible means your product reads the Microsoft Graph base URL and credentials from customer configuration instead of hardcoding them. This page walks through the technical integration, edge cases (token caching, rate limits, ruleset denial errors), and a compatibility test checklist.

<x-doc.status-badge status="supported">Applies to every language and Graph SDK</x-doc.status-badge>

<x-doc.prerequisites>

- A product that calls Microsoft Graph in any language or SDK
- The ability to externalize the Graph endpoint and credentials as configuration (environment variables, a config file, or a database-backed setting)
- A test GraphWarden instance reachable from your development environment for compatibility testing

</x-doc.prerequisites>

<x-doc.ai-prompt title="Plan GraphWarden compatibility with an AI assistant">
Add GraphWarden compatibility to my SaaS product that uses Microsoft Graph.

Compatibility means my product reads the Graph base URL and credentials from customer configuration instead of hardcoding https://graph.microsoft.com.

I need:
1. Identification of every Graph reference in my codebase that needs to be externalized
2. A configuration surface change (env vars, admin UI settings, or similar)
3. A compatibility statement template for my customer-facing documentation

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my product's primary language/framework and paste the Graph initialization code.
</x-doc.ai-prompt>

## The two config values

Two values move from product-level constants to customer-supplied configuration. Everything else in your product stays the same.

| Value | Direct-to-Graph | Through GraphWarden |
|-------|-----------------|----------------------|
| Microsoft Graph base URL | `https://graph.microsoft.com` (the Microsoft default) | The customer's proxy URL, for example `https://proxy.customer.internal` |
| Token endpoint | `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token` | `https://{proxy-host}/proxy/token` (the proxy issues its own JWT) |
| Client ID sent to the token endpoint | Your customer's Azure AD application `client_id` | The Proxy Client ID issued by the customer's GraphWarden App Admin |
| Client Secret sent to the token endpoint | Your customer's Azure AD application secret | The Proxy Client Secret issued by the customer's GraphWarden App Admin |
| Scopes | `https://graph.microsoft.com/.default` | Identical — scopes continue to be declared against Graph |
| Request paths | `/v1.0/users`, `/beta/groups`, etc. | Identical — the proxy is path-transparent |

The practical shape: your product's configuration surface adds one new Graph base URL setting (call it `GRAPH_BASE_URL` or whatever matches your product's conventions), and your existing credential inputs accept the customer-supplied Proxy Client ID and Secret instead of Azure AD credentials. No SDK change. No protocol change.

## Integration steps

The four steps below are the complete engineering work required to declare compatibility.

1. **Externalize the Graph base URL.** Replace every hardcoded reference to `https://graph.microsoft.com` with a configuration read. If your product uses a Microsoft-published Graph SDK, this is a one-line change — set the `BaseAddress` of the `HttpClient` passed to `GraphServiceClient` (.NET), or pass a `baseUrl` option (`@microsoft/microsoft-graph-client` on Node). The default value for the setting remains `https://graph.microsoft.com` so customers who do not deploy GraphWarden continue to work without changing anything.
2. **Externalize the credentials.** If your product hardcodes the Azure AD token endpoint or treats it as an implementation detail, expose it as configuration. Accept the proxy token endpoint in the same setting. Accept the Proxy Client ID and Proxy Client Secret through the same credential inputs your product already uses for Azure AD client credentials.
3. **Document these settings for your customers.** In your product's deployment or configuration documentation, describe the two settings and note that they accept either Microsoft defaults (direct to Graph) or customer-supplied values (routed through GraphWarden or any equivalent governance proxy). The compatibility statement template gives you the wording your enterprise customers expect.
4. **Test the integration.** Run the compatibility test checklist below against a test GraphWarden instance. Once the checklist passes, publish your compatibility statement.

A .NET example makes the shape concrete. The snippet below shows the two overrides — everything else is the same code you already have.

<x-doc.code-block lang="csharp">
using System.Net.Http.Headers;
using Microsoft.Graph;
using Microsoft.Identity.Client;

// Read from your existing configuration surface.
string graphBaseUrl     = config["GRAPH_BASE_URL"] ?? "https://graph.microsoft.com";
string tokenEndpoint    = config["GRAPH_TOKEN_ENDPOINT"]
    ?? "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token";
string graphClientId    = config["GRAPH_CLIENT_ID"];
string graphClientSecret= config["GRAPH_CLIENT_SECRET"];

// Direct-to-Graph: tokenEndpoint points at Azure AD, graphBaseUrl is the Microsoft default.
// Through GraphWarden: tokenEndpoint points at the proxy (/proxy/token), graphBaseUrl is
// the proxy host, and the client_id/secret are the proxy pair.
var cca = ConfidentialClientApplicationBuilder
    .Create(graphClientId)
    .WithClientSecret(graphClientSecret)
    .WithAuthority(new Uri(tokenEndpoint), validateAuthority: false)
    .Build();

var token = (await cca
    .AcquireTokenForClient(new[] { "https://graph.microsoft.com/.default" })
    .ExecuteAsync()).AccessToken;

var http = new HttpClient { BaseAddress = new Uri(graphBaseUrl) };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var graphClient = new GraphServiceClient(http);
// graphClient.Users.GetAsync(...) now hits {graphBaseUrl}/v1.0/users with the issued token.
</x-doc.code-block>

## Edge case: token caching

Tokens issued by the proxy have the same one-hour lifetime as tokens issued by Azure AD. Your existing token-caching strategy keeps working.

If your product caches the token by expiry and evicts on 401, the behaviour against the proxy is identical: acquire once, reuse until expiry, re-acquire when expiry passes or the proxy returns 401. MSAL's built-in cache on `ConfidentialClientApplication` works the same way against the proxy's token endpoint as against Azure AD. The proxy returns standard OAuth2 responses from `/proxy/token`: a JSON body with `access_token`, `token_type: Bearer`, and `expires_in`.

Do not cache tokens across product upgrades or restarts unless you already do so for Azure AD tokens. The proxy does not introduce new cache-invalidation concerns.

## Edge case: rate limits

<x-doc.callout type="warning">
The proxy may enforce stricter rate limits than Microsoft Graph. Treat 429 responses from the proxy with the same exponential-backoff strategy your product already uses for Graph, and honour the `Retry-After` header exactly as you would against direct Graph.
</x-doc.callout>

A GraphWarden deployment can throttle Graph traffic per App Identity or per tenant before a request ever reaches Microsoft. This protects the customer's Graph quota and enforces their internal usage budgets. From your product's perspective, a 429 from the proxy is indistinguishable from a 429 from Graph — status code, JSON body shape, and `Retry-After` header all follow the Microsoft pattern.

Rate-limit thresholds are customer-configurable. A customer running a tight budget may set lower thresholds than Microsoft's defaults; a customer running a generous budget may see no proxy-imposed limit at all. Your product should not encode assumptions about the threshold; the correct behaviour is to respect the `Retry-After` value and retry after the indicated interval.

## Edge case: ruleset denial errors

When a customer's ruleset blocks a specific Graph call, the proxy returns HTTP 403 with a JSON body naming the matched rule. The response shape is proxy-specific but follows the Microsoft Graph error envelope closely: an `error` object with `code` and `message` fields, plus an `innerError.ruleId` that identifies the rule in the customer's GraphWarden App Admin.

Your product should surface this gracefully. A helpful error message for the end user looks something like:

> "This action was blocked by your organization's Microsoft Graph policy. Contact your GraphWarden administrator and reference rule `{ruleId}`."

Do NOT treat a 403 from the proxy as a bug in your product. The customer's security policy is the authoritative source for what Graph calls are permitted; a 403 means the administrator has not granted permission for this endpoint or this combination of caller plus endpoint. Log the `ruleId` at your product's standard error level and return a user-facing message that names the administrator, not your support team.

Ruleset denials can also surface as response filters — the proxy returns 200 with a partial body where specific properties have been stripped. If your product depends on a property and receives `null` unexpectedly, the matched rule's filter is responsible. The customer's GraphWarden audit log records both the rule id and the transforms applied.

## Compatibility test checklist

Run through the checklist against a test GraphWarden instance before publishing your compatibility statement. A pass on every item is the bar for declaring compatibility.

1. **Baseline: direct to Graph.** With `GRAPH_BASE_URL` set to `https://graph.microsoft.com` and the token endpoint set to Azure AD, confirm every feature of your product that calls Graph works. This is your regression fixture.
2. **Open ruleset through GraphWarden.** Point your product at the test proxy URL with a ruleset that contains a single rule: `action: allow` on every endpoint and every method. Every feature that passed step 1 MUST pass step 2. Differences here indicate your product is not reading the base URL or credentials from configuration.
3. **Rule denying one specific endpoint.** Ask the test administrator to add a rule with `action: block` on one specific endpoint your product uses — for example `POST /users`. Trigger that feature and confirm your product surfaces the 403 response without crashing, and that the error message names the blocked action clearly. The rest of your product MUST continue to function for other endpoints.
4. **Rule filtering a response property.** Ask the test administrator to add a rule with `action: filter` and a `strip_properties` transform that removes a property your product reads — for example, `mail` on `/users`. Trigger that feature and confirm your product handles the missing property gracefully (does not crash on `null`; displays a reasonable fallback).
5. **Token expiry and refresh.** Wait past the token lifetime (one hour) and trigger a feature. Confirm your product re-acquires a token against `/proxy/token` transparently.
6. **429 Too Many Requests.** Ask the test administrator to lower the rate limit aggressively, then trigger a burst of calls. Confirm your product honours `Retry-After` and retries after the indicated interval rather than hammering the proxy.
7. **502 / proxy unavailability.** Stop the test proxy and trigger a feature. Confirm your product surfaces a reasonable "Graph unavailable" error rather than a cryptic low-level HTTP failure. Restart the proxy and confirm the next call succeeds without requiring a product restart.
8. **Cross-region deployment.** If your product deploys in multiple regions, confirm each region's configuration points at the region's proxy URL. The proxy URL is per-customer and does not need to match your product's region layout.

A product that passes all eight items can publish a GraphWarden compatibility statement with confidence. A product that fails one or more items has a concrete fix list: externalize what is hardcoded, handle what is unhandled, then re-run the checklist.

A copy-paste template for the published statement is the next page in this section. Use it to declare compatibility in your own product documentation without having to draft the wording from scratch.

## Troubleshooting

The five issues below cover the common surprises when wiring a product to GraphWarden for the first time.

### `401 Unauthorized` from `/proxy/token`

The Proxy Client ID or Proxy Client Secret sent to `/proxy/token` is not the pair the customer's App Admin issued for your App Identity. Your product is likely still sending Azure AD credentials. Confirm the credentials input in your product's configuration is the proxy pair — not the Azure AD application credentials. The customer distributes the proxy pair through their own secrets channel (Key Vault, Vault, CI secrets); the Azure AD application credentials never reach your product when GraphWarden is in the path.

### `HttpRequestException: The SSL connection could not be established`

The proxy is reachable by DNS but its TLS certificate is not trusted by your runtime's trust store. In development against a self-signed test proxy, install the test certificate in the local machine trust store. In production, every proxy your customers run presents a publicly trusted certificate or one issued by their internal CA; your product should not disable certificate validation to work around this.

### Graph SDK calls go to `graph.microsoft.com` instead of the proxy

The Graph base URL override was missed. Graph SDKs default to `https://graph.microsoft.com` when the override is absent; even a single un-overridden code path sends traffic direct to Graph, bypassing the ruleset. Grep your codebase for `graph.microsoft.com` and confirm every occurrence is either configurable or pointing at a configured base URL. This is the most common integration gap.

### Every call returns `403 Forbidden` with the same rule id

A rule in the customer's ruleset is matching aggressively — often a `*` endpoint pattern that was meant as a default-deny and never narrowed. Direct the customer's administrator to the GraphWarden App Admin's What-If Simulator to replay a specific request and see which rule fires. This is a ruleset configuration issue on the customer side, not a product bug.

### Intermittent `502 Bad Gateway`

Microsoft Graph returned a non-2xx upstream response and the proxy is forwarding it as 502. Check Microsoft's Graph status page; these are usually short-lived Graph incidents. Your product's existing retry-with-backoff logic for transient Graph failures works without change.

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden compatibility statement (template)

<!-- TEMPLATE — this page is a copy-paste payload. An ISV replaces the
     {curly brace} markers with their product specifics and publishes the body
     under their own documentation site. The meta-note callout and the
     Customization checklist section are stripped from the published copy. -->

# GraphWarden compatibility statement (template)

<x-doc.callout type="note">
**This page is a template.** Everything inside the "Template body" section below is the copy-paste payload. Replace the `{curly brace}` markers with your product details, then publish the body on your own documentation site under a title like "{Product name} compatibility with GraphWarden".
</x-doc.callout>

<x-doc.status-badge status="supported">Copy-paste template</x-doc.status-badge>

## Template body (copy from here)

---

### {Product name} and GraphWarden

{Product name} version {Minimum version} and later integrates with GraphWarden by routing Microsoft Graph API calls through the proxy you configure. Customers who run GraphWarden can deploy {Product name} without a code change: they point {Product name}'s Graph endpoint configuration at their GraphWarden proxy URL and provide the proxy credentials from their GraphWarden administration console.

### How the integration works

1. Your GraphWarden administrator creates an App Identity for {Product name} and generates proxy credentials (a Proxy Client ID and a Proxy Client Secret).
2. Your GraphWarden administrator configures a ruleset specifying which Microsoft Graph endpoints and scopes {Product name} may access.
3. You configure {Product name} with:
   - Graph base URL: your GraphWarden proxy URL (in place of `https://graph.microsoft.com`)
   - Graph client ID: the Proxy Client ID from your GraphWarden administration console
   - Graph client secret: the Proxy Client Secret from your GraphWarden administration console
4. {Product name} calls Microsoft Graph through your proxy. Your GraphWarden installation audits every call and enforces your ruleset.

### Supported Microsoft Graph endpoints

{Supported Graph endpoints}
<!-- Replace with a list of the Graph endpoints your product uses. Example:
- `GET /users`
- `GET /groups/{id}/members`
- `POST /teams`
-->

### Known limitations

{Known limitations}
<!-- Replace with any edge cases specific to your product. Example:
- Subscription endpoints (`/subscriptions`) are not currently wired through GraphWarden; subscriptions are created against Graph directly.
- Real-time change notifications delivered via webhooks bypass GraphWarden; audit logs do not include webhook deliveries.
-->

### Customer responsibilities

You are responsible for:

- Configuring your GraphWarden ruleset to permit the Graph endpoints {Product name} requires (see the endpoint list above).
- Rotating proxy credentials per your GraphWarden administration policy.
- Monitoring GraphWarden audit logs for denied calls that indicate a ruleset mismatch with {Product name}'s needs.

### Support

For issues specific to {Product name}, contact {Contact email}.
For issues specific to GraphWarden (proxy unavailability, ruleset denials, audit log access), contact your GraphWarden administrator.

---

## Template ends here

## Customization checklist

Before publishing your customized statement, work through the checklist below.

- [ ] Replace `{Product name}` throughout the body (appears roughly six times).
- [ ] Replace `{Minimum version}` with the earliest product version that reads the Graph base URL and credentials from configuration.
- [ ] Replace `{Supported Graph endpoints}` with the exact Graph paths and methods your product calls.
- [ ] Replace `{Known limitations}` with any edge cases specific to your product — subscription endpoints, webhooks, beta endpoints, and similar.
- [ ] Replace `{Contact email}` with your product support address.
- [ ] Remove the Customization checklist section from the published copy.
- [ ] Remove the meta-note callout at the top of this page from the published copy.
- [ ] Keep the Customer responsibilities section — it sets accurate expectations and prevents support tickets that belong to the administrator.
- [ ] Add a last-updated date to the published statement so customers can tell when the document was last reviewed against your product.

## Troubleshooting

The three scenarios below cover the questions your support team receives most often once the compatibility statement is live.

### "The proxy URL returns 401."

The customer configured their Graph credentials, not the proxy credentials, in {Product name}. The proxy issues a distinct Proxy Client ID and Proxy Client Secret pair, separate from the Azure AD application credentials. Direct the customer to their GraphWarden administrator to re-issue the proxy pair and confirm which input field in {Product name} accepts the proxy credentials.

### "Some features work, others return 403."

The customer's GraphWarden ruleset permits some endpoints and denies others. Each 403 response names the matched rule id; direct the customer to their GraphWarden administrator with the rule id to adjust the ruleset. This is expected behaviour — the administrator's ruleset is the authoritative source for which Graph endpoints are permitted.

### "The integration worked in direct-Graph mode but not with GraphWarden."

Confirm {Product name} reads the Graph base URL from configuration rather than a hardcoded constant. If the base URL is hardcoded in {Product name}'s source, the product cannot route through GraphWarden. This indicates a product issue, not a GraphWarden configuration issue, and your engineering team should externalize the constant in the next release.

### "Audit logs show calls to `/subscriptions` being blocked."

If your product relies on Graph subscriptions and webhooks, those calls may bypass GraphWarden by design (the webhook delivery path originates from Microsoft, not from your product). The customer should be aware this traffic does not appear in GraphWarden audit logs. Document this under Known limitations in your published statement.

<x-doc.last-reviewed date="2026-04-19" />



## Why your product should support GraphWarden

# Why your product should support GraphWarden

Enterprise customers adopt GraphWarden to govern Microsoft Graph API access. If your product calls Graph, those customers will ask whether you support routing through the proxy. This page explains the business case for declaring compatibility and what "support" means technically and operationally.

<x-doc.status-badge status="supported">Applies to any product that calls Microsoft Graph</x-doc.status-badge>

<x-doc.prerequisites>

- Your product calls Microsoft Graph directly or through a Microsoft-published Graph SDK
- Product leadership authority to publish a compatibility statement alongside your own product documentation

</x-doc.prerequisites>

## Why enterprise customers ask

GraphWarden customers run regulated workloads: healthcare, financial services, government, and critical infrastructure. The security, compliance, and audit teams at those organizations demand three properties from every application that touches Microsoft Graph on their tenant.

- **Zero-knowledge credentials.** The real Graph client secret is written to the customer's own Azure Key Vault. GraphWarden reads the secret at runtime through a Managed Identity; no third party ever holds a copy. A product that hardcodes its own Graph credentials, or ships them in an embedded configuration file, cannot satisfy this requirement.
- **Ruleset enforcement.** Every Graph call is evaluated against a ruleset the customer authors. Allow, filter, block, and log-only verdicts happen inside the proxy before the call reaches Microsoft. Customers need to confirm that your product continues to function when a rule removes response properties or denies a specific endpoint.
- **Audit trail and retention.** Each Graph call produces an audit event — method, path, caller, status, matched rule, verdict. Events ship to Elasticsearch under a retention policy the customer chooses (30 days, 90 days, 1 year, or 7 years). Compliance frameworks including HIPAA, SOC 2, ISO 27001, PCI DSS, and regional residency rules require this level of evidence.

When a prospect's security review asks "does this product support routing through a Graph governance proxy?", the answer that unblocks the deal is a published compatibility statement. A vague "yes, probably" lengthens the sales cycle; a documented statement shortens it.

## What "compatible" means

GraphWarden compatibility is a configuration property, not a runtime dependency.

A compatible product reads two values from customer configuration instead of hardcoding them:

- **Microsoft Graph base URL** — the customer supplies a proxy URL (for example `https://proxy.customer.internal`) in place of the Microsoft default `https://graph.microsoft.com`.
- **Credentials for the token endpoint** — the customer supplies a Proxy Client ID and a Proxy Client Secret issued by their GraphWarden App Admin. These replace the Azure AD application credentials your product would otherwise use against `https://login.microsoftonline.com`.

Your product builds Graph request URIs against the customer-supplied base URL and acquires tokens from the customer-supplied token endpoint. The SDK calls, the scopes, the response JSON shapes, and the error codes all remain the Microsoft Graph contract. The proxy is transparent to the SDK.

## What it does NOT require

Compatibility does not obligate you to adopt anything GraphWarden-specific at the code level.

- **No proxy SDK.** The customer's proxy URL and credentials are plain strings your existing configuration surface already handles. There is no "GraphWarden SDK" to link, package, or update.
- **No API key exchange or registration with GraphWarden.** Your product does not authenticate to GraphWarden; the customer does, inside their own deployment of the proxy. The credentials your product uses are issued by the customer's App Admin, not by GraphWarden as a vendor.
- **No ongoing subscription, licence fee, or commercial relationship with GraphWarden.** Compatibility is a one-time documentation and configuration change on your side.
- **No GraphWarden-specific code paths in your product.** Your product does not need to reference GraphWarden by name internally. The base URL and credentials are generic configuration values; the customer owns the setup. You may choose to name the capability "GraphWarden compatibility" in your own documentation, but the source code does not need a branded flag.
- **No proxy-specific endpoints.** Your product continues to call the Microsoft Graph paths it already calls: `/v1.0/users`, `/beta/groups`, `/v1.0/me/messages`, and so on. The proxy forwards each path unchanged.

## What you get in return

Declaring compatibility is a sales and retention investment. The concrete artifacts:

- A published compatibility statement on your own documentation site. A copy-paste template lives at the compatibility statement template page; you replace the fill-in markers with your product specifics and publish the result under a title like "{Your product} compatibility with GraphWarden".
- A one-page technical integration guide your support team can reference when a customer asks how to wire your product to their proxy. The compatibility guide in this section walks through the two configuration values, the common edge cases (token caching, rate limits, ruleset denial errors), and a test checklist.
- Positioning with compliance-oriented prospects. Security reviews that ask about Graph governance treat a published compatibility statement as a hard yes and move on. The absence of one extends the review.

## Troubleshooting

The questions below come up frequently during initial compatibility discussions.

### Will my Microsoft Graph SDK work through the proxy?

Yes, as long as the SDK exposes a way to override the Graph base URL. Every major Microsoft-published SDK does so. For `Microsoft.Graph` on .NET, construct `GraphServiceClient` with an `HttpClient` whose `BaseAddress` points at the proxy. For `@microsoft/microsoft-graph-client` on Node, pass a `baseUrl` option. For PowerShell's `Microsoft.Graph` module, pass `-Environment` or supply a custom authentication provider that targets the proxy. The compatibility guide covers the override points per SDK.

### Does compatibility require ongoing maintenance on my side?

No. Once your product reads the Graph base URL and credentials from configuration, the surface is stable. GraphWarden does not introduce breaking changes to its configuration contract; the two values your product reads are the same values every customer supplies. If Microsoft Graph changes a path or adds a new endpoint, your product handles it the same way it would against direct Graph — no proxy-specific update required.

### What happens if a customer's ruleset blocks a feature my product needs?

The proxy returns HTTP 403 with a JSON body naming the matched rule. Your product surfaces the error gracefully, ideally with a message that points the end user to their GraphWarden administrator rather than to your support team. The compatibility guide covers error-surface patterns. The practical outcome: the customer's security policy is the final authority, and your product treats a 403 as "the administrator has not granted permission for this endpoint" — the same way it would treat a 403 from direct Graph.

### Will this affect performance?

The proxy adds one network hop between your product and Microsoft Graph. In most enterprise network topologies the proxy sits close to the customer's clients, so the added latency is single-digit milliseconds. Token acquisition goes to the proxy rather than Azure AD directly, and the proxy-issued JWT has the same one-hour lifetime as a Graph token — your existing token-caching logic works without change.

### Can I test against GraphWarden without deploying it?

GraphWarden runs as a Windows Service or container; a test deployment on a developer workstation takes well under an hour with the pre-staged prerequisites. Many ISVs negotiate a shared lab instance with a prospect during compatibility testing. The compatibility guide includes a test checklist that walks through a baseline run against direct Graph followed by a run through the proxy with an open ruleset and a denying ruleset.

<x-doc.last-reviewed date="2026-04-19" />



## Graph subscriptions, webhooks, and callbacks with GraphWarden

# Graph subscriptions, webhooks, and callbacks with GraphWarden

Microsoft Graph subscriptions deliver change notifications directly from Graph to your endpoint — they bypass the GraphWarden proxy entirely. This page explains the edge cases: which Graph traffic flows through GraphWarden, which does not, how to configure subscriptions safely, and the audit-gap implications for compliance.

<x-doc.status-badge status="supported">Edge case reference for Graph subscriptions</x-doc.status-badge>

<x-doc.prerequisites>

- Familiarity with Graph subscriptions — the `/subscriptions` endpoint and change-notification delivery model
- A deployed GraphWarden proxy and a separate webhook endpoint owned by your application

</x-doc.prerequisites>

<x-doc.ai-prompt title="Decide between Graph subscriptions and polling for GraphWarden">
Help me decide between Graph subscriptions vs polling for my GraphWarden deployment.

My application is governed by a GraphWarden ruleset. I need to track changes to a Graph resource (for example, new mail messages, user directory changes, or Team membership changes) and I am weighing the tradeoffs between /subscriptions change notifications and periodic polling.

I need:
1. A clear statement of which option flows through the GraphWarden proxy and produces audit events
2. The compliance implications of each option under my framework (Loi 25 / PIPEDA / GDPR / SOC 2)
3. A recommendation based on my update frequency, latency tolerance, and audit retention requirements

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my Graph resource type, expected change volume, and compliance framework before recommending.
</x-doc.ai-prompt>

## What flows through GraphWarden

GraphWarden is a reverse proxy your application calls in place of `https://graph.microsoft.com`. Every Graph request your application initiates — read, write, delete, or subscription management — goes through the proxy and is evaluated against your ruleset.

The traffic that flows through GraphWarden:

- **Direct Graph API calls from your application.** Every `GET /users`, `POST /teams`, `DELETE /messages/{id}`, and similar call. The proxy matches each request against your ruleset, applies the verdict (allow, filter, block, log-only), and returns a filtered response.
- **Subscription creation, update, and deletion calls.** `POST /subscriptions` (to create), `PATCH /subscriptions/{id}` (to renew), and `DELETE /subscriptions/{id}` (to remove) are ordinary Graph API calls. They pass through the proxy and are audited like any other request. Your ruleset can allow or block these calls.
- **Token acquisition against `/proxy/token`.** Your application acquires a proxy-issued JWT from the proxy; the proxy exchanges that JWT for a real Graph token against Azure AD. Both hops are audited.

Every audit event produced by this traffic carries the method, path, caller, status code, matched rule, and verdict — the full evidence chain your compliance framework requires.

## What does NOT flow through GraphWarden

The critical edge case for anyone governing Graph traffic: **change notification deliveries bypass the proxy entirely.**

Once you create a subscription (via `POST /subscriptions`, which the proxy audits), Microsoft Graph is authoritative for delivery. When the subscribed resource changes, Graph sends an HTTP POST to the `notificationUrl` you specified in the subscription. That POST originates from Microsoft's infrastructure and arrives at your endpoint directly. It does not touch the GraphWarden proxy.

The asymmetry in plain terms:

| Step | Path | Audited by GraphWarden? |
|------|------|--------------------------|
| Create subscription | Your app -> GraphWarden proxy -> Graph API (`POST /subscriptions`) | Yes |
| Renew subscription | Your app -> GraphWarden proxy -> Graph API (`PATCH /subscriptions/{id}`) | Yes |
| Delete subscription | Your app -> GraphWarden proxy -> Graph API (`DELETE /subscriptions/{id}`) | Yes |
| Change notification delivery | Microsoft Graph -> your webhook endpoint (direct POST) | **No** |
| Validation token exchange | Microsoft Graph -> your webhook endpoint (direct POST with `validationToken`) | **No** |

The same rule applies to every Graph capability that follows the same delivery pattern — including Teams change notifications, presence subscriptions, and any feature that Microsoft delivers to your endpoint from their infrastructure. Outbound calls your app makes to Graph are audited; inbound deliveries from Graph to your app are not.

## Audit-gap implications

<x-doc.callout type="warning">
Change notifications are not captured in GraphWarden audit logs. Your compliance scope must account for this gap when you rely on subscriptions for workflows that touch regulated data.
</x-doc.callout>

The practical consequence: if your application processes personal data, health information, or other regulated content that arrives via change notifications, the processing record is not in GraphWarden. Your compliance evidence for that portion of the data flow must come from elsewhere.

This matters differently for different frameworks:

- **Loi 25 and PIPEDA (Canada)** — both frameworks require records of access to personal information. See [Loi 25 (FR)](/fr/compliance/loi-25) and [PIPEDA](/en/compliance/pipeda). Change notifications that carry personal information need an audit trail your privacy officer can consult during a breach investigation or subject-access request.
- **GDPR (EU)** — Article 30 records of processing activities cover every touch of personal data. See [GDPR](/en/compliance/gdpr). If a change notification delivers the name or email of a data subject, the processing needs to be recorded even though the proxy did not see the request.
- **SOC 2 / HIPAA / ISO 27001** — all three frameworks require audit trails of data access events. A delivery gap widens the surface area your auditor examines because the evidence needs to come from the application logs rather than a single GraphWarden stream.

The mitigation section below describes three patterns for closing the gap without giving up on subscriptions entirely.

## Mitigation patterns

Three patterns close the audit gap in order of increasing engineering effort. Pick the one that fits your workload.

### Pattern 1: Prefer polling over subscriptions

For compliance-sensitive resources, periodic polling replaces subscriptions. Your application queries Graph on a schedule (for example, `GET /me/messages?$filter=receivedDateTime ge {last_poll}`) and every request flows through the proxy. The audit log carries a complete record of every access.

Tradeoffs:

- **Latency.** Polling updates arrive on the poll interval, not on the Graph change. If you poll every 60 seconds, the update lag is up to 60 seconds.
- **Quota.** Polling consumes Graph request quota even when nothing changed. Use `$delta` queries against endpoints that support them to minimize wasted calls.
- **Simplicity.** No webhook endpoint, no validation token handling, no subscription renewal. The entire data flow is audited.

Polling is the default recommendation for resources governed by regulated-data frameworks. The latency cost is usually acceptable against the audit-completeness benefit.

### Pattern 2: Log subscription deliveries from your webhook endpoint

When subscriptions are the right fit for a workload (for example, high-volume Teams presence updates where polling quota would be prohibitive), emit audit events from your webhook endpoint that match the proxy's audit schema. Your application becomes the audit source for the delivery leg of the flow.

The schema to match is documented in the [Agent API](/docs/api-reference/agent-api) reference — same event fields, same UTC timestamp format, same `GWOrgId` tenant tagging. Write the events to the same Elasticsearch index your proxy writes to (or to a parallel index your compliance team can query). The result: one query against the audit system reveals both proxy-originated and webhook-originated events.

Tradeoffs:

- **Engineering cost.** You author and maintain the audit-emit code in your webhook handler. Schema drift between proxy and webhook emitters is an ongoing concern; add a CI check that compares field names.
- **Reliability.** Your webhook endpoint must emit the audit event on every delivery. If the endpoint crashes mid-request, the audit record is missing. Use the same reliability pattern you use for any critical side-effect (retry queue, dead-letter on failure).
- **Completeness.** This closes the audit gap from the compliance auditor's perspective. The gap is conceptual — two sources instead of one — but the evidence chain is complete.

### Pattern 3: Validate deliveries and process through proxy calls

A hybrid pattern: your webhook endpoint receives the notification but does not read the data from the notification payload. Instead, the endpoint extracts the `resourceData.id` or the resource URL from the notification and issues a fresh Graph call through the proxy to fetch the data. The notification acts only as a trigger; the data read flows through the audit path.

Tradeoffs:

- **Correctness.** The delivered payload can be richer than the re-fetched payload when Graph includes encrypted content via `encryptedContent`. Using the re-fetch pattern sacrifices the delivered payload richness.
- **Quota.** Every notification produces a follow-up Graph call. For high-volume subscriptions, this doubles the proxy traffic.
- **Audit completeness.** The data access flows through the proxy; the webhook delivery itself carries no data the compliance team cares about (only an identifier). The audit chain stays inside GraphWarden.

This pattern fits when notification volume is moderate and the compliance team wants a single audit source without the engineering cost of dual-emit.

## Configuring a subscription via GraphWarden

Creating a subscription is an ordinary Graph call through the proxy. The call passes through your ruleset; if the ruleset allows `POST /subscriptions`, the call reaches Graph and the subscription is created.

A typical subscription create:

```http
POST /subscriptions HTTP/1.1
Host: proxy.customer.internal
Authorization: Bearer {proxy-issued-jwt}
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://yourapp.example.com/webhooks/graph",
  "resource": "me/mailfolders('Inbox')/messages",
  "expirationDateTime": "2026-04-20T18:23:45.9356913Z",
  "clientState": "secretClientValue",
  "latestSupportedTlsVersion": "v1_2"
}
```

This POST flows through the proxy and is audited. Your ruleset can restrict subscription creation by path (`POST /subscriptions` -> allow) or by resource (`/subscriptions` + condition on request body -> allow for specific `resource` values only). See the [rule schema](/docs/api-reference/rule-schema) for the condition-type reference.

The subscription itself, once created, is owned by Graph. Your endpoint at `notificationUrl` starts receiving POSTs directly from Microsoft. Those POSTs do not flow through the proxy even though the subscription was created through it.

## Certificate pinning and validation tokens

When you create a subscription, Graph sends an initial POST to `notificationUrl` with a `validationToken` query parameter. Your endpoint must echo the token in the response body within 10 seconds. This handshake confirms to Graph that your endpoint is reachable before Graph starts delivering notifications.

The validation POST comes from Microsoft, not from the proxy. Your endpoint must be reachable from the public internet (or from Microsoft's service tags) regardless of whether the proxy is involved in any other part of the flow.

A minimal validation handler:

```http
POST /webhooks/graph?validationToken=abc123 HTTP/1.1
Host: yourapp.example.com

(empty body)
```

Response:

```http
HTTP/1.1 200 OK
Content-Type: text/plain

abc123
```

Subsequent notification POSTs include the `clientState` value you specified when creating the subscription. Your endpoint validates `clientState` matches the expected value on every delivery — this is your defense against spoofed notifications from attackers who discovered your webhook URL.

For higher assurance, Graph supports encrypted notifications where the payload is encrypted with a certificate your application supplies at subscription creation time. The certificate's public key goes in the subscription request; Graph encrypts the notification body with it; your endpoint decrypts with the matching private key. This does not change the audit path — encrypted or not, the delivery still bypasses the proxy — but it does guarantee only your endpoint can read the payload.

## Troubleshooting

The entries below cover the common surprises when wiring subscriptions behind GraphWarden.

### Subscription creation returns 403 from the proxy

Your ruleset blocks `POST /subscriptions`. The 403 response body names the matched rule id. Direct your GraphWarden administrator to the rule with that id — either the path pattern is broader than intended, or a condition on the rule excludes your App Identity. This is a ruleset configuration issue, not a subscription or webhook issue.

### Webhook endpoint not reachable by Graph

Graph cannot POST to your `notificationUrl`. Common causes: the endpoint is behind a firewall that only allows internal traffic; the DNS name does not resolve publicly; the TLS certificate is self-signed or expired; or the endpoint responds to the validation handshake with a non-200 status code. Test the endpoint with a direct `curl -X POST` from a machine outside your network before creating the subscription.

### `clientState` mismatch in delivered notifications

A notification arrives with a `clientState` that does not match the value you specified when creating the subscription. Either the notification is spoofed (reject it) or your subscription record has drifted from the stored expected value. Re-fetch the subscription via `GET /subscriptions/{id}` through the proxy; the returned `clientState` is the authoritative value. If the delivered notification's `clientState` matches the stored value after re-fetch, your application's stored expected value was stale.

### Certificate validation failures on encrypted notifications

Graph cannot find a usable public key to encrypt the notification with, or your endpoint cannot decrypt with the matching private key. The encryption certificate passed at subscription creation must be valid (not expired, correct key usage) and your endpoint must have the private key available at the time of each delivery. Rotating the certificate requires creating a new subscription; you cannot swap the key on an existing subscription.

### Subscription renewal returns 403 with rule id

Same root cause as subscription creation — the ruleset blocks `PATCH /subscriptions/{id}`. Add the PATCH method to the allowed path pattern in the rule, or add a dedicated rule with `methods: [PATCH]` on `/subscriptions/*`.

<x-doc.last-reviewed date="2026-04-19" />



## PowerShell cookbook: common M365 admin tasks through GraphWarden

# PowerShell cookbook: common M365 admin tasks through GraphWarden

Copy-paste PowerShell snippets for common Microsoft 365 administration tasks routed through GraphWarden. Each snippet assumes you have already connected via `Connect-MgGraph` per the [PowerShell quickstart](./quickstart). Snippets are reference-authored and should be validated on a non-production tenant before operational use.

<x-doc.status-badge status="beta">Reference snippets — validate on a test tenant before production use</x-doc.status-badge>

<x-doc.prerequisites>

- Completed the [PowerShell quickstart](./quickstart) — the connection must be established via `Connect-MgGraph -AccessToken $SecureToken` before any snippet below will route through GraphWarden
- Appropriate ruleset permissions for the Graph endpoints each snippet calls (the per-snippet notes flag which endpoint is touched)
- For write snippets (group create, license assign, guest invite, secret rotate): an App Identity whose ruleset permits the write action

</x-doc.prerequisites>

<x-doc.callout type="warning">
These snippets are reference-authored from the official `Microsoft.Graph` module documentation and the GraphWarden recon notes. They have NOT been executed against a live M365 tenant from this writing. Validate each snippet on a non-production tenant before operational use; parameter names and output shapes change between module versions. Report accuracy issues via the Suggest-an-edit link in the page footer.
</x-doc.callout>

<x-doc.ai-prompt title="Generate a PowerShell snippet for a specific M365 admin task">
Generate a PowerShell snippet for a specific Microsoft 365 admin task, routed through GraphWarden.

Assume my script has already called Connect-MgGraph through the GraphWarden proxy (see the PowerShell quickstart).

I need the snippet to:
1. Use Microsoft.Graph module v2.x cmdlets
2. Include the Graph endpoint the cmdlet calls (so I can verify my ruleset allows it)
3. Include a short "what to expect" note on the shape of the output

Reference documentation: https://graphwarden.com/llms.txt

Ask me for the admin task, any filter criteria, and the output format I want.
</x-doc.ai-prompt>

## List users with selected properties

Return a compact directory listing with the fields you care about. `-Property` maps to `$select`, keeping the payload small and ruleset-filter-friendly.

```powershell
Get-MgUser -Top 25 -Property displayName, mail, userPrincipalName, accountEnabled `
    | Format-Table displayName, mail, accountEnabled
```

**Graph endpoint**: `GET /v1.0/users?$top=25&$select=displayName,mail,userPrincipalName,accountEnabled`. **What to expect**: a table of up to 25 users with the four selected fields; any property a Response Filter strips will surface as `$null`.

## Find inactive users (no sign-in in 90 days)

Useful for licence reclamation and lifecycle hygiene. Requires the `AuditLog.Read.All` scope on the App Identity's underlying registration AND a ruleset that permits `/v1.0/users` with the `signInActivity` property read.

```powershell
$cutoff = (Get-Date).AddDays(-90).ToString('o')

Get-MgUser -Filter "signInActivity/lastSignInDateTime lt $cutoff" `
    -Property displayName, userPrincipalName, signInActivity `
    -Top 100 `
    | Select-Object displayName, userPrincipalName,
        @{ n = 'LastSignIn'; e = { $_.SignInActivity.LastSignInDateTime } }
```

**Graph endpoint**: `GET /v1.0/users?$filter=...`. **What to expect**: a list of up to 100 users whose last interactive sign-in was before the cutoff; `signInActivity` can be `$null` for never-signed-in accounts.

## Create a security group

A new security group with no mail enablement and no group types (the shape most admin tooling creates).

```powershell
$group = New-MgGroup `
    -DisplayName      'Finance-ReadOnly' `
    -MailNickname     'finance-readonly' `
    -MailEnabled:$false `
    -SecurityEnabled:$true `
    -GroupTypes       @()

Write-Host "Created group: $($group.Id)"
```

**Graph endpoint**: `POST /v1.0/groups`. **What to expect**: the new group id on `$group.Id`; GraphWarden audit entry records the matched rule and caller.

## Add members to a group

Add a user to an existing group by directory object id. Accepts user ids, group ids, or service principal ids via the same cmdlet.

```powershell
$groupId = '00000000-0000-0000-0000-000000000000'
$userId  = '11111111-1111-1111-1111-111111111111'

New-MgGroupMember `
    -GroupId         $groupId `
    -DirectoryObjectId $userId
```

**Graph endpoint**: `POST /v1.0/groups/{groupId}/members/$ref`. **What to expect**: a 204 on success; re-adding an existing member raises a terminating error with `Request_BadRequest`.

## Assign a licence to a user

Look up the SKU and assign in two steps. The SKU lookup is a separate Graph call and must itself be permitted by the ruleset.

```powershell
$sku = Get-MgSubscribedSku `
    | Where-Object SkuPartNumber -eq 'ENTERPRISEPACK' `
    | Select-Object -First 1

Set-MgUserLicense `
    -UserId          'alice@contoso.com' `
    -AddLicenses     @(@{ SkuId = $sku.SkuId }) `
    -RemoveLicenses  @()
```

**Graph endpoint**: `POST /v1.0/users/{id}/assignLicense`. **What to expect**: the updated user object; the assignment shows as `SkuPartNumber` in `Get-MgUserLicenseDetail` on the next call.

## Revoke a licence

The same `Set-MgUserLicense` cmdlet with an empty `-AddLicenses` and the SKU id in `-RemoveLicenses`.

```powershell
$sku = Get-MgSubscribedSku `
    | Where-Object SkuPartNumber -eq 'ENTERPRISEPACK' `
    | Select-Object -First 1

Set-MgUserLicense `
    -UserId          'alice@contoso.com' `
    -AddLicenses     @() `
    -RemoveLicenses  @($sku.SkuId)
```

**Graph endpoint**: `POST /v1.0/users/{id}/assignLicense`. **What to expect**: the user's `AssignedLicenses` collection no longer contains the removed SKU on subsequent reads.

## List a user's assigned roles

Discover which directory roles a user holds. Useful for privileged-access reviews.

```powershell
$userId = (Get-MgUser -UserId 'alice@contoso.com').Id

Get-MgUserMemberOf -UserId $userId `
    | Where-Object { $_.AdditionalProperties.'@odata.type' -eq '#microsoft.graph.directoryRole' } `
    | Select-Object @{ n = 'Role'; e = { $_.AdditionalProperties.displayName } }
```

**Graph endpoint**: `GET /v1.0/users/{id}/memberOf`. **What to expect**: a filtered list of directory-role display names the user holds; groups are filtered out by the `@odata.type` test.

## Invite a guest user

Send an invitation to an external email address and optionally include a redirect URL.

```powershell
$invitation = New-MgInvitation `
    -InvitedUserEmailAddress 'partner@supplier.example' `
    -InvitedUserDisplayName  'Partner, External' `
    -SendInvitationMessage:$true `
    -InviteRedirectUrl       'https://myapps.microsoft.com'

Write-Host "Invitation: $($invitation.InviteRedeemUrl)"
```

**Graph endpoint**: `POST /v1.0/invitations`. **What to expect**: an `InviteRedeemUrl` the guest can use to accept; the guest user appears in `Get-MgUser` once accepted.

## List conditional access policies (read-only)

Read-only inventory of CA policies. Requires `Policy.Read.All` scope and ruleset coverage for the `/identity/conditionalAccess` namespace.

```powershell
Get-MgIdentityConditionalAccessPolicy `
    | Select-Object DisplayName, State, CreatedDateTime `
    | Sort-Object CreatedDateTime -Descending
```

**Graph endpoint**: `GET /v1.0/identity/conditionalAccess/policies`. **What to expect**: a table of policy name, state (`enabled` / `disabled` / `enabledForReportingButNotEnforced`), and creation timestamp.

## Query directory audit logs (last 24 hours)

Fetch recent directory audit events. Requires `AuditLog.Read.All` scope and ruleset coverage for `/v1.0/auditLogs/directoryAudits`.

```powershell
$since = (Get-Date).AddHours(-24).ToString('o')

Get-MgAuditLogDirectoryAudit `
    -Filter "activityDateTime ge $since" `
    -Top    50 `
    | Select-Object ActivityDateTime, ActivityDisplayName,
        @{ n = 'InitiatedBy'; e = { $_.InitiatedBy.User.UserPrincipalName } }
```

**Graph endpoint**: `GET /v1.0/auditLogs/directoryAudits?$filter=...`. **What to expect**: up to 50 audit events in the last 24 hours; `InitiatedBy.User.UserPrincipalName` can be `$null` for app-initiated events (check `InitiatedBy.App` in that case).

## List enterprise applications and their permissions

Inventory service principals and their granted permissions — a starting point for app-consent reviews.

```powershell
Get-MgServicePrincipal -Top 100 -Property DisplayName, AppId, AppRoleAssignmentRequired `
    | Select-Object DisplayName, AppId, AppRoleAssignmentRequired
```

**Graph endpoint**: `GET /v1.0/servicePrincipals`. **What to expect**: up to 100 service principals; use `-Filter "tags/any(t: t eq 'WindowsAzureActiveDirectoryIntegratedApp')"` to narrow to user-consented enterprise apps.

## Find service principals with admin consent

Locate service principals whose permissions were granted via admin consent (not user consent). Useful for privileged-app audits.

```powershell
Get-MgOauth2PermissionGrant `
    | Where-Object ConsentType -eq 'AllPrincipals' `
    | Select-Object ClientId, ResourceId, Scope `
    | Sort-Object ClientId
```

**Graph endpoint**: `GET /v1.0/oauth2PermissionGrants`. **What to expect**: delegated-permission grants where `ConsentType` is `AllPrincipals` (admin-consent scope); the `ClientId` is the service principal id of the consenting app.

## Export group membership to CSV

Flatten every member of a given group to a CSV — useful for compliance evidence packs.

```powershell
$groupId = '00000000-0000-0000-0000-000000000000'

Get-MgGroupMember -GroupId $groupId -All `
    | ForEach-Object {
        [pscustomobject]@{
            GroupId           = $groupId
            MemberId          = $_.Id
            MemberType        = $_.AdditionalProperties.'@odata.type'
            DisplayName       = $_.AdditionalProperties.displayName
            UserPrincipalName = $_.AdditionalProperties.userPrincipalName
        }
    } `
    | Export-Csv -Path '.\group-members.csv' -NoTypeInformation
```

**Graph endpoint**: `GET /v1.0/groups/{id}/members` (paginated under the hood via `-All`). **What to expect**: one CSV row per member; nested groups appear as member rows with `MemberType` `#microsoft.graph.group`.

## Check MFA registration status for a user

Read the MFA registration detail for a single user from the authentication methods endpoint.

```powershell
$userId = (Get-MgUser -UserId 'alice@contoso.com').Id

Get-MgReportAuthenticationMethodUserRegistrationDetail `
    -Filter "id eq '$userId'" `
    | Select-Object UserDisplayName, IsMfaRegistered, IsMfaCapable, MethodsRegistered
```

**Graph endpoint**: `GET /v1.0/reports/authenticationMethods/userRegistrationDetails?$filter=...`. **What to expect**: one record per user; `MethodsRegistered` is an array (for example, `@('microsoftAuthenticatorPush', 'phone')`).

## Rotate an app registration secret

Rotate the client secret on an app registration. This is an admin operation — ruleset coverage and audit retention should be tight around this endpoint.

```powershell
$appId    = '00000000-0000-0000-0000-000000000000'
$app      = Get-MgApplication -Filter "appId eq '$appId'"

$newSecret = Add-MgApplicationPassword `
    -ApplicationId $app.Id `
    -PasswordCredential @{
        DisplayName = "rotated-$(Get-Date -Format 'yyyyMMdd')"
        EndDateTime = (Get-Date).AddMonths(12)
    }

Write-Warning "Capture this secret now; Graph will not return it again: $($newSecret.SecretText)"
```

**Graph endpoint**: `POST /v1.0/applications/{id}/addPassword`. **What to expect**: `$newSecret.SecretText` holds the one-time cleartext; save it to your secret store immediately. Always pair with `Remove-MgApplicationPassword` on the old secret once the consuming workload is rotated.

## Troubleshooting

The five failure modes below cover the common cookbook-snippet surprises.

### Cmdlet returns `403 Forbidden` naming a specific Graph scope

The App Identity's underlying Azure AD registration lacks the scope the cmdlet needs (for example, `AuditLog.Read.All` for audit-log cmdlets, `Policy.Read.All` for CA-policy cmdlets). Scope grants happen on the real registration, not in GraphWarden — add the scope in Azure AD and admin-consent it, then retry. A scope missing at the registration level produces a different error surface from a GraphWarden ruleset denial; the former names a scope, the latter names a rule.

### Cmdlet returns `403 Forbidden` naming a GraphWarden rule

A ruleset rule returned `block` on the endpoint the cmdlet called. The response body names the matched rule id. Use the What-If Simulator in GraphWarden App Admin to preview rule evaluation without hitting Graph, and widen or adjust the rule if the block was unintentional.

### Pagination returns fewer results than expected

Many Graph endpoints default to pages of 100; cmdlets like `Get-MgUser` expose `-All` to follow `@odata.nextLink` automatically. Without `-All`, you get only the first page. Some ruleset Response Filters strip `@odata.nextLink` as part of `allow_properties`; if pagination appears broken, inspect the raw response with `Invoke-MgGraphRequest -Method GET -Uri '/v1.0/users?$top=2'` and widen the filter to include navigation properties.

### Rate-limit (`429 Too Many Requests`) on bulk snippets

Large cookbook snippets (for example, export group membership on a 10,000-seat tenant) can trigger Microsoft Graph's per-app throttles, or a ruleset rate-limit rule in GraphWarden. The response body's `Retry-After` header indicates the backoff window. For scripted bulk work, add a `Start-Sleep` between batches or switch to `$batch` request batching.

### Snippet result differs from tenant reality

The snippets on this page are reference-authored and not live-tested against every tenant shape. If a snippet's output does not match what you expect, re-run the underlying Graph call with `Invoke-MgGraphRequest -Verbose` to see the exact request URI and response, then file a correction via the Suggest-an-edit link in the page footer.

<x-doc.last-reviewed date="2026-04-19" />



## Route Exchange Online PowerShell through GraphWarden

# Route Exchange Online PowerShell through GraphWarden

`Connect-ExchangeOnline` can route through GraphWarden by supplying a proxy-acquired access token and pointing the module at the proxy as its Graph endpoint. Every existing Exchange Online cmdlet (`Get-Mailbox`, `Set-CASMailbox`, `Get-CASMailbox`, and the rest) then flows through the proxy and is subject to your ruleset's endpoint allowlist. This page shows the connect pattern, the ruleset considerations for Exchange workloads, and the legacy-REST cmdlets that bypass the proxy entirely.

<x-doc.status-badge status="supported">ExchangeOnlineManagement v3.x</x-doc.status-badge>

<x-doc.prerequisites>

- PowerShell 7+ (recommended) or Windows PowerShell 5.1
- `ExchangeOnlineManagement` module v3.x — install with `Install-Module ExchangeOnlineManagement -Scope CurrentUser`
- A GraphWarden proxy URL reachable from the script host
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this script
- For certificate-based Exchange authentication: a certificate thumbprint registered on the Azure AD app registration GraphWarden brokers for

</x-doc.prerequisites>

<x-doc.ai-prompt title="Route an Exchange Online admin script with an AI assistant">
Route my Exchange Online admin script through GraphWarden.

My script currently calls Connect-ExchangeOnline with certificate-based app-only auth against Exchange Online directly.

I need:
1. The pattern to acquire a proxy JWT from GraphWarden's /proxy/token endpoint
2. A Connect-ExchangeOnline -AccessToken invocation that routes through the proxy
3. Guidance on which of my cmdlets transit Microsoft Graph (routed through GraphWarden) vs the legacy Exchange REST endpoint (not routed)

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my proxy URL, proxy credentials, and the cmdlet list the script uses today.
</x-doc.ai-prompt>

## The override pattern

Modern `ExchangeOnlineManagement` v3.x uses Microsoft Graph under the hood for the cmdlets that have been migrated to Graph (roughly: mailbox read operations, user-level calendar queries, some transport rule reads). Those cmdlets honour the `MICROSOFT_GRAPH_API_ENDPOINT` environment variable the same way `Microsoft.Graph` cmdlets do, and they accept `-AccessToken` on `Connect-ExchangeOnline` so you can pass a GraphWarden-issued proxy JWT.

- **Token acquisition** — post your Proxy Client ID and Proxy Client Secret to `POST {proxy-host}/proxy/token`. The response is a proxy JWT; pass it to `Connect-ExchangeOnline` as `-AccessToken`.
- **Graph endpoint override** — set `MICROSOFT_GRAPH_API_ENDPOINT` to the proxy URL BEFORE `Connect-ExchangeOnline`. Graph-backed cmdlets read this at connection time.

```powershell
# 1. Configuration — read from the environment.
$ProxyUrl     = $env:GRAPHWARDEN_PROXY_URL     # e.g. https://proxy.example.com
$ClientId     = $env:GRAPHWARDEN_CLIENT_ID     # Proxy Client ID from App Admin
$ClientSecret = $env:GRAPHWARDEN_CLIENT_SECRET # Proxy Client Secret from App Admin
$Organization = 'contoso.onmicrosoft.com'      # Your Exchange Online tenant domain

if (-not $ProxyUrl -or -not $ClientId -or -not $ClientSecret) {
    throw "Set GRAPHWARDEN_PROXY_URL, GRAPHWARDEN_CLIENT_ID, and GRAPHWARDEN_CLIENT_SECRET before running."
}

# 2. Acquire a proxy JWT via client_credentials against the proxy token endpoint.
$TokenResponse = Invoke-RestMethod `
    -Method Post `
    -Uri "$ProxyUrl/proxy/token" `
    -ContentType 'application/x-www-form-urlencoded' `
    -Body @{
        grant_type    = 'client_credentials'
        client_id     = $ClientId
        client_secret = $ClientSecret
    }

# 3. Point Graph-backed Exchange cmdlets at the proxy BEFORE Connect-ExchangeOnline.
$env:MICROSOFT_GRAPH_API_ENDPOINT = $ProxyUrl

# 4. Connect using the proxy JWT. -ShowBanner:$false quiets the module banner.
Connect-ExchangeOnline `
    -AccessToken  $TokenResponse.access_token `
    -Organization $Organization `
    -ShowBanner:$false

# 5. Verification call — Get-Mailbox routes through the proxy on v3.x.
Get-Mailbox -ResultSize 1 | Select-Object DisplayName, PrimarySmtpAddress
```

The `-Organization` parameter is mandatory for app-only / token-based connections so the module knows which tenant to scope cmdlets to. Omit it only if you are connecting with user-delegated auth, which is not the GraphWarden path.

## Configuring ruleset for Exchange workloads

Exchange Online cmdlets call a mix of Microsoft Graph endpoints and Exchange-specific REST endpoints. Your GraphWarden ruleset must cover the Graph-backed paths; the Exchange-specific paths bypass the proxy and are NOT subject to ruleset enforcement (see the next section).

Graph-backed endpoints to include in your allowlist for common Exchange workloads:

| Workload | Graph endpoint pattern |
|---|---|
| Mailbox properties (read) | `/v1.0/users/{id}/mailboxSettings`, `/v1.0/users/{id}?$select=...` |
| Mailbox messages | `/v1.0/users/{id}/messages` and `/v1.0/users/{id}/mailFolders/*/messages` |
| Calendar reads | `/v1.0/users/{id}/calendar`, `/v1.0/users/{id}/events` |
| Distribution groups (read) | `/v1.0/groups`, `/v1.0/groups/{id}/members` |

For workloads that are NOT Graph-backed (transport rules, message-trace queries, some mail-flow cmdlets), plan to surface those in your compliance audit through Exchange Online's own audit log rather than through GraphWarden — the proxy never sees those requests.

<x-doc.callout type="warning">
Some Exchange Online cmdlets route through the legacy Exchange REST endpoint (`outlook.office365.com`) rather than Microsoft Graph. Examples include most transport-rule cmdlets, `Get-MessageTrace`, and the older shell-proxy cmdlets. These calls do NOT transit GraphWarden and are not covered by your ruleset. Identify the endpoint a cmdlet uses by running it with `-Verbose` and inspecting the request URIs in the output.
</x-doc.callout>

## Common admin scenarios

Four short scenarios showing the common operations. Each assumes the connection from the override pattern above is already established.

### List mailboxes with size and quota

```powershell
Get-Mailbox -ResultSize 100 `
    | Get-MailboxStatistics `
    | Select-Object DisplayName, TotalItemSize, ItemCount, LastLogonTime `
    | Sort-Object TotalItemSize -Descending
```

`Get-MailboxStatistics` reads mailbox size counters from Graph on v3.x; the Graph endpoint is subject to ruleset enforcement.

### Update mail routing for a single user

```powershell
Set-Mailbox `
    -Identity 'alice@contoso.com' `
    -ForwardingSmtpAddress 'compliance-archive@contoso.com' `
    -DeliverToMailboxAndForward:$true
```

Mailbox property updates go through Microsoft Graph on v3.x; a ruleset with `action: block` on `PATCH /v1.0/users/{id}` will stop this cmdlet at the proxy.

### Grant full-access mailbox permission

```powershell
Add-MailboxPermission `
    -Identity 'shared-inbox@contoso.com' `
    -User 'helpdesk@contoso.com' `
    -AccessRights FullAccess `
    -AutoMapping:$false
```

Mailbox permission changes are audit-heavy; even with `action: allow`, every call surfaces as a GraphWarden audit event with the matched rule id and the payload summary.

### Export mailbox permissions to CSV

```powershell
Get-Mailbox -ResultSize Unlimited `
    | ForEach-Object {
        Get-MailboxPermission -Identity $_.Identity `
            | Where-Object { $_.User -notlike 'NT AUTHORITY\*' -and -not $_.IsInherited }
    } `
    | Select-Object Identity, User, AccessRights `
    | Export-Csv -Path '.\mailbox-permissions.csv' -NoTypeInformation
```

Useful for compliance reviews. Run against a non-production tenant first — `ResultSize Unlimited` over a large tenant can trigger proxy rate-limit rules depending on your ruleset.

## Troubleshooting

The five failure modes below cover the common surprises when running Exchange Online cmdlets against GraphWarden.

### `Connect-ExchangeOnline` returns a modern-auth-only error

The `ExchangeOnlineManagement` v3.x module has dropped support for Basic authentication; all connections must use OAuth 2.0. If you see the error `Basic auth disabled` or `modern authentication required`, the module is working as designed — you must supply `-AccessToken` (the GraphWarden path) or `-CertificateThumbprint` (direct to Exchange). There is no fallback to username/password.

### Cmdlet returns `401 Unauthorized` after an hour of scripted runs

Proxy JWTs expire after roughly one hour. The Exchange Online module does not automatically refresh tokens supplied via `-AccessToken`. For long-running scripts, wrap the connect + cmdlet call in a helper that catches `401`, calls `Disconnect-ExchangeOnline`, reacquires a fresh proxy JWT from `/proxy/token`, and reconnects.

### Cmdlet returns `403 Forbidden` with a GraphWarden rule id in the body

A rule in the bound ruleset returned a `block` verdict on the Graph endpoint the cmdlet called. The response body names the matched rule. Confirm that the Graph endpoint pattern is covered by your ruleset's allowlist, and use the What-If Simulator to preview rule evaluation without hitting Graph.

### Cmdlet succeeds but no audit entry appears in GraphWarden

The cmdlet used the legacy Exchange REST endpoint (`outlook.office365.com` or equivalent), not Microsoft Graph. GraphWarden does not intercept Exchange REST, so the request bypassed the proxy. This is expected for transport-rule and some mail-flow cmdlets; audit those via Exchange Online's native audit log.

### `502 Bad Gateway` on `Get-Mailbox`

The proxy is reachable but Microsoft Graph returned a non-2xx upstream response, or the Exchange-on-Graph session the module established on connect has expired. Check the proxy's health endpoint (`GET /health`), then call `Disconnect-ExchangeOnline` and reconnect. The module re-establishes its Graph session on `Connect-ExchangeOnline`.

<x-doc.last-reviewed date="2026-04-19" />



## Route legacy AzureAD and MSOnline PowerShell modules through GraphWarden

# Route legacy AzureAD and MSOnline PowerShell modules through GraphWarden

The legacy `AzureAD` and `MSOnline` PowerShell modules are deprecated by Microsoft but still widely deployed in enterprise automation. Both modules can be routed through GraphWarden with the same override pattern as `Microsoft.Graph`: acquire a proxy JWT, pass it to `Connect-AzureAD` or `Connect-MsolService`, and existing cmdlets flow through the proxy. This page also flags the endpoint differences that matter when planning a migration.

<x-doc.status-badge status="supported">AzureAD v2.x and MSOnline v1.x through the proxy (maintenance path)</x-doc.status-badge>

<x-doc.prerequisites>

- Windows PowerShell 5.1 (the MSOnline module is a PS 5.1-only module; AzureAD works on 5.1 and on PowerShell 7 with the `Windows PowerShell Compatibility` layer)
- `AzureAD` module v2.x (`Install-Module AzureAD -Scope CurrentUser`) OR `MSOnline` module v1.x (`Install-Module MSOnline -Scope CurrentUser`)
- A GraphWarden proxy URL reachable from the script host
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this script

</x-doc.prerequisites>

<x-doc.callout type="warning">
Microsoft has deprecated both the `AzureAD` and `MSOnline` modules. New development SHOULD use `Microsoft.Graph` (see the [PowerShell quickstart](./quickstart)). This page covers routing existing scripts through GraphWarden so they can keep running during a migration window — not as a long-term recommendation.
</x-doc.callout>

<x-doc.ai-prompt title="Migrate a legacy AzureAD or MSOnline script with an AI assistant">
Help me route an existing PowerShell script that uses the AzureAD or MSOnline module through GraphWarden, and plan a migration to Microsoft.Graph.

My script currently calls Connect-AzureAD or Connect-MsolService with credential-based auth against Azure AD directly.

I need:
1. The pattern to acquire a proxy JWT from GraphWarden's /proxy/token endpoint
2. A Connect-AzureAD -AadAccessToken invocation that routes through the proxy
3. A mapping from my current AzureAD/MSOnline cmdlets to Microsoft.Graph equivalents so I can plan the migration

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my proxy URL, proxy credentials, and which legacy cmdlets the script relies on.
</x-doc.ai-prompt>

## Why this page exists

Enterprise PowerShell automation written between 2016 and 2020 overwhelmingly targeted the `AzureAD` and `MSOnline` modules. Many of those scripts are still in production — they run under scheduled tasks, service accounts, and runbooks that compliance owners cannot rewrite overnight. Routing them through GraphWarden unblocks the audit-and-ruleset story without forcing a same-week migration.

The load-bearing fact: both modules speak HTTP to Azure AD or legacy Azure AD Graph (`graph.windows.net`), and both accept an externally-acquired access token via a connect-time parameter. That is the seam GraphWarden uses.

## AzureAD module through GraphWarden

The `AzureAD` module exposes `-AadAccessToken` on `Connect-AzureAD`. When you pass a token, the module skips its own interactive / device-code flow and uses what you supplied for every subsequent cmdlet. GraphWarden issues a proxy JWT from `/proxy/token`; the AzureAD cmdlets then call through the proxy with that JWT as the `Authorization: Bearer` header.

```powershell
# 1. Configuration — read from the environment, never hardcode secrets.
$ProxyUrl     = $env:GRAPHWARDEN_PROXY_URL     # e.g. https://proxy.example.com
$ClientId     = $env:GRAPHWARDEN_CLIENT_ID     # Proxy Client ID from App Admin
$ClientSecret = $env:GRAPHWARDEN_CLIENT_SECRET # Proxy Client Secret from App Admin

if (-not $ProxyUrl -or -not $ClientId -or -not $ClientSecret) {
    throw "Set GRAPHWARDEN_PROXY_URL, GRAPHWARDEN_CLIENT_ID, and GRAPHWARDEN_CLIENT_SECRET before running."
}

# 2. Force TLS 1.2 — Windows PowerShell 5.1 defaults to older protocols.
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# 3. Acquire a proxy JWT from the GraphWarden token endpoint (not Azure AD).
$TokenResponse = Invoke-RestMethod `
    -Method Post `
    -Uri "$ProxyUrl/proxy/token" `
    -ContentType 'application/x-www-form-urlencoded' `
    -Body @{
        grant_type    = 'client_credentials'
        client_id     = $ClientId
        client_secret = $ClientSecret
    }

# 4. Connect-AzureAD accepts a pre-acquired token via -AadAccessToken.
#    The module uses this token for every cmdlet that follows.
Connect-AzureAD `
    -AadAccessToken $TokenResponse.access_token `
    -AccountId      'service-principal-upn@contoso.onmicrosoft.com'

# 5. Existing cmdlets work unchanged — now routed through GraphWarden.
Get-AzureADUser -Top 1 | Select-Object ObjectId, DisplayName, UserPrincipalName
```

The `AccountId` parameter is a display-only value for the AzureAD module's session context — it does not affect authentication. Use the UPN of the service principal or account you want shown in `Get-AzureADCurrentSessionInfo` output.

<x-doc.callout type="note">
`AzureAD` cmdlets call the older Azure AD Graph API (`graph.windows.net`), not Microsoft Graph (`graph.microsoft.com`). Your GraphWarden ruleset must have endpoint coverage for the Azure AD Graph paths your script touches; if your proxy was scoped to Microsoft Graph only, some cmdlets will return `404 Not Found` or pass through with no ruleset matching. Verify endpoint coverage with your GraphWarden administrator before migrating a production script.
</x-doc.callout>

## MSOnline module through GraphWarden

The `MSOnline` module is older than `AzureAD`: it predates the standardised `-AadAccessToken` parameter and targets the legacy MSOnline service endpoint (`provisioningapi.microsoftonline.com`) for most of its cmdlets. Connection uses `Connect-MsolService`, which accepts `-AdGraphAccessToken` and `-MsGraphAccessToken` parameters for externally-acquired tokens.

```powershell
# Same token-acquisition block as above — shown abridged here.
$TokenResponse = Invoke-RestMethod `
    -Method Post `
    -Uri "$ProxyUrl/proxy/token" `
    -ContentType 'application/x-www-form-urlencoded' `
    -Body @{
        grant_type    = 'client_credentials'
        client_id     = $ClientId
        client_secret = $ClientSecret
    }

# Connect-MsolService wants TWO tokens — one for Azure AD Graph and one for
# Microsoft Graph. Passing the same proxy JWT for both is the pragmatic choice
# when the proxy is the authority for everything.
Connect-MsolService `
    -AdGraphAccessToken $TokenResponse.access_token `
    -MsGraphAccessToken $TokenResponse.access_token

# Existing cmdlets — some route through the proxy, some do not (see callout below).
Get-MsolUser -MaxResults 1 | Select-Object ObjectId, UserPrincipalName
```

<x-doc.callout type="warning">
MSOnline cmdlets that query the legacy provisioning endpoint (`provisioningapi.microsoftonline.com`) are NOT routed through GraphWarden — that endpoint is outside the Microsoft Graph and Azure AD Graph namespaces the proxy intercepts. Only the cmdlets that transit the Azure AD Graph endpoint (for example, `Get-MsolUser`, `Get-MsolGroup`) participate in ruleset enforcement. For full coverage, migrate the affected cmdlets to `Microsoft.Graph` where every cmdlet maps to a Microsoft Graph endpoint the proxy controls.
</x-doc.callout>

The migration priority is therefore MSOnline first (partial proxy coverage), then AzureAD (full Azure AD Graph coverage but deprecated), then Microsoft.Graph (fully covered and the long-term supported surface).

## Migration guide (AzureAD / MSOnline to Microsoft.Graph)

A rough cmdlet map for the common enterprise tasks. Exact parameter shapes differ — consult the `Microsoft.Graph` cmdlet reference before running these against production.

| Legacy cmdlet | Microsoft.Graph equivalent |
|---|---|
| `Get-AzureADUser` | `Get-MgUser` |
| `Get-AzureADGroup` | `Get-MgGroup` |
| `Get-AzureADGroupMember` | `Get-MgGroupMember` |
| `New-AzureADGroup` | `New-MgGroup` |
| `Get-MsolUser` | `Get-MgUser` |
| `Get-MsolRoleMember` | `Get-MgDirectoryRoleMember` |
| `Set-MsolUserLicense` | `Set-MgUserLicense` |
| `Connect-MsolService` | `Connect-MgGraph` |

Once a script is on `Microsoft.Graph`, point it at the proxy using the [Microsoft.Graph module page](./microsoft-graph-module) — the `MICROSOFT_GRAPH_API_ENDPOINT` environment-variable override is cleaner than the `-AadAccessToken` pattern shown on this page.

## Troubleshooting

The failure modes below cover the common surprises when running legacy modules against GraphWarden for the first time.

### `AADSTS*` error from `Connect-AzureAD` or `Connect-MsolService`

The module fell back to its own interactive auth flow — usually because the `-AadAccessToken` / `-AdGraphAccessToken` parameter was not passed, or because the `Invoke-RestMethod` call to `/proxy/token` returned an error that was not checked. Inspect `$TokenResponse.access_token` before the Connect call; if it is empty, the token request failed (`401` from the proxy means the Proxy Client ID or Secret does not match what App Admin stored).

### `403 Forbidden` from an AzureAD cmdlet (e.g. `Get-AzureADUser`)

A rule in the ruleset bound to your App Identity returned a `block` verdict on an Azure AD Graph path. The response body names the matched rule. Confirm that your ruleset has endpoint coverage for `graph.windows.net` paths — a ruleset scoped to Microsoft Graph only will NOT match Azure AD Graph paths, so either the request falls through (which looks like a generic `403`) or the cmdlet hits an unproxied endpoint. Widen the ruleset or migrate the cmdlet.

### MSOnline cmdlet succeeds but no audit entry appears

The cmdlet targeted the legacy provisioning endpoint (`provisioningapi.microsoftonline.com`), which GraphWarden does NOT intercept. The request bypassed the proxy and hit Microsoft directly. This is not a failure — it is the documented behaviour — but it means ruleset enforcement is silently skipped for that cmdlet. Migrate the specific cmdlet to `Microsoft.Graph` to regain audit coverage.

### Windows PowerShell 5.1 raises a TLS 1.2 error on `Invoke-RestMethod`

Windows PowerShell 5.1 defaults to TLS 1.0 / 1.1 on older .NET Framework versions; GraphWarden serves TLS 1.2+. Run the one-liner below before any `Invoke-RestMethod` call:

```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```

PowerShell 7+ negotiates TLS 1.2+ by default. Note that the `MSOnline` module is PS 5.1 only, so the TLS override is mandatory for any MSOnline script.

### Token expires mid-script (502 / 401 after an hour)

Proxy JWTs expire after roughly one hour. Long-running scripts should wrap the token acquisition in a helper function that re-requests on 401, then call `Disconnect-AzureAD` / `Disconnect-MsolService` and reconnect with the fresh token. AzureAD and MSOnline do not support silent token refresh — the connection must be rebuilt.

<x-doc.last-reviewed date="2026-04-19" />



## Manage Microsoft 365 with the Microsoft.Graph PowerShell module through GraphWarden

# Manage Microsoft 365 with the Microsoft.Graph PowerShell module through GraphWarden

Once connected through the quickstart, `Microsoft.Graph` cmdlets work against GraphWarden transparently. This page walks through common Microsoft 365 admin scenarios — users, groups, licences, directory audit — and shows how ruleset enforcement surfaces when a cmdlet is denied. Every snippet assumes the connection is already established; see the quickstart for the `Connect-MgGraph` setup.

<x-doc.status-badge status="supported">Microsoft.Graph v2.x</x-doc.status-badge>

<x-doc.prerequisites>

- Completed the PowerShell quickstart (see `./quickstart`). The connection must be established via `Connect-MgGraph -AccessToken $SecureToken` before any cmdlet below will route through GraphWarden.
- An App Identity configured in GraphWarden App Admin with a ruleset that permits the operations you intend to run. Cmdlets whose underlying Graph calls are blocked by a rule surface as `403 Forbidden` errors.

</x-doc.prerequisites>

## List users with selected properties

The `Get-MgUser` cmdlet wraps `GET /v1.0/users`. `-Property` maps to `$select`, `-Top` maps to `$top`, and `-Filter` maps to `$filter`. All three query shapes pass through the proxy byte-for-byte.

<x-doc.code-block lang="powershell">
Get-MgUser `
    -Top 10 `
    -Property 'displayName','mail','userPrincipalName','accountEnabled'
    | Format-Table displayName, mail, accountEnabled
</x-doc.code-block>

If a ruleset Response Filter applies `allow_properties` or `strip_properties` to `/v1.0/users`, the missing keys will not appear in the deserialized objects — a user with `mail` stripped surfaces as `$null`.

## Create a group

`New-MgGroup` issues `POST /v1.0/groups`. The example below creates a security group; adjust `MailEnabled`, `SecurityEnabled`, and `GroupTypes` for other shapes (Microsoft 365 group, distribution list, dynamic membership).

<x-doc.code-block lang="powershell">
$group = New-MgGroup `
    -DisplayName   'Test security group' `
    -MailNickname  'test-sec-group' `
    -MailEnabled:$false `
    -SecurityEnabled:$true `
    -GroupTypes    @()

Write-Host "Created group: $($group.Id) - $($group.DisplayName)"
</x-doc.code-block>

Group creation is a common ruleset gate — many policies limit which App Identities can create groups, or require a naming convention enforced by a rule's `conditions` block. If your request is denied, the response body will name the matched rule.

## Assign a licence

License assignment uses `Set-MgUserLicense`, which issues `POST /v1.0/users/{id}/assignLicense`. You need the SKU `Id` of the plan you are assigning — fetch it with `Get-MgSubscribedSku` before calling assign.

<x-doc.code-block lang="powershell">
# 1. Find the SKU you want to assign (e.g. Microsoft 365 E3).
$sku = Get-MgSubscribedSku `
    | Where-Object SkuPartNumber -eq 'ENTERPRISEPACK' `
    | Select-Object -First 1

# 2. Assign it to a user by UPN or object id.
Set-MgUserLicense `
    -UserId       'alice@contoso.com' `
    -AddLicenses  @(@{ SkuId = $sku.SkuId }) `
    -RemoveLicenses @()
</x-doc.code-block>

License state is an audit-heavy area. Even with `action: allow`, every assign / remove surfaces as an audit event in GraphWarden with the matched rule id, the caller, and the payload summary.

## Read audit log entries

`Get-MgAuditLogDirectoryAudit` returns tenant-level audit activities (admin actions, policy changes). The scope `AuditLog.Read.All` or `Directory.Read.All` must be granted on the underlying Azure AD app registration AND permitted by the ruleset — the App Identity needs to be permitted to call `/v1.0/auditLogs/directoryAudits` in GraphWarden.

<x-doc.code-block lang="powershell">
Get-MgAuditLogDirectoryAudit `
    -Top    10 `
    -Filter "activityDisplayName eq 'Add user'"
    | Select-Object ActivityDateTime, ActivityDisplayName, InitiatedBy
</x-doc.code-block>

If the ruleset has not been configured to permit this endpoint, expect `403 Forbidden` with a rule id in the response body (see the "Understanding ruleset denials in PowerShell" section below).

## Delete a user (permission-gated)

Delete operations are high-impact and are typically denied by default in GraphWarden rulesets. The example below intentionally demonstrates a denied cmdlet — run it against an identity whose ruleset blocks user deletes to see the shape of the error.

<x-doc.callout type="warning">
`Remove-MgUser` issues `DELETE /v1.0/users/{id}` and is irreversible when permitted. If your ruleset has been configured to allow deletes, running this snippet against a real user account will remove that user. Use a disposable test account or a demo tenant for the denial demonstration.
</x-doc.callout>

<x-doc.code-block lang="powershell">
try {
    Remove-MgUser -UserId 'victim@contoso.com' -ErrorAction Stop
    Write-Host "User removed."
}
catch {
    # Expected: 403 Forbidden when the ruleset denies DELETE on /v1.0/users.
    Write-Warning "Remove-MgUser failed: $($_.Exception.Message)"
    Write-Host  "Response body:" ($_.ErrorDetails.Message)
}
</x-doc.code-block>

Expected output when the rule blocks the request (exact rule id will vary with your ruleset):

<x-doc.code-block lang="powershell">
# WARNING: Remove-MgUser failed: Response status code does not indicate success: 403 (Forbidden).
# Response body: {"error":{"code":"Forbidden","message":"Blocked by GraphWarden rule 'deny-user-delete'."}}
</x-doc.code-block>

## Understanding ruleset denials in PowerShell

A blocked cmdlet raises a terminating error whose `$_.Exception.Response.StatusCode` is `403` and whose response body contains the matched rule id. There are two useful ways to inspect it.

<x-doc.code-block lang="powershell">
# Option 1 — inspect $Error[0] after a failed cmdlet.
try {
    Get-MgAuditLogSignIn -Top 1 -ErrorAction Stop
}
catch {
    $response = $_.Exception.Response
    Write-Host "Status:      $([int]$response.StatusCode) $($response.StatusCode)"
    Write-Host "Rule body:   $($_.ErrorDetails.Message)"
}

# Option 2 — -ErrorVariable captures the error without terminating the script.
$failures = $null
Get-MgGroup -Top 1 -ErrorAction SilentlyContinue -ErrorVariable failures

if ($failures) {
    foreach ($f in $failures) {
        Write-Host "Failed: $($f.Exception.Message)"
    }
}
</x-doc.code-block>

The rule id in the response body is the same identifier shown in GraphWarden App Admin's audit log entry for the request; use it to locate the rule, review its `match` pattern and `conditions`, and decide whether to widen the rule or adjust the script.

<x-doc.callout type="info">
GraphWarden returns Microsoft Graph's native status codes for pass-through responses (2xx, 4xx forwarded from Graph). A `403` that originates at the proxy (ruleset denial) versus a `403` that originates at Graph (scope not granted on the underlying app registration) both surface the same status code; the response body distinguishes them — GraphWarden denials name a rule, Graph denials name a scope.
</x-doc.callout>

## Troubleshooting

The five failure modes below cover the common surprises when running Microsoft.Graph cmdlets against GraphWarden.

### `Connect-MgGraph` succeeds but every cmdlet returns 401

The proxy JWT that was passed to `Connect-MgGraph` has expired, or the SDK is not re-reading `MICROSOFT_GRAPH_API_ENDPOINT` (set after the connection was established). Disconnect with `Disconnect-MgGraph`, reacquire a fresh proxy JWT, ensure the env var is set, and reconnect.

### Cmdlet returns `403 Forbidden` with no rule id in the body

The rule body format changes with proxy versions; on older proxies the body may be `{"error":{"code":"Forbidden","message":"Access denied."}}` with no rule id. Check the audit log in GraphWarden App Admin for the matching request — audit events always include the rule id regardless of response body shape.

### Cmdlet hangs on first call

The proxy URL resolves by DNS but the host is unreachable. Test with `Test-NetConnection -ComputerName <proxy-host> -Port 443`. In on-prem deployments, verify the firewall permits outbound 443 from the scripting host to the proxy.

### `Invoke-MgGraphRequest` ignores the env var

`Invoke-MgGraphRequest` is a lower-level cmdlet that composes against the endpoint fixed at `Connect-MgGraph` time. If you switched `MICROSOFT_GRAPH_API_ENDPOINT` after connecting, `Invoke-MgGraphRequest` will keep calling the previous endpoint. Disconnect and reconnect to pick up the change.

### Pagination returns 0 results with a `@odata.nextLink`

Some ruleset Response Filters strip the `@odata.nextLink` property. If pagination appears broken, inspect the raw response with `Invoke-MgGraphRequest -Method GET -Uri '/v1.0/users?$top=2'` and check whether `@odata.nextLink` is present. If it was filtered, adjust the rule to keep navigation properties in the allow list.

<x-doc.last-reviewed date="2026-04-19" />



## Route a PowerShell script through GraphWarden

# Route a PowerShell script through GraphWarden

A PowerShell script using `Microsoft.Graph` cmdlets connects to GraphWarden by passing a custom access token and a Graph endpoint override. After `Connect-MgGraph`, every cmdlet you already use (`Get-MgUser`, `New-MgGroup`, and the rest) works unchanged. This page shows the complete setup.

<x-doc.status-badge status="supported">Microsoft.Graph v2.x on PowerShell 5.1 or 7+</x-doc.status-badge>

<x-doc.prerequisites>

- PowerShell 5.1 or 7+
- `Microsoft.Graph` module v2.x — install once with `Install-Module Microsoft.Graph -Scope CurrentUser`
- A GraphWarden proxy URL reachable from the machine running the script
- A Proxy Client ID and Proxy Client Secret issued by GraphWarden App Admin for the App Identity that represents this script

</x-doc.prerequisites>

<x-doc.ai-prompt title="Route a PowerShell script with an AI assistant">
Route my PowerShell script using Connect-MgGraph through GraphWarden.

My script currently calls Connect-MgGraph with client-credential auth against https://graph.microsoft.com.

I need:
1. The tested pattern to acquire a token from the GraphWarden proxy's token endpoint
2. A Connect-MgGraph invocation that uses that token against the proxy as the Graph endpoint
3. A sanity check that Get-MgContext confirms the endpoint is the proxy

Reference documentation: https://graphwarden.com/llms.txt

Ask me for my proxy URL and proxy credentials.
</x-doc.ai-prompt>

## The two overrides

A direct-to-Graph PowerShell script does two things: it calls `Connect-MgGraph` (which acquires a token from Azure AD) and then issues cmdlets that hit `https://graph.microsoft.com`. To route through GraphWarden you override both.

- **Token acquisition** — post your Proxy Client ID and Proxy Client Secret to `POST {proxy-host}/proxy/token` (per the proxy architecture — recon #210). The response is a proxy JWT; you pass it to `Connect-MgGraph` as `-AccessToken`.
- **Graph endpoint** — `Connect-MgGraph` normally targets `https://graph.microsoft.com`. Microsoft.Graph v2.x exposes `-Environment` (for the set of named clouds Microsoft ships) and honours the `MICROSOFT_GRAPH_API_ENDPOINT` environment variable for custom endpoints. Setting that variable to your proxy URL before calling `Connect-MgGraph` points every subsequent cmdlet at the proxy.

<x-doc.callout type="note">
The exact `Connect-MgGraph` override syntax depends on the `Microsoft.Graph` module version. The sample below targets v2.x; recon #214 is the primary source for endpoint-override behaviour. If you are pinned to v1.x, the `-AccessToken` parameter accepts a plain string rather than a `SecureString` — check your module with `Get-Module Microsoft.Graph -ListAvailable`.
</x-doc.callout>

## Complete script (client-credentials flow)

The script below reads three environment variables, acquires a proxy JWT, and runs a single verification call. It is copy-paste runnable once the three variables are set. Inline comments flag the GraphWarden-specific lines.

<x-doc.code-block lang="powershell">
# 1. Configuration — read from the environment, never hardcode secrets.
$ProxyUrl      = $env:GRAPHWARDEN_PROXY_URL      # e.g. https://proxy.example.com
$ClientId      = $env:GRAPHWARDEN_CLIENT_ID      # Proxy Client ID from App Admin
$ClientSecret  = $env:GRAPHWARDEN_CLIENT_SECRET  # Proxy Client Secret from App Admin

if (-not $ProxyUrl -or -not $ClientId -or -not $ClientSecret) {
    throw "Set GRAPHWARDEN_PROXY_URL, GRAPHWARDEN_CLIENT_ID, and GRAPHWARDEN_CLIENT_SECRET before running."
}

# 2. Acquire a proxy JWT via client_credentials against the proxy token endpoint.
#    Authority is the proxy, NOT Azure AD. See recon #210.
$TokenResponse = Invoke-RestMethod `
    -Method Post `
    -Uri "$ProxyUrl/proxy/token" `
    -ContentType 'application/x-www-form-urlencoded' `
    -Body @{
        grant_type    = 'client_credentials'
        client_id     = $ClientId
        client_secret = $ClientSecret
    }

$SecureToken = ConvertTo-SecureString -String $TokenResponse.access_token -AsPlainText -Force

# 3. Point Microsoft.Graph at the proxy BEFORE Connect-MgGraph. The env var is
#    read when the connection is established; setting it afterwards has no effect.
$env:MICROSOFT_GRAPH_API_ENDPOINT = $ProxyUrl

# 4. Connect using the proxy JWT. -NoWelcome suppresses the banner so scripts stay quiet.
Connect-MgGraph -AccessToken $SecureToken -NoWelcome

# 5. Verification call — standard cmdlet, now routed through GraphWarden.
Get-MgUser -Top 1 | Select-Object Id, DisplayName, UserPrincipalName
</x-doc.code-block>

The important line is `Connect-MgGraph -AccessToken $SecureToken`. Everything after that is standard Microsoft.Graph — cmdlets compose request URIs against the endpoint set in `MICROSOFT_GRAPH_API_ENDPOINT`, so `Get-MgUser` issues `GET {proxy-host}/v1.0/users` with the proxy JWT attached.

## Verifying the connection

`Get-MgContext` returns the current connection state. Confirm the endpoint is the proxy, not the public Graph host.

<x-doc.code-block lang="powershell">
$context = Get-MgContext

Write-Host "Account:          $($context.Account)"
Write-Host "AuthType:         $($context.AuthType)"
Write-Host "Graph endpoint:   $([Microsoft.Graph.PowerShell.Authentication.GraphSession]::Instance.GraphEndpoint)"

if ($env:MICROSOFT_GRAPH_API_ENDPOINT -and
    $env:MICROSOFT_GRAPH_API_ENDPOINT -ne 'https://graph.microsoft.com') {
    Write-Host "Routing through GraphWarden: $env:MICROSOFT_GRAPH_API_ENDPOINT"
} else {
    Write-Warning "MICROSOFT_GRAPH_API_ENDPOINT is not set — cmdlets will hit Microsoft Graph directly."
}
</x-doc.code-block>

The `$env:MICROSOFT_GRAPH_API_ENDPOINT` check is the quickest way to catch a forgotten override; the SDK property confirms what the module actually resolved at connection time.

## Running your existing script

Once the connection is established every cmdlet you already use flows through the proxy. You do not rewrite your script — `Get-MgUser`, `New-MgGroup`, `Set-MgUserLicense`, and the other cmdlets compose the same request URIs, and the proxy enforces the ruleset bound to your App Identity on each call.

One reminder: keep the `Connect-MgGraph` call at the top of your script and acquire a fresh proxy JWT on each script run. Proxy JWTs expire after roughly one hour; for long-running scripts, wrap the token acquisition in a helper function that refreshes on 401.

## Troubleshooting

The five failure modes below cover the common onboarding surprises when wiring a PowerShell script against GraphWarden for the first time.

### `AADSTS*` error from `Connect-MgGraph`

The script is still authenticating against Azure AD instead of the proxy — usually because `-AccessToken` was not passed (so `Connect-MgGraph` fell back to interactive / device-code sign-in) or because the Proxy Client ID and Proxy Client Secret are wrong. Verify the two values copied from GraphWarden App Admin match the App Identity for this script, and confirm `Invoke-RestMethod` against `/proxy/token` returned a 200 with an `access_token` field.

### `403 Forbidden` from `Get-MgUser`

A rule in the ruleset bound to your App Identity returned a `block` verdict. The response body names the matched rule. Review the ruleset in GraphWarden App Admin — check the match pattern, the conditions, and the scopes your App Identity was granted. The What-If Simulator replays the request without touching production Graph.

### `502 Bad Gateway`

The proxy is reachable but Microsoft Graph returned a non-2xx upstream response. Check the proxy's health endpoint and Graph's status page; retry with the same payload after a short backoff.

### Cmdlet appears to hit `graph.microsoft.com` directly

The `MICROSOFT_GRAPH_API_ENDPOINT` environment variable was not set before `Connect-MgGraph`, or was set in a parent process that the PowerShell session did not inherit. Run `Get-MgContext` and compare the reported endpoint against the proxy URL. If the variable is missing, set it explicitly in the script (as shown in the sample above) rather than relying on session inheritance.

### PowerShell 5.1 raises a TLS 1.2 error

Windows PowerShell 5.1 defaults to TLS 1.0 / 1.1 on older .NET Framework versions. GraphWarden serves TLS 1.2+. Add the one-liner below before `Invoke-RestMethod`:

<x-doc.code-block lang="powershell">
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
</x-doc.code-block>

PowerShell 7+ negotiates TLS 1.2+ by default and does not need this workaround.

<x-doc.last-reviewed date="2026-04-19" />



## Deploy GraphWarden and make your first proxied Graph call

# Deploy GraphWarden and make your first proxied Graph call

Deploy the GraphWarden proxy on-premises as a Windows Service or in a Docker container, provision one App Identity in the Admin app, and route one Graph call through the proxy. The steps below target a prepared host with Azure AD credentials already set up; expected time is around ten minutes end to end.

<x-doc.status-badge status="supported">On-premises Windows Service path</x-doc.status-badge>

<x-doc.prerequisites>

- Windows Server 2019 or later, OR a Linux or Windows host running Docker
- Access to the GraphWarden Admin app with permission to provision an App Identity
- An Azure AD tenant where you have already registered a Graph application and written its client secret to an Azure Key Vault you operate
- PowerShell 5.1 or later, or .NET 6 or later, for the verification call

</x-doc.prerequisites>

<x-doc.callout type="info">
This quickstart uses the on-premises Windows Service deployment. Hosted customers can skip step 1 — the proxy URL is provided to you and the runtime is managed.
</x-doc.callout>

<x-doc.callout type="note">
The ten-minute target assumes a prepared host with Azure AD credentials already provisioned in Key Vault. First-time Azure AD registration and Key Vault setup take longer and are covered by the trust model and deployment modes concept pages.
</x-doc.callout>

## Step 1: Install the proxy

Download the GraphWarden proxy binary onto your Windows Server host and register it as a Windows Service. Deeper installation coverage — silent installers, upgrade flow, multi-tenant hosts, network hardening — is part of the Phase 2 deployment documentation.

<x-doc.code-block lang="powershell">
# Run in an elevated PowerShell session on the proxy host.
$InstallDir = 'C:\Program Files\GraphWardenProxy'
$ServiceName = 'GraphWardenProxy'

# 1. Copy the release binaries to $InstallDir (done out of band — unzip or MSI).

# 2. Register the Windows Service. Quoting matters when the path contains spaces.
sc.exe create $ServiceName `
    binPath= "`"$InstallDir\GraphProxy.Proxy.exe`"" `
    DisplayName= "GraphWarden Proxy" `
    start= auto

# 3. Start the service.
Start-Service -Name $ServiceName

# 4. Confirm it is listening.
Get-Service -Name $ServiceName
Invoke-WebRequest -UseBasicParsing -Uri http://localhost:5000/health
</x-doc.code-block>

Configuration lives in `appsettings.json` next to the executable. Set `GraphClient:TenantId`, `GraphClient:ClientId`, `KeyVault:VaultUri`, and `ProxyJwt:SigningKey` for a minimal startup. The environment variables page lists every key the proxy reads.

## Step 2: Create an App Identity in the Admin app

The App Identity is the GraphWarden-side record that represents your client application. It carries the proxy credentials your app will send to `/proxy/token` and binds the app to a ruleset.

1. Sign in to the GraphWarden Admin app.
2. Open the ruleset you want to bind this application to. If you have no ruleset yet, create one — it can be a permissive starter ruleset for the smoke test and tightened later.
3. Create a new App Identity. Give it a name that matches the calling application so the audit trail is readable.
4. Copy the Proxy Client ID and Proxy Client Secret the Admin app displays. The secret is shown once; if you lose it you must rotate.
5. Note the proxy URL you will use in step 3. For the on-premises deployment in step 1 this is the host and port Kestrel listens on.

## Step 3: Make the proxied call

The samples below all do the same thing: acquire a proxy JWT from `/proxy/token`, point the Graph client at the proxy URL, and run one verification call against `GET /v1.0/users?$top=1`. Each sample reads the three environment variables you set from the values copied in step 2. Pick the tab for your stack; the per-language deep-dive guides at `../developers/dotnet`, `../developers/nodejs`, `../developers/python`, `../developers/php-laravel`, and `../powershell/quickstart` cover the full integration details.

<x-doc.code-tabs :tabs="[
    [
        'name' => '.NET',
        'lang' => 'csharp',
        'code' => 'using System.Net.Http.Headers;' . PHP_EOL
            . 'using Microsoft.Graph;' . PHP_EOL
            . 'using Microsoft.Identity.Client;' . PHP_EOL
            . PHP_EOL
            . '// GraphWarden-specific: read proxy URL + proxy credentials.' . PHP_EOL
            . 'string proxyUrl     = Environment.GetEnvironmentVariable(\'GRAPHWARDEN_PROXY_URL\')!;' . PHP_EOL
            . 'string clientId     = Environment.GetEnvironmentVariable(\'GRAPHWARDEN_CLIENT_ID\')!;' . PHP_EOL
            . 'string clientSecret = Environment.GetEnvironmentVariable(\'GRAPHWARDEN_CLIENT_SECRET\')!;' . PHP_EOL
            . PHP_EOL
            . '// Authority is the proxy, not login.microsoftonline.com.' . PHP_EOL
            . 'var cca = ConfidentialClientApplicationBuilder.Create(clientId)' . PHP_EOL
            . '    .WithClientSecret(clientSecret)' . PHP_EOL
            . '    .WithAuthority(new Uri($\'{proxyUrl}/proxy/token\'), validateAuthority: false)' . PHP_EOL
            . '    .Build();' . PHP_EOL
            . PHP_EOL
            . 'var token = await cca' . PHP_EOL
            . '    .AcquireTokenForClient(new[] { \'https://graph.microsoft.com/.default\' })' . PHP_EOL
            . '    .ExecuteAsync();' . PHP_EOL
            . PHP_EOL
            . '// GraphWarden-specific: base URL is the proxy.' . PHP_EOL
            . 'var http = new HttpClient { BaseAddress = new Uri(proxyUrl) };' . PHP_EOL
            . 'http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(\'Bearer\', token.AccessToken);' . PHP_EOL
            . PHP_EOL
            . 'var graph = new GraphServiceClient(http);' . PHP_EOL
            . 'var users = await graph.Users.GetAsync(r => { r.QueryParameters.Top = 1; });' . PHP_EOL
            . 'Console.WriteLine(users?.Value?[0].DisplayName);',
    ],
    [
        'name' => 'Node.js',
        'lang' => 'javascript',
        'code' => 'import { ConfidentialClientApplication } from \'@azure/msal-node\';' . PHP_EOL
            . 'import { Client } from \'@microsoft/microsoft-graph-client\';' . PHP_EOL
            . PHP_EOL
            . '// GraphWarden-specific: read proxy URL + proxy credentials.' . PHP_EOL
            . 'const proxyUrl     = process.env.GRAPHWARDEN_PROXY_URL;' . PHP_EOL
            . 'const clientId     = process.env.GRAPHWARDEN_CLIENT_ID;' . PHP_EOL
            . 'const clientSecret = process.env.GRAPHWARDEN_CLIENT_SECRET;' . PHP_EOL
            . PHP_EOL
            . '// Authority + knownAuthorities point MSAL Node at the proxy.' . PHP_EOL
            . 'const pca = new ConfidentialClientApplication({' . PHP_EOL
            . '  auth: {' . PHP_EOL
            . '    clientId,' . PHP_EOL
            . '    clientSecret,' . PHP_EOL
            . '    authority: proxyUrl + \'/proxy/token\',' . PHP_EOL
            . '    knownAuthorities: [new URL(proxyUrl).host],' . PHP_EOL
            . '  },' . PHP_EOL
            . '});' . PHP_EOL
            . PHP_EOL
            . 'const { accessToken } = await pca.acquireTokenByClientCredential({' . PHP_EOL
            . '  scopes: [\'https://graph.microsoft.com/.default\'],' . PHP_EOL
            . '});' . PHP_EOL
            . PHP_EOL
            . '// GraphWarden-specific: baseUrl is the proxy.' . PHP_EOL
            . 'const graph = Client.init({ baseUrl: proxyUrl, authProvider: d => d(null, accessToken) });' . PHP_EOL
            . 'const users = await graph.api(\'/users\').top(1).get();' . PHP_EOL
            . 'console.log(users.value[0].displayName);',
    ],
    [
        'name' => 'Python',
        'lang' => 'python',
        'code' => 'import os' . PHP_EOL
            . 'from azure.identity.aio import ClientSecretCredential' . PHP_EOL
            . 'from msgraph import GraphServiceClient' . PHP_EOL
            . PHP_EOL
            . '# GraphWarden-specific: read proxy URL + proxy credentials.' . PHP_EOL
            . 'proxy_url     = os.environ[\'GRAPHWARDEN_PROXY_URL\']' . PHP_EOL
            . 'client_id     = os.environ[\'GRAPHWARDEN_CLIENT_ID\']' . PHP_EOL
            . 'client_secret = os.environ[\'GRAPHWARDEN_CLIENT_SECRET\']' . PHP_EOL
            . PHP_EOL
            . '# authority = the proxy, not login.microsoftonline.com.' . PHP_EOL
            . 'credential = ClientSecretCredential(' . PHP_EOL
            . '    tenant_id=\'proxy\',' . PHP_EOL
            . '    client_id=client_id,' . PHP_EOL
            . '    client_secret=client_secret,' . PHP_EOL
            . '    authority=proxy_url,' . PHP_EOL
            . ')' . PHP_EOL
            . PHP_EOL
            . '# GraphWarden-specific: host_name override routes every Graph call via the proxy.' . PHP_EOL
            . 'graph = GraphServiceClient(credentials=credential, scopes=[\'https://graph.microsoft.com/.default\'])' . PHP_EOL
            . 'graph.request_adapter.base_url = proxy_url' . PHP_EOL
            . PHP_EOL
            . 'users = await graph.users.get(request_configuration=lambda r: setattr(r.query_parameters, \'top\', 1))' . PHP_EOL
            . 'print(users.value[0].display_name)',
    ],
    [
        'name' => 'PHP',
        'lang' => 'php',
        'code' => '<?php' . PHP_EOL
            . 'require __DIR__ . \'/vendor/autoload.php\';' . PHP_EOL
            . PHP_EOL
            . 'use GuzzleHttp\\Client as GuzzleClient;' . PHP_EOL
            . 'use Microsoft\\Graph\\GraphServiceClient;' . PHP_EOL
            . PHP_EOL
            . '// GraphWarden-specific: read proxy URL + proxy credentials.' . PHP_EOL
            . '$proxyUrl     = getenv(\'GRAPHWARDEN_PROXY_URL\');' . PHP_EOL
            . '$clientId     = getenv(\'GRAPHWARDEN_CLIENT_ID\');' . PHP_EOL
            . '$clientSecret = getenv(\'GRAPHWARDEN_CLIENT_SECRET\');' . PHP_EOL
            . PHP_EOL
            . '// Acquire proxy JWT from the proxy token endpoint.' . PHP_EOL
            . '$http = new GuzzleClient();' . PHP_EOL
            . '$tokenResponse = $http->post($proxyUrl . \'/proxy/token\', [' . PHP_EOL
            . '    \'form_params\' => [' . PHP_EOL
            . '        \'grant_type\'    => \'client_credentials\',' . PHP_EOL
            . '        \'client_id\'     => $clientId,' . PHP_EOL
            . '        \'client_secret\' => $clientSecret,' . PHP_EOL
            . '    ],' . PHP_EOL
            . ']);' . PHP_EOL
            . '$accessToken = json_decode((string) $tokenResponse->getBody())->access_token;' . PHP_EOL
            . PHP_EOL
            . '// GraphWarden-specific: construct Graph client against the proxy base URL.' . PHP_EOL
            . '$graph = new GraphServiceClient($accessToken, $proxyUrl);' . PHP_EOL
            . '$users = $graph->users()->get(fn ($r) => $r->queryParameters->top = 1)->wait();' . PHP_EOL
            . 'echo $users->getValue()[0]->getDisplayName();',
    ],
    [
        'name' => 'PowerShell',
        'lang' => 'powershell',
        'code' => '# 1. Configuration — read from the environment.' . PHP_EOL
            . '$ProxyUrl     = $env:GRAPHWARDEN_PROXY_URL     # e.g. https://proxy.example.com' . PHP_EOL
            . '$ClientId     = $env:GRAPHWARDEN_CLIENT_ID     # Proxy Client ID from the Admin app' . PHP_EOL
            . '$ClientSecret = $env:GRAPHWARDEN_CLIENT_SECRET # Proxy Client Secret from the Admin app' . PHP_EOL
            . PHP_EOL
            . '# 2. Acquire the proxy JWT.' . PHP_EOL
            . '$TokenResponse = Invoke-RestMethod `' . PHP_EOL
            . '    -Method Post `' . PHP_EOL
            . '    -Uri ($ProxyUrl + \'/proxy/token\') `' . PHP_EOL
            . '    -ContentType \'application/x-www-form-urlencoded\' `' . PHP_EOL
            . '    -Body @{' . PHP_EOL
            . '        grant_type    = \'client_credentials\'' . PHP_EOL
            . '        client_id     = $ClientId' . PHP_EOL
            . '        client_secret = $ClientSecret' . PHP_EOL
            . '    }' . PHP_EOL
            . PHP_EOL
            . '# 3. Point Microsoft.Graph at the proxy BEFORE Connect-MgGraph.' . PHP_EOL
            . '$env:MICROSOFT_GRAPH_API_ENDPOINT = $ProxyUrl' . PHP_EOL
            . '$SecureToken = ConvertTo-SecureString -String $TokenResponse.access_token -AsPlainText -Force' . PHP_EOL
            . PHP_EOL
            . '# 4. Connect and run one verification call.' . PHP_EOL
            . 'Connect-MgGraph -AccessToken $SecureToken -NoWelcome' . PHP_EOL
            . 'Get-MgUser -Top 1 | Select-Object Id, DisplayName, UserPrincipalName',
    ],
]" />

The PowerShell quickstart covers the same flow in more depth, including the TLS 1.2 workaround for Windows PowerShell 5.1 and the override variables that let `Invoke-MgGraphRequest` reach the proxy directly. The per-language deep-dive guides explain the SDK-specific wiring (MSAL knownAuthorities for Node, `request_adapter.base_url` for Python, Laravel service-container binding for PHP, `cloud.Configuration.ActiveDirectoryAuthorityHost` for Go).

## Verifying the call hit GraphWarden

Two checks confirm the request went through the proxy rather than bypassing it.

- In the Admin app, open the audit log for your App Identity. You should see one entry for the verification call — timestamp, HTTP method, path, status, and the rule that matched. The correlation ID in the audit row matches the response header the proxy returned to your client.
- The response body itself has the same shape as a direct Graph response. If a `filter` rule applied, specific properties will be absent; if an `allow` rule matched, the body is unchanged.

If the audit log is empty but your script succeeded, the request probably bypassed the proxy and hit Microsoft Graph directly. The troubleshooting section below covers the pattern.

## Troubleshooting

The five failure modes below cover the common first-run surprises.

### Service fails to start — "ProxyJwt:SigningKey is required"

`appsettings.json` is missing the `ProxyJwt:SigningKey` value or left it blank. Set a high-entropy secret of at least 32 characters and restart the service. Do not reuse a staging value in production.

### `Invoke-RestMethod` returns `401 Unauthorized` on `/proxy/token`

The Proxy Client ID or Proxy Client Secret in your environment does not match the hash stored for the App Identity. Confirm both values come from the same Admin app record and that nothing in your pipeline trimmed the secret. Rotate in the Admin app if you suspect the secret was logged or pasted incorrectly.

### Proxy logs show `KeyVault: access denied`

The Managed Identity the proxy runs under 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 an equivalent access policy entry (legacy policy mode). Confirm `KeyVault:VaultUri` points at the vault holding the secret.

### `403 Forbidden` on the verification call despite a valid token

A rule in the bound ruleset returned a `block` verdict. The response body names the matched rule ID. Open the ruleset in the Admin app, review the match pattern and conditions, and use the What-If Simulator to replay the call without hitting Graph.

### The verification call succeeds but the audit log is empty

The request reached Microsoft Graph directly and skipped the proxy. Check that `MICROSOFT_GRAPH_API_ENDPOINT` was set **before** `Connect-MgGraph` (PowerShell) or that `HttpClient.BaseAddress` was set on the `HttpClient` passed to `GraphServiceClient` (.NET). Run `Get-MgContext` to confirm the endpoint resolved to your proxy URL.

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden and GDPR: how the proxy supports your compliance obligations

# GraphWarden and GDPR: how the proxy supports your compliance obligations

The European Union's General Data Protection Regulation (GDPR) imposes strict obligations on organizations processing personal data, covering security, minimization, traceability, and notification. GraphWarden helps meet several GDPR articles by centralizing access control to Microsoft Graph, filtering the data returned, and producing a verifiable audit log. This document maps the main GDPR articles to GraphWarden's capabilities, with explicit limits.

<x-doc.prerequisites title="Who this document is for">

- An organization subject to the GDPR (processing personal data of EU residents, or established in the EU)
- A records of processing activities (ROPA, Art. 30) in place
- Access to the GraphWarden admin application and to your Azure Key Vault
- Intended readers: data protection officer (DPO), CISO, legal and compliance team

</x-doc.prerequisites>

## GDPR context

The GDPR — Regulation (EU) 2016/679 — was adopted in April 2016 and entered into application on 25 May 2018. It applies to any processing of personal data of EU residents, regardless of the controller's location, whenever the processing relates to offering goods or services to individuals in the EU or monitoring their behaviour. The regulation replaces Directive 95/46/EC and harmonizes the data protection regime across the European Union.

Supervision is carried out by national supervisory authorities (the CNIL in France, the Garante in Italy, the BfDI in Germany, the DPC in Ireland, and others), coordinated at the European level by the European Data Protection Board (EDPB). The main pillars of the regulation cover lawfulness of processing (Art. 6), the rights of data subjects (Art. 15 to 22), data protection by design and by default (Art. 25), records of processing activities (Art. 30), security of processing (Art. 32), breach notification (Art. 33 and 34), and data protection impact assessments (DPIA, Art. 35). Administrative fines can reach 20 million euros or 4 percent of annual worldwide turnover, whichever is higher.

## GDPR mapping to GraphWarden capabilities

<x-doc.compliance-mapping
    :mappings="[
        ['article' => 'Art. 5 — Data minimization and purpose limitation principles', 'capability' => 'Graph response filtering (Response Filter transforms)', 'status' => 'aligned', 'proof' => 'Configure a Response Filter to restrict the Graph fields returned to those strictly necessary for the declared purpose.'],
        ['article' => 'Art. 25 — Data protection by design and by default', 'capability' => 'Per-system app identities and versioned YAML rulesets', 'status' => 'aligned', 'proof' => 'Every Graph-integrated application has its own identity with a documented ruleset, enforcing protection by default (minimal access).'],
        ['article' => 'Art. 30 — Records of processing activities (ROPA)', 'capability' => 'YAML rulesets and exportable audit log', 'status' => 'aligned', 'proof' => 'Versioned YAML rulesets and exportable audit logs provide technical artifacts to attach to your records of processing activities.'],
        ['article' => 'Art. 32 — Security of processing', 'capability' => 'Zero-knowledge architecture (Azure Key Vault)', 'status' => 'aligned', 'proof' => 'Graph credentials remain in your Key Vault; GraphWarden holds a get permission only.'],
        ['article' => 'Art. 33-34 — Personal data breach notification', 'capability' => 'HMAC-authenticated audit log', 'status' => 'supported', 'proof' => 'The audit log produces timestamped evidence usable to document the scope of a breach within the regulatory window (72 hours to the supervisory authority).'],
    ]"
    articleHeader="GDPR article"
    capabilityHeader="GraphWarden capability"
    statusHeader="Status"
    proofHeader="Technical proof"
/>

## Concrete scenario

A French SaaS publisher operating in the European Union integrates 8 internal applications with Microsoft 365. Without GraphWarden, each application holds full Graph credentials and can query every endpoint its Azure AD registration permits. With GraphWarden: 8 distinct app identities, each with a ruleset restricting endpoints and returned fields. During a CNIL inspection on the data minimization principle (Art. 5), the publisher produces the YAML rulesets as technical evidence of per-application access limitation, together with the audit log for the inspected time window.

## Hosting and data residency

Hosted tier: the proxy runtime is in **Azure Canada Central**; the control plane runs in **Canada East (OVHCloud)**. On-premise tier (Windows Service or Docker): the proxy runs entirely in your infrastructure — no Graph data leaves your environment, which can contribute to your international-transfer obligations (Chapter V). Graph credentials (client secrets, certificates) never leave your Azure Key Vault: GraphWarden holds only their SHA-256 fingerprint to authenticate calls from your applications.

**EU–Canada adequacy decision.** Canada holds an EU adequacy decision (2014), so transfers from the EU to our Canada-hosted tier do NOT require Standard Contractual Clauses (SCCs). This adequacy simplifies the Chapter V analysis for EU-established controllers that choose our hosted tier.

## Limits

GraphWarden helps meet several GDPR obligations but does not cover the entire regulation. The following items remain your responsibility.

- GraphWarden does NOT cover the legal bases for processing (Art. 6) — lawfulness, consent, and legitimate interest are part of your legal analysis.
- GraphWarden does NOT cover data subject rights (Art. 15 to 22) — access, rectification, erasure, and portability remain your application-level responsibility.
- GraphWarden does NOT perform the data protection impact assessment (DPIA, Art. 35) — the proxy provides technical artifacts, not the assessment.
- GraphWarden does NOT cover international data transfers (Chapter V) — the location of your deployment must be consistent with your post-Schrems II commitments.
- GraphWarden does NOT notify the supervisory authority of personal data breaches — that process (72 hours to the authority, Art. 33; without undue delay to data subjects, Art. 34) remains your responsibility.
- GraphWarden does NOT replace the designation of a data protection officer (DPO, Art. 37 and following).

## Prepare your GDPR brief with an AI assistant

<x-doc.ai-prompt title="Prepare a GDPR compliance brief">
Prepare a GDPR compliance brief for my organization using GraphWarden with Microsoft 365.

I need to deliver to my DPO / GDPR committee:
1. Which GDPR articles GraphWarden helps meet (mapping)
2. Which articles remain under my responsibility (out of scope)
3. The technical artifacts to attach to my file (YAML rulesets, audit logs)

Reference documentation: https://graphwarden.com/llms.txt

Ask me:
- My EU establishment jurisdiction
- How many Graph-integrated applications I have today
- Whether I already have a ROPA and a DPIA in progress
</x-doc.ai-prompt>

## Troubleshooting

- **My ROPA must list every processing activity by purpose — how does GraphWarden help?** Export each YAML ruleset named by purpose; the ruleset name and description serve as ROPA entries. See [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **A supervisory authority asks me to prove access limitation.** Produce the relevant YAML ruleset and the audit log for the requested period through the HMAC endpoint; see [Agent API](/docs/api-reference/agent-api).
- **Schrems II and transfers outside the EU — does GraphWarden change anything?** See the Hosting section above. In on-premise mode inside the EU, no transfer occurs through GraphWarden. In hosted mode, the proxy runs in Canada (Azure Canada Central + Canada East OVHCloud) — Canada holds an EU adequacy decision (2014), so EU-to-Canada transfers do not require SCCs.
- **My breach notification must be filed within 72 hours — how does GraphWarden help scope it?** The HMAC-authenticated audit log lets you identify precisely which Graph calls fall inside a given time window, supporting the scoping of a breach.
- **A partner asks me to demonstrate protection by default (Art. 25).** Git versioning of your YAML rulesets documents your minimal-access decisions as a technical record, usable as evidence of data protection by design and by default.

## Resources

- For deployment, see [On-Premise Windows Installation](/docs/deployment/on-premise-windows).
- For app identities, see [App Identities](/docs/concepts/app-identities).
- For the proxy trust model, see [Trust Model](/docs/concepts/trust-model).
- Data Processing Agreement (DPA) template — <x-doc.status-badge status="planned">coming in Phase 5b</x-doc.status-badge>.

## Next steps

For a demo tailored to your GDPR deployment, [contact the GraphWarden team](/en/contact). Review the [use cases](/en/use-cases) to see how other EU-based organizations have aligned rulesets to their ROPA and DPIA programs. Bring to the session: your EU establishment jurisdiction, your list of Graph-integrated applications, your ROPA review deadline, and the desired audit retention tier (90 days, 1 year, or 7 years).

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden and HIPAA: how the proxy supports your compliance obligations

# GraphWarden and HIPAA: how the proxy supports your compliance obligations

The HIPAA Security Rule imposes administrative, physical, and technical safeguards on covered entities and business associates handling electronic protected health information (ePHI) inside Microsoft 365 and the Graph API. GraphWarden helps address the Technical Safeguards of 45 CFR §164.312 by centralizing access control to Microsoft Graph, producing a verifiable audit trail, and keeping Graph credentials inside your own Azure Key Vault. This document maps each §164.312 standard to GraphWarden's capabilities, with explicit limits on the parts of HIPAA that remain your responsibility.

<x-doc.prerequisites title="Who this document is for">

- A US-based covered entity or business associate processing ePHI through Microsoft 365
- An existing HIPAA risk analysis (§164.308(a)(1)(ii)(A)) and security management process in place
- Access to the GraphWarden admin application and to your Azure Key Vault
- Intended readers: CISO, HIPAA Security Officer, compliance officer, privacy officer

</x-doc.prerequisites>

## HIPAA context

HIPAA — the Health Insurance Portability and Accountability Act of 1996 — is enforced in the United States by the Office for Civil Rights (OCR) of the Department of Health and Human Services. The Security Rule at 45 CFR Part 164 Subpart C imposes three safeguard categories on covered entities and business associates handling electronic protected health information: administrative safeguards (§164.308), physical safeguards (§164.310), and technical safeguards (§164.312).

The Technical Safeguards in §164.312 cover access control, audit controls, integrity, person-or-entity authentication, and transmission security. The HITECH Act of 2009 strengthened these obligations with a federal breach notification framework (§164.404 to §164.414) and increased civil monetary penalties up to 2 million dollars per violation category per year. Business associates are directly liable under HITECH, which means every integration between your Microsoft 365 tenant and a third-party application that touches ePHI falls under a Business Associate Agreement (BAA) regime. GraphWarden addresses the technical surface of that integration.

## HIPAA mapping to GraphWarden capabilities

<x-doc.compliance-mapping
    :mappings="[
        ['article' => '§164.312(a)(1) Access Control', 'capability' => 'Graph endpoint allowlist via ruleset', 'status' => 'aligned', 'proof' => 'Ruleset YAML documents exactly which Graph endpoints each App Identity may reach. Unauthorized calls return 403.'],
        ['article' => '§164.312(a)(2)(i) Unique User Identification', 'capability' => 'App Identity = unique principal per system', 'status' => 'aligned', 'proof' => 'Each integrated application has a dedicated App Identity; proxy audit logs record which identity made each call.'],
        ['article' => '§164.312(b) Audit Controls', 'capability' => 'HMAC-authenticated audit endpoint', 'status' => 'aligned', 'proof' => 'Every proxied Graph call emits an audit event with timestamp, identity, path, status, latency.'],
        ['article' => '§164.312(c)(1) Integrity', 'capability' => 'Response Filter transforms do not modify PHI in transit except where explicitly configured', 'status' => 'supported', 'proof' => 'Any field-level transformation is declared in the ruleset and auditable.'],
        ['article' => '§164.312(d) Person or Entity Authentication', 'capability' => 'OAuth2 client_credentials against Graph, proxy client credentials to the app', 'status' => 'aligned', 'proof' => 'Two-layer credential model; the app never sees real Graph credentials.'],
        ['article' => '§164.312(e)(1) Transmission Security', 'capability' => 'TLS 1.2+ end-to-end', 'status' => 'supported', 'proof' => 'Proxy enforces TLS for inbound and outbound; internal paths go over encrypted channels.'],
    ]"
    articleHeader="HIPAA section"
    capabilityHeader="GraphWarden capability"
    statusHeader="Status"
    proofHeader="Technical proof"
/>

## Concrete scenario

A US regional hospital network runs a Microsoft 365 tenant and integrates a third-party telehealth SaaS. Without GraphWarden, the telehealth vendor holds the Graph credentials and can query every endpoint its Azure AD registration permits, including directory-wide user queries that extend beyond the clinical staff it serves. With GraphWarden, the telehealth App Identity has a ruleset restricting it to the `Clinical-Staff` security group and to the `id`, `displayName`, `mail`, and `jobTitle` fields. During an OCR investigation on §164.312(b) Audit Controls, the hospital produces the YAML ruleset (access-control artifact) and the audit log for the investigation window (identity, timestamp, endpoint, status), satisfying the audit-controls standard for the Graph surface.

## Hosting and data residency

Hosted tier: the proxy runtime is in **Azure Canada Central**; the control plane runs in **Canada East (OVHCloud)**. On-premise tier (Windows Service or Docker) inside your own infrastructure: no ePHI transits through a third-party GraphWarden infrastructure. Graph credentials (client secrets, certificates) never leave your Azure Key Vault: GraphWarden holds only their SHA-256 fingerprint to authenticate calls from your applications.

**Cross-border PHI caveat.** GraphWarden's Hosted tier is in Canada, NOT the United States. Cross-border PHI transfer from a US covered entity to a Canadian-hosted service has Business Associate Agreement (BAA) and data-transfer implications that are the customer's legal analysis — **GraphWarden does not sign HIPAA BAAs for cross-border hosting**. The On-premise tier keeps data in your jurisdiction and is the recommended posture for US covered entities that cannot move ePHI outside the United States.

## Limits

GraphWarden helps address the Technical Safeguards of §164.312 but does not cover the entire HIPAA regime. The following items remain your responsibility.

- GraphWarden does NOT store or process PHI at rest — GraphWarden is a proxy, not a data store; PHI remains in Microsoft 365 and in your integrated applications.
- GraphWarden does NOT replace your Business Associate Agreement obligations — the BAA between your organization and each application vendor (and between you and your GraphWarden deployment contract, if hosted) is yours to negotiate and maintain.
- GraphWarden does NOT file breach notifications under §164.404 — the audit log scopes the incident, but the notification to affected individuals, to HHS, and to the media where applicable remains your responsibility.
- GraphWarden does NOT perform the risk analysis mandated by §164.308(a)(1)(ii)(A) — the proxy provides artifacts (rulesets, audit evidence) that feed the analysis, but the analysis itself remains your responsibility.
- GraphWarden does NOT cover the administrative safeguards of §164.308, including workforce training (§164.308(a)(5)) and sanction policy — these are administrative, not technical.
- GraphWarden does NOT cover the physical safeguards of §164.310 — facility access controls, workstation use, and device controls remain the deploying organization's responsibility.

## Prepare your HIPAA brief with an AI assistant

<x-doc.ai-prompt title="Prepare a HIPAA compliance brief">
Prepare a HIPAA compliance brief for my M365 tenant using GraphWarden, with focus on §164.312 Technical Safeguards.

I need to deliver to my HIPAA Security Officer:
1. Which §164.312 standards GraphWarden helps meet (section-by-section mapping)
2. Which HIPAA obligations remain under my responsibility (out of scope — BAA, breach notification, risk analysis, workforce training)
3. The technical artifacts to attach to my documentation package (YAML rulesets, audit log exports)

Reference documentation: https://graphwarden.com/llms.txt

Ask me:
- Whether I am a covered entity, a business associate, or both
- How many Graph-integrated applications touch ePHI today
- Whether my risk analysis is current and which retention tier my audit log uses
</x-doc.ai-prompt>

## Troubleshooting

- **An OCR auditor asks me to prove access control under §164.312(a)(1).** Produce the relevant YAML ruleset and the audit log for the requested window through the HMAC `/audit` endpoint; see [Agent API](/docs/api-reference/agent-api).
- **My audit log does not show every Graph operation.** Verify that the application actually routes through the proxy (check the `baseUrl` override). A call that bypasses the proxy is not logged — see [App Identities](/docs/concepts/app-identities).
- **My BAA with a vendor requires field-level minimization on a Graph query.** Configure a Response Filter on the App Identity's ruleset to restrict returned fields; see [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **How do I scope a breach notification window?** Filter the HMAC audit export by App Identity and timestamp range for the incident period; the export satisfies the evidentiary part of the §164.404 workflow.
- **Do I still need a BAA with GraphWarden?** GraphWarden does not sign HIPAA BAAs for cross-border hosting — the Hosted tier is in Canada, and the legal analysis for PHI transfers from a US covered entity to a Canadian-hosted service remains your responsibility. On-premise deployments inside your infrastructure do not introduce a new BA relationship because no ePHI transits to a third-party processor — this is the recommended posture for US covered entities.

## Resources

- For deployment, see [On-Premise Windows Installation](/docs/deployment/on-premise-windows).
- For app identities, see [App Identities](/docs/concepts/app-identities).
- For the proxy trust model, see [Trust Model](/docs/concepts/trust-model).
- Data Processing Agreement (DPA) template — <x-doc.status-badge status="planned">coming in a later phase</x-doc.status-badge>.

## Next steps

For a demo tailored to your HIPAA deployment, [contact the GraphWarden team](/en/contact). Review the [use cases](/en/use-cases) to see how other US healthcare organizations have aligned rulesets to their §164.312 documentation. Bring to the session: your covered-entity or business-associate posture, your list of Graph-integrated applications that touch ePHI, your risk-analysis cycle, and the desired audit retention tier (90 days, 1 year, or 7 years).

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden and ISO 27001: how the proxy supports your Annex A controls

# GraphWarden and ISO 27001: how the proxy supports your Annex A controls

ISO/IEC 27001:2022 is the international standard for Information Security Management Systems (ISMS). Clauses 4-10 define the management-system requirements, and Annex A enumerates 93 reference controls organized into four themes: organizational (A.5), people (A.6), physical (A.7), and technological (A.8). For organizations running Microsoft 365 with Graph-integrated applications, several Annex A controls land on the API access surface. GraphWarden helps address those controls by centralizing access to Graph, producing structured audit events, and keeping credentials inside your own Azure Key Vault. This document maps the most relevant Annex A controls to GraphWarden's capabilities, with explicit limits on the parts of ISO 27001 that remain your responsibility.

<x-doc.prerequisites title="Who this document is for">

- An organization implementing or certifying an ISMS to ISO/IEC 27001:2022
- A Statement of Applicability (SoA) draft or revision in progress
- Access to the GraphWarden admin application and to your Azure Key Vault
- Intended readers: CISO, ISMS lead, internal auditor, risk officer

</x-doc.prerequisites>

## ISO 27001 context

ISO/IEC 27001 was first published in 2005 and most recently revised in 2022. The 2022 revision updated the Annex A control catalogue from the 2013 edition (114 controls across 14 categories) to 93 controls organized under four themes (A.5 organizational, A.6 people, A.7 physical, A.8 technological). Certification is issued by accredited certification bodies after a three-stage surveillance cycle: Stage 1 (documentation review), Stage 2 (on-site audit of operating effectiveness), and ongoing surveillance audits until recertification at year three.

The main body of ISO 27001 consists of Clauses 4 through 10, which define the management-system obligations: context of the organization (Cl. 4), leadership (Cl. 5), planning (Cl. 6), support (Cl. 7), operation (Cl. 8), performance evaluation (Cl. 9), and improvement (Cl. 10). Annex A is a reference catalogue of controls; organizations select applicable controls based on their risk assessment and document the selection in a Statement of Applicability (SoA). The companion standard ISO/IEC 27002 provides implementation guidance for each Annex A control. GraphWarden maps most directly to controls in A.5 (organizational), A.8 (technological), and A.12.4 (logging), with supporting relevance to A.9 and A.18.

## ISO 27001 mapping to GraphWarden capabilities

<x-doc.compliance-mapping
    :mappings="[
        ['article' => 'A.5.15 — Access Control', 'capability' => 'Ruleset YAML as access-control policy artifact', 'status' => 'aligned', 'proof' => 'Each ruleset is a versioned policy document mapping App Identities to Graph endpoints.'],
        ['article' => 'A.8.2 — Information Classification', 'capability' => 'Response Filter transforms enforce field-level classification', 'status' => 'supported', 'proof' => 'Fields classified sensitive can be filtered or transformed per ruleset.'],
        ['article' => 'A.8.3 — Information Access Restriction', 'capability' => 'Ruleset denies unauthorized endpoints', 'status' => 'aligned', 'proof' => '403 response for any call not explicitly permitted by the App Identity ruleset.'],
        ['article' => 'A.9.2 — User Access Management', 'capability' => 'App Identity lifecycle tied to Key Vault credential rotation', 'status' => 'supported', 'proof' => 'Credential rotation documented; revocation invalidates all future calls for that identity.'],
        ['article' => 'A.12.4 — Logging and Monitoring', 'capability' => 'HMAC audit events delivered to your SIEM', 'status' => 'aligned', 'proof' => 'All proxied calls produce structured audit events suitable for ISO 27001-compliant log retention.'],
        ['article' => 'A.18.1.3 — Protection of Records', 'capability' => 'Immutable-by-default audit export', 'status' => 'supported', 'proof' => 'Audit records can be exported to WORM storage via the HMAC audit endpoint.'],
    ]"
    articleHeader="Annex A control"
    capabilityHeader="GraphWarden capability"
    statusHeader="Status"
    proofHeader="Technical proof"
/>

## Concrete scenario

An organization pursuing ISO 27001:2022 certification needs to evidence its access-control policy (A.5.15), information access restrictions (A.8.3), and logging and monitoring (A.12.4) for Graph-integrated applications. It operates 11 integrated systems on a Microsoft 365 tenant. The Stage 2 auditor asks for documented access-control decisions and for evidence that the decisions are enforced. The organization produces the 11 App Identity rulesets (access-control artifacts) and a 6-month audit-log export (operating effectiveness evidence). The SoA cites the GraphWarden rulesets as the technical implementation of A.5.15 and A.8.3, and the HMAC audit export as the implementation of A.12.4.

## Hosting and data residency

Hosted tier: the proxy runtime is in **Azure Canada Central**; the control plane runs in **Canada East (OVHCloud)**. On-premise tier (Windows Service or Docker) inside your own infrastructure: processing remains entirely under your control — relevant to the control-of-processing and supplier-relationship considerations your SoA captures. For the Hosted tier, document the tier in the supplier-relationship controls (A.5.19 through A.5.23 in ISO 27001:2022); geography itself is not material to Annex A, but documenting the deployment target is. Graph credentials (client secrets, certificates) never leave your Azure Key Vault: GraphWarden holds only their SHA-256 fingerprint to authenticate calls from your applications.

## Limits

GraphWarden helps address several Annex A controls but does not cover the full ISO 27001 regime. The following items remain your responsibility.

- GraphWarden does NOT cover Clauses 4-10 of the main body — the management-system requirements (context, leadership, planning, support, operation, evaluation, improvement) are entirely the ISMS's responsibility.
- GraphWarden does NOT cover A.6 people controls — recruitment, training, awareness, disciplinary processes, and role definitions are administrative controls.
- GraphWarden does NOT cover A.7 physical controls — facility access, perimeter protection, and physical media handling are physical controls.
- GraphWarden does NOT cover A.17 business continuity beyond the proxy's availability — business continuity planning at the organizational level is your architecture and process responsibility.
- GraphWarden does NOT carry an ISO 27001 attestation — the standard is issued to an ISMS, not to a product. Page-level status is `aligned`, not a formal attestation.
- GraphWarden does NOT manage supplier relationships on your behalf (A.5.19 to A.5.23 in 2022 / A.15 in 2013) — your DPA process, supplier assessment, and contractual controls remain your responsibility.

## Prepare your ISO 27001 brief with an AI assistant

<x-doc.ai-prompt title="Prepare an ISO 27001 compliance brief">
Prepare an ISO 27001 Annex A compliance brief for A.5, A.8, A.9, A.12, A.18 using GraphWarden as a control on M365 Graph access.

I need to deliver to my ISMS lead:
1. Which Annex A controls GraphWarden helps meet (control-by-control mapping)
2. Which controls and clauses remain under my responsibility (out of scope — Clauses 4-10, A.6 people, A.7 physical, A.17 continuity, supplier relationships)
3. The technical artifacts I can attach to my Statement of Applicability (YAML rulesets, audit log export, App Identity inventory)

Reference documentation: https://graphwarden.com/llms.txt

Ask me:
- Whether I am on the ISO 27001:2022 or 2013 control catalogue
- The stage I am at (internal gap assessment, Stage 1, Stage 2, surveillance)
- How many Graph-integrated applications are in the scope of my ISMS
</x-doc.ai-prompt>

## Troubleshooting

- **My auditor asks for evidence of access-control decisions under A.5.15.** Export each ruleset YAML and cite it in the SoA as the technical policy artifact; see [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **My auditor asks for log retention evidence under A.12.4.** Configure the HMAC audit export to forward to your SIEM and apply the retention tier matching your ISMS policy (90 days, 1 year, 7 years); see [Agent API](/docs/api-reference/agent-api).
- **The auditor asks how I handle a supplier whose access I revoked.** Revoke the App Identity in GraphWarden; the revocation invalidates all future calls and is captured in the audit log for the evidence trail.
- **My SoA states we apply A.8.3 at the field level.** Walk through a Response Filter on a representative ruleset; the ruleset is the control's technical artifact.
- **How do I demonstrate that my logging is protected against tampering (A.12.4.2)?** Export audit records to WORM storage via the HMAC endpoint; the append-only target enforces the tamper-evidence requirement.

## Resources

- For deployment, see [On-Premise Windows Installation](/docs/deployment/on-premise-windows).
- For app identities, see [App Identities](/docs/concepts/app-identities).
- For the proxy trust model, see [Trust Model](/docs/concepts/trust-model).
- Data Processing Agreement (DPA) template — <x-doc.status-badge status="planned">coming in a later phase</x-doc.status-badge>.

## Next steps

For a demo tailored to your ISO 27001 deployment, [contact the GraphWarden team](/en/contact). Review the [use cases](/en/use-cases) to see how other organizations have mapped GraphWarden capabilities to their Annex A controls. Bring to the session: your control-catalogue version (2022 or 2013), your current ISMS stage, your list of Graph-integrated applications, and the desired audit retention tier (90 days, 1 year, or 7 years).

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden and Loi 25: how the proxy supports your compliance obligations

# GraphWarden and Loi 25: how the proxy supports your compliance obligations

Quebec's Loi 25 imposes strict obligations on organizations that collect, use, or disclose personal information, including data accessible through Microsoft Graph. GraphWarden acts as a centralized control point to minimize data transmitted, trace every access, and keep Graph authentication credentials inside your own Azure Key Vault. This document maps the key Loi 25 requirements to GraphWarden's technical capabilities, with explicit limits on what GraphWarden does not cover.

<x-doc.prerequisites title="Who this document is for">

- A Microsoft 365 tenant subject to Loi 25 (operations in Quebec)
- A personal information protection policy template in place
- Access to the GraphWarden admin application and to your Azure Key Vault
- Intended readers: CISO, access-to-personal-information officer, legal and compliance team

</x-doc.prerequisites>

## Loi 25 context

Loi 25 — officially the "Act to modernize legislative provisions as regards the protection of personal information" — was passed by Quebec's National Assembly in 2021 (formerly Bill 64). Its provisions came into force in stages from September 2022 to September 2024, with graduated obligations for public bodies and private enterprises operating in Quebec. The law modernizes Quebec's personal information protection regime, aligning it with international standards while preserving specifics of Quebec civil law.

The supervisory authority is the Commission d'accès à l'information du Québec (CAI), which receives complaints, conducts investigations, and publishes guidelines. Key requirements include appointing an access-to-personal-information officer in each organization (Art. 3.1), maintaining a confidentiality incident register (Art. 3.5), minimizing personal information collected and retained (Art. 5), ensuring traceability of disclosures (Art. 8), managing consent (Art. 12–14), the right to data portability (Art. 27), and performing a privacy impact assessment (PIA, known in French as EFVP) before any project involving personal information (Art. 22). Administrative penalties can reach 10 million Canadian dollars or 2 percent of worldwide turnover.

## Loi 25 mapping to GraphWarden capabilities

<x-doc.compliance-mapping
    :mappings="[
        ['article' => 'Art. 5 — Personal information minimization', 'capability' => 'Graph response filtering (Response Filter transforms)', 'status' => 'aligned', 'proof' => 'Configure a Response Filter in your ruleset to restrict the fields returned by Graph to those strictly needed for the operation.'],
        ['article' => 'Art. 8 — Traceability and logging', 'capability' => 'HMAC-authenticated audit log to your SIEM platform', 'status' => 'aligned', 'proof' => 'Every proxied Graph call is recorded with the app identity, path, HTTP status, and latency.'],
        ['article' => 'Art. 3.5 — Confidentiality incident register', 'capability' => 'Scheduled extraction of the audit log', 'status' => 'supported', 'proof' => 'Periodically export the audit log to your incident register via the HMAC /audit endpoint.'],
        ['article' => 'Art. 22 — Privacy impact assessment (PIA / EFVP)', 'capability' => 'Ruleset configuration documented per app identity', 'status' => 'aligned', 'proof' => 'Each app identity has its versioned YAML ruleset documenting the permitted Graph endpoints — a direct artifact for the PIA.'],
    ]"
    articleHeader="Loi 25 article"
    capabilityHeader="GraphWarden capability"
    statusHeader="Status"
    proofHeader="Technical proof"
/>

## Concrete scenario

A Quebec public body operates 12 SaaS applications integrated with Microsoft 365. Without GraphWarden, each application holds full Graph credentials and can query every Graph endpoint authorized on its app registration — including fields that are not strictly necessary for its business use. With GraphWarden: 12 distinct app identities, each with a ruleset restricting endpoints and returned fields. A security incident on one application exposes only that application's ruleset, not the whole tenant. The incident register (Art. 3.5) can pinpoint precisely which identities accessed which endpoints during the exposure window.

## Hosting and data residency

Hosted tier: the proxy runtime is in **Azure Canada Central**; the control plane runs in **Canada East (OVHCloud)**. On-premise tier (Windows Service or Docker): the proxy runs entirely in your infrastructure — no Graph data leaves your environment. For Loi 25 purposes, Canada-based hosting is the gold standard: data stays under Canadian jurisdiction. Graph secrets (client secrets, certificates) never leave your Azure Key Vault: GraphWarden holds only their SHA-256 fingerprint to authenticate calls from your applications.

## Limits

GraphWarden supports several Loi 25 obligations but does not cover the entire regime. The following items remain your responsibility.

- GraphWarden does NOT cover consent requirements (Art. 12–14) — those apply to your application, not the proxy.
- GraphWarden does NOT cover data retention and destruction (Art. 23) — your application remains responsible for lifecycles.
- GraphWarden does NOT cover management of data subject rights (Art. 27 and following) — access, rectification, and portability belong to your application.
- GraphWarden does NOT cover explicit consent requirements for automated decision-making (Art. 12.1).
- GraphWarden does NOT perform the PIA on your behalf — the proxy provides technical artifacts (rulesets, audit logs) but the assessment remains your responsibility.
- GraphWarden does NOT replace your designation of an access-to-personal-information officer (Art. 3.1).

## Prepare your PIA package with an AI assistant

<x-doc.ai-prompt title="Prepare a Loi 25 compliance brief">
Prepare a Loi 25 compliance brief for my Microsoft 365 tenant using GraphWarden.

I need to deliver to my security committee:
1. Which Loi 25 requirements GraphWarden helps meet (article-by-article mapping)
2. Which requirements stay under my responsibility (not covered by GraphWarden)
3. Which technical artifacts I can extract from GraphWarden for my compliance package

Reference documentation: https://graphwarden.com/llms.txt

Ask me:
- How many Microsoft Graph-integrated applications I have today
- Whether I already have a PIA in progress
- My filing deadline
</x-doc.ai-prompt>

## Troubleshooting

- **The audit log does not show every Graph operation.** Verify that the app identity actually routes through the proxy (`Get-MgContext` in PowerShell; inspect the `baseUrl` in .NET). A call that bypasses the proxy is not logged — see [App Identities](/docs/concepts/app-identities).
- **I cannot find the HMAC `/audit` endpoint.** See [Agent API](/docs/api-reference/agent-api) for the HMAC specification and available endpoints.
- **My PIA asks for data geolocation and GraphWarden does not specify it.** See the Hosting section above: in hosted mode the proxy runs in Azure Canada Central and the control plane in Canada East (OVHCloud); in on-premise mode, processing stays entirely inside your infrastructure.
- **One of my rulesets is more permissive than Art. 5 requires.** Revisit the Response Filter and reduce the returned fields; see [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **How do I produce the incident register in the CAI format?** Export the audit log through the HMAC endpoint and filter on `block` verdicts or on the correlation IDs tied to a known incident — see [Agent API](/docs/api-reference/agent-api).

## Resources

- For deployment technical details, see [On-Premise Windows Installation](/docs/deployment/on-premise-windows).
- For credential management, see [App Identities](/docs/concepts/app-identities).
- For the proxy trust model, see [Trust Model](/docs/concepts/trust-model).
- Data Processing Agreement (DPA) template — <x-doc.status-badge status="planned">coming in Phase 5b</x-doc.status-badge>.

## Next steps

For a demo tailored to your Loi 25 deployment, [contact the GraphWarden team](/en/contact). Review the [use cases](/en/use-cases) to see how other organizations subject to Loi 25 have mapped rulesets to their access-officer program. Bring to the session: your list of Graph-integrated applications, your PIA deadline, and the desired audit retention tier (90 days, 1 year, or 7 years).

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden and OWASP API Security Top 10 (2023)

# GraphWarden and OWASP API Security Top 10 (2023)

The OWASP API Security Top 10 is a community-driven list of the ten most critical security risks affecting modern APIs. The 2023 edition (the most recent) updated the 2019 list based on incident data and community input. For organizations exposing Microsoft Graph to internal applications and third-party SaaS vendors, several items in the Top 10 land squarely on the proxy layer. GraphWarden's Response Filter transforms address API3 (Broken Object Property Level Authorization) — the most common Graph finding — and the ruleset model addresses API5 (Broken Function Level Authorization) via per-method restrictions. This document maps each of the ten OWASP risks to GraphWarden's capabilities, with explicit focus on API3 and API5 and explicit limits on what the proxy does not cover.

<x-doc.prerequisites title="Who this document is for">

- An organization performing an API security review of a Microsoft 365-integrated product
- A security engineering team adopting the OWASP API Top 10 as a risk framework
- Access to the GraphWarden admin application and to your Azure Key Vault
- Intended readers: security engineer, AppSec lead, CISO, penetration tester

</x-doc.prerequisites>

## OWASP API Top 10 context

OWASP — the Open Worldwide Application Security Project — maintains several community-driven security resources, including the original Application Security Top 10 (first published in 2003) and the API Security Top 10 (first published in 2019, updated in 2023). The API Top 10 is a risk-awareness list; it is not a certification framework. The 2023 edition covers ten categories: broken object-level authorization (API1), broken authentication (API2), broken object property-level authorization (API3), unrestricted resource consumption (API4), broken function-level authorization (API5), unrestricted access to sensitive business flows (API6), server-side request forgery (API7), security misconfiguration (API8), improper inventory management (API9), and unsafe consumption of APIs (API10).

API3 deserves particular attention for Microsoft Graph deployments. The 2019 edition called this risk Excessive Data Exposure; the 2023 edition renamed and broadened it to Broken Object Property Level Authorization, combining the old Excessive Data Exposure and Mass Assignment risks into one category. In Graph workloads, API3 manifests whenever a Graph response returns more fields than the consuming application strictly requires — for example, a help-desk application that only needs `displayName` and `mail` but receives the full user object. GraphWarden's Response Filter transforms address API3 declaratively at the proxy layer, no application code changes required. For formal assurance, the companion OWASP Application Security Verification Standard (ASVS) provides testable requirements; GraphWarden can be an input to an ASVS assessment but is not the whole program.

## OWASP API Top 10 mapping to GraphWarden capabilities

<x-doc.compliance-mapping
    :mappings="[
        ['article' => 'API1:2023 — Broken Object Level Authorization', 'capability' => 'Ruleset conditions on object_attribute and group_membership', 'status' => 'aligned', 'proof' => 'A rule can limit which Graph objects (users, groups, sites) are reachable based on attributes.'],
        ['article' => 'API2:2023 — Broken Authentication', 'capability' => 'client_credentials flow against proxy; Graph credentials in Key Vault', 'status' => 'aligned', 'proof' => 'The app never handles real Graph credentials; token acquisition flows through the proxy.'],
        ['article' => 'API3:2023 — Broken Object Property Level Authorization', 'capability' => 'Response Filter transforms on specific response properties', 'status' => 'aligned', 'proof' => 'Central GraphWarden capability. Limit returned fields per ruleset — no over-fetching.'],
        ['article' => 'API4:2023 — Unrestricted Resource Consumption', 'capability' => 'rate_limit condition', 'status' => 'supported', 'proof' => 'Ruleset can enforce a per-minute rate limit per App Identity.'],
        ['article' => 'API5:2023 — Broken Function Level Authorization', 'capability' => 'Ruleset action restrictions (allow/block per HTTP method)', 'status' => 'aligned', 'proof' => 'A ruleset can limit which HTTP methods (GET/POST/DELETE) an App Identity may use on each endpoint.'],
        ['article' => 'API6:2023 — Unrestricted Access to Sensitive Business Flows', 'capability' => 'Combined conditions (time_window + rate_limit + caller_identity)', 'status' => 'supported', 'proof' => 'Rulesets can require specific context windows for sensitive operations.'],
        ['article' => 'API7:2023 — Server Side Request Forgery', 'capability' => 'Graph is the only upstream; no user-controlled URL targets', 'status' => 'not-in-scope', 'proof' => 'The proxy connects to Graph only; SSRF vectors are bounded by design.'],
        ['article' => 'API8:2023 — Security Misconfiguration', 'capability' => 'Rulesets are version-controlled YAML', 'status' => 'supported', 'proof' => 'Changes are auditable and reviewable.'],
        ['article' => 'API9:2023 — Improper Inventory Management', 'capability' => 'App Identities and rulesets catalog all Graph consumers', 'status' => 'aligned', 'proof' => 'Explicit inventory of every system integrated to Graph.'],
        ['article' => 'API10:2023 — Unsafe Consumption of APIs', 'capability' => 'GraphWarden consumes Graph API only; upstream is Microsoft', 'status' => 'not-in-scope', 'proof' => 'Application responsibility for downstream consumption of its own dependencies.'],
    ]"
    articleHeader="OWASP API risk"
    capabilityHeader="GraphWarden capability"
    statusHeader="Status"
    proofHeader="Technical proof"
/>

## Concrete scenario

A security engineer reviews an SaaS product that integrates with Microsoft 365 Graph. The review identifies API3 (Broken Object Property Level Authorization) on the product's `/users` query: the product reads the entire user object when it only displays `displayName`, `mail`, and `jobTitle`. Without GraphWarden, remediation requires code changes on the SaaS side. With GraphWarden, the engineer adds a Response Filter on the App Identity ruleset that allowlists those three fields; the proxy strips every other property at the response layer. No code change is required on the SaaS side. A follow-up review adds API5 coverage by restricting the App Identity's method set to `GET` only, blocking writes that would be out of scope for the product's function.

## Hosting and data residency

The data processing location depends on your GraphWarden deployment configuration. In on-premise mode (Windows Service or Docker) inside your own infrastructure, Graph responses are filtered inside your network boundary. In hosted mode, refer to your GraphWarden contract for the applicable deployment region. Graph credentials (client secrets, certificates) never leave your Azure Key Vault: GraphWarden holds only their SHA-256 fingerprint to authenticate calls from your applications. The zero-knowledge credential model directly supports API2 (Broken Authentication) by removing a class of credential-leak risks from the application surface.

## Limits

GraphWarden aligns with several OWASP API Top 10 risks but does not cover every application security concern. The following items remain your responsibility.

- GraphWarden does NOT detect application-layer logic bugs — parameter tampering, IDOR in your app's own code, or missing authorization on your internal endpoints are outside the proxy's view.
- GraphWarden does NOT cover supply-chain risks in your own dependencies — vulnerable packages, transitive CVEs, and outdated runtimes are out of scope.
- GraphWarden does NOT cover API security beyond Microsoft Graph — integrations with other APIs (AWS, Stripe, internal microservices) require their own controls.
- GraphWarden does NOT issue an OWASP API Top 10 certification — the Top 10 is a risk-awareness list, not a certification scheme. Alignment with the Top 10 is not formal compliance.
- GraphWarden does NOT replace an OWASP ASVS program — the Application Security Verification Standard is a broader, testable control set; GraphWarden can be an input but not the whole program.
- GraphWarden does NOT perform penetration testing — the proxy is a preventive control; offensive testing of your applications remains a separate engagement.

## Prepare your OWASP API brief with an AI assistant

<x-doc.ai-prompt title="Prepare an OWASP API Top 10 compliance brief">
Prepare an OWASP API Top 10 (2023) compliance brief for my M365-integrated product using GraphWarden, with focus on API3 and API5.

I need to deliver to my AppSec lead:
1. Which OWASP API Top 10 risks GraphWarden helps address (item-by-item mapping)
2. Which risks remain under my responsibility (out of scope — application-layer logic, supply chain, non-Graph APIs, pen-testing)
3. The technical artifacts I can reference in the review package (YAML rulesets with Response Filter, App Identity inventory, rate-limit configuration)

Reference documentation: https://graphwarden.com/llms.txt

Ask me:
- Which OWASP API risks came back as findings on my current review
- How many Graph-integrated applications are in scope
- Whether I plan to pursue OWASP ASVS verification as a follow-on
</x-doc.ai-prompt>

## Troubleshooting

- **An API3 finding lands on a Graph query — how do I fix it without changing application code?** Add a Response Filter on the App Identity ruleset to allowlist only the required fields; see [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **An API5 finding says my application can call methods it should not.** Restrict the App Identity ruleset's `match.methods` to the allowed HTTP methods (for example, `[GET]` only); anything else returns 403.
- **My pentester asks for an inventory of every Graph consumer (API9).** Export the App Identity list from your GraphWarden admin — each App Identity is an explicit entry in the inventory.
- **I want to rate-limit a specific App Identity (API4).** Add a `rate_limit` condition on the ruleset with `max_requests` and `window_seconds`; see [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **How do I evidence that ruleset changes are reviewable (API8)?** Rulesets live in version control as YAML; every change is reviewable through your Git pull-request process, and the audit log records when the new ruleset went live.

## Resources

- For deployment, see [On-Premise Windows Installation](/docs/deployment/on-premise-windows).
- For app identities, see [App Identities](/docs/concepts/app-identities).
- For the proxy trust model, see [Trust Model](/docs/concepts/trust-model).
- Data Processing Agreement (DPA) template — <x-doc.status-badge status="planned">coming in a later phase</x-doc.status-badge>.

## Next steps

For a demo tailored to your OWASP API review, [contact the GraphWarden team](/en/contact). Review the [use cases](/en/use-cases) to see how other organizations have mapped Response Filter transforms to API3 findings. Bring to the session: your review findings, your list of Graph-integrated applications, the OWASP edition you are targeting (2019 or 2023), and the desired audit retention tier (90 days, 1 year, or 7 years).

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden and PIPEDA: how the proxy supports your compliance obligations

# GraphWarden and PIPEDA: how the proxy supports your compliance obligations

PIPEDA imposes on Canadian private-sector organizations ten Fair Information Principles covering the collection, use, and disclosure of personal information in the course of commercial activities. GraphWarden helps meet several of these principles by centralizing access control to Microsoft Graph, minimizing the data returned, and producing a verifiable audit log. This document maps each of the ten principles to GraphWarden's capabilities, with explicit limits.

<x-doc.prerequisites title="Who this document is for">

- An organization subject to PIPEDA (federal private sector, or operating outside Alberta, British Columbia, and Quebec)
- A personal information protection policy in place
- Access to the GraphWarden admin application and to your Azure Key Vault
- Intended readers: privacy officer, CISO, legal and compliance team

</x-doc.prerequisites>

## PIPEDA context

PIPEDA — the Personal Information Protection and Electronic Documents Act — was enacted by the Parliament of Canada in 2000 and governs how private-sector organizations handle personal information during commercial activities. It rests on ten Fair Information Principles drawn from the Canadian Standards Association's Model Code for the Protection of Personal Information, incorporated as Schedule 1 of the Act. The Office of the Privacy Commissioner of Canada (OPC) oversees enforcement, receives complaints, and publishes guidance.

An interprovincial framework applies: PIPEDA does not cover Quebec (Loi 25), Alberta (PIPA), or British Columbia (PIPA BC), which have enacted laws deemed substantially similar. Bill C-27 proposes a modernization of PIPEDA (Consumer Privacy Protection Act and Personal Information and Data Protection Tribunal); the obligations described here reflect the current regime independently of the ongoing legislative evolution.

## PIPEDA mapping to GraphWarden capabilities

<x-doc.compliance-mapping
    :mappings="[
        ['article' => 'Principle 1 — Accountability', 'capability' => 'Dedicated app identities per integrated system', 'status' => 'aligned', 'proof' => 'Every Graph-integrated application has its own GraphWarden app identity with a versioned YAML ruleset, making responsibilities traceable.'],
        ['article' => 'Principle 2 — Identifying Purposes', 'capability' => 'YAML rulesets documenting permitted endpoints', 'status' => 'aligned', 'proof' => 'Each app identity\'s ruleset explicitly documents the Graph endpoints and authorized fields, serving as a purpose-identification artifact.'],
        ['article' => 'Principle 3 — Consent', 'capability' => 'Not covered by GraphWarden', 'status' => 'not-in-scope', 'proof' => 'Obtaining consent from data subjects is an application-level concern, not a proxy concern.'],
        ['article' => 'Principle 4 — Limiting Collection', 'capability' => 'Response Filter transforms', 'status' => 'aligned', 'proof' => 'Configure a Response Filter to restrict the Graph fields returned to those strictly necessary, enforcing data minimization at the source.'],
        ['article' => 'Principle 5 — Limiting Use, Disclosure, and Retention', 'capability' => 'Endpoint blocking via ruleset', 'status' => 'aligned', 'proof' => 'Block at the ruleset level any Graph endpoint that exceeds the identified purposes.'],
        ['article' => 'Principle 6 — Accuracy', 'capability' => 'Not directly covered', 'status' => 'not-in-scope', 'proof' => 'Accuracy of personal information is an application and internal-process responsibility.'],
        ['article' => 'Principle 7 — Safeguards', 'capability' => 'Graph credentials held in your Azure Key Vault (zero-knowledge architecture)', 'status' => 'aligned', 'proof' => 'GraphWarden holds only a get permission on your Key Vault secrets; Graph credentials never transit through GraphWarden in clear form.'],
        ['article' => 'Principle 8 — Openness', 'capability' => 'Rulesets publishable internally', 'status' => 'supported', 'proof' => 'The YAML ruleset is a human-readable artifact usable in your internal openness policy.'],
        ['article' => 'Principle 9 — Individual Access', 'capability' => 'Not covered by GraphWarden', 'status' => 'not-in-scope', 'proof' => 'Handling access requests (PIPEDA Schedule 1, 4.9) is an application-level responsibility.'],
        ['article' => 'Principle 10 — Challenging Compliance', 'capability' => 'Audit log as technical evidence', 'status' => 'supported', 'proof' => 'The HMAC-authenticated audit log to your SIEM produces verifiable access evidence useful during an investigation by the OPC.'],
    ]"
    articleHeader="PIPEDA principle"
    capabilityHeader="GraphWarden capability"
    statusHeader="Status"
    proofHeader="Technical proof"
/>

## Concrete scenario

A Canadian insurer operates in 9 provinces (excluding Quebec) and integrates a SaaS human-resources system with Microsoft 365. Without GraphWarden, the SaaS vendor holds the Graph credentials and can query all tenant users. With GraphWarden, the SaaS app identity has a ruleset that limits access to members of the `HR-Active` group and to the `displayName`, `mail`, and `jobTitle` fields. During an OPC investigation (Principle 10), the insurer produces the YAML ruleset and the audit log as technical evidence of the access controls in place during the relevant window.

## Hosting and data residency

Hosted tier: the proxy runtime is in **Azure Canada Central**; the control plane runs in **Canada East (OVHCloud)**. On-premise tier (Windows Service or Docker): the proxy runs entirely in your infrastructure — no Graph data leaves your environment. Canada-based hosting keeps your data under Canadian jurisdiction, consistent with the PIPEDA operating perimeter. Graph secrets (client secrets, certificates) never leave your Azure Key Vault: GraphWarden holds only their SHA-256 fingerprint to authenticate calls from your applications.

## Limits

GraphWarden helps meet several PIPEDA principles but does not cover the entire regime. The following items remain your responsibility.

- GraphWarden does NOT cover consent (Principle 3) — that belongs to your application and business processes.
- GraphWarden does NOT cover accuracy of personal information (Principle 6).
- GraphWarden does NOT cover individual access to personal information by data subjects (Principle 9, PIPEDA Schedule 1, 4.9).
- GraphWarden does NOT identify legitimate purposes on your behalf (Principle 2) — the proxy enforces your decision, it does not make it.
- GraphWarden does NOT notify data subjects in case of a privacy breach — that process remains your responsibility.
- GraphWarden does NOT replace your designated privacy officer (Principle 1).

## Prepare your compliance brief with an AI assistant

<x-doc.ai-prompt title="Prepare a PIPEDA compliance brief">
Prepare a PIPEDA compliance brief for my organization using GraphWarden with Microsoft 365.

I need to deliver to my committee:
1. For each of the 10 PIPEDA principles, what GraphWarden helps meet
2. For each principle, what remains under my responsibility
3. The technical artifacts I can extract (rulesets, audit logs)

Reference documentation: https://graphwarden.com/llms.txt

Ask me:
- My province of operation (PIPEDA does not apply in Quebec / Alberta / British Columbia)
- How many Graph-integrated applications I have
- Whether I already have a personal information protection policy
</x-doc.ai-prompt>

## Troubleshooting

- **My organization operates in Quebec — does PIPEDA apply?** No, Loi 25 applies; see [/en/compliance/loi-25](/en/compliance/loi-25).
- **The OPC asks me for a 12-month access log.** See the `/audit` endpoint in [Agent API](/docs/api-reference/agent-api) and configure a periodic export to your archive.
- **How do I demonstrate that my ruleset meets Principle 4 (limiting collection)?** Export the ruleset YAML and attach it as an appendix to the compliance brief.
- **I am receiving data I did not request.** Review the Response Filter in the ruleset; see [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **How do I isolate calls from a compromised application?** Filter the audit log by app identity and by the incident window; see [App Identities](/docs/concepts/app-identities).

## Resources

- For deployment, see [On-Premise Windows Installation](/docs/deployment/on-premise-windows).
- For app identities, see [App Identities](/docs/concepts/app-identities).
- For the proxy trust model, see [Trust Model](/docs/concepts/trust-model).
- Data Processing Agreement (DPA) template — <x-doc.status-badge status="planned">coming in Phase 5b</x-doc.status-badge>.

## Next steps

For a demo tailored to your PIPEDA deployment, [contact the GraphWarden team](/en/contact). Review the [use cases](/en/use-cases) to see how other Canadian private-sector organizations have documented their Fair Information Principles via rulesets. Bring to the session: your province of operation, your list of Graph-integrated applications, and the desired audit retention tier (90 days, 1 year, or 7 years).

<x-doc.last-reviewed date="2026-04-19" />



## GraphWarden and SOC 2: how the proxy supports your Trust Service Criteria

# GraphWarden and SOC 2: how the proxy supports your Trust Service Criteria

SOC 2 reports attest how a service organization designs and operates controls against the AICPA's Trust Service Criteria: Security (mandatory), Availability, Confidentiality, Processing Integrity, and Privacy. For SaaS vendors and cloud service providers integrating with Microsoft 365, the Graph API surface is a frequent source of assessor questions on logical access and data handling. GraphWarden helps address several Trust Service Criteria by centralizing access control to Graph, producing a verifiable audit trail, and keeping Graph credentials inside your own Azure Key Vault. This document maps each criterion to GraphWarden's capabilities, with explicit limits on the parts of SOC 2 that remain your responsibility.

<x-doc.prerequisites title="Who this document is for">

- A service organization preparing a SOC 2 Type I or Type II attestation
- An inventory of systems in scope of the attestation, including M365-integrated applications
- Access to the GraphWarden admin application and to your Azure Key Vault
- Intended readers: CISO, SOC 2 project lead, internal audit, compliance officer

</x-doc.prerequisites>

## SOC 2 context

SOC 2 — System and Organization Controls 2 — is an attestation framework maintained by the AICPA (the American Institute of CPAs). A SOC 2 report is issued by a licensed CPA firm, not by the vendor's customers or by a certification body. Two report types exist: Type I attests design of controls at a point in time; Type II attests operating effectiveness over a period, typically 6 to 12 months. The 2017 Trust Services Criteria (updated in 2022) define five categories — Security (also called Common Criteria, CC), Availability (A), Confidentiality (C), Processing Integrity (PI), and Privacy (P). Security is mandatory; the other four are selected based on commitments to customers.

The Common Criteria include CC1 (control environment), CC2 (communication), CC3 (risk assessment), CC4 (monitoring), CC5 (control activities), CC6 (logical and physical access), CC7 (system operations), CC8 (change management), and CC9 (risk mitigation). Additional criteria under A, C, PI, and P address the specific Trust Service categories the service organization commits to. GraphWarden's technical surface maps most directly to CC6 (logical access), C1 (confidentiality), and P1 (privacy), with supporting relevance to A1 (availability) and PI1 (processing integrity).

## SOC 2 mapping to GraphWarden capabilities

<x-doc.compliance-mapping
    :mappings="[
        ['article' => 'CC6.1 — Logical and Physical Access Controls', 'capability' => 'Rulesets enforce least-privilege Graph access per App Identity', 'status' => 'aligned', 'proof' => 'Each ruleset is a documented access-control artifact, auditable by a SOC 2 assessor.'],
        ['article' => 'A1.1 — Availability', 'capability' => 'Health endpoints and horizontal scale support', 'status' => 'supported', 'proof' => 'Proxy exposes a health check and scales horizontally; continuity is your deployment architecture responsibility.'],
        ['article' => 'C1.1 — Confidentiality', 'capability' => 'Response Filter transforms and Key Vault zero-knowledge credentials', 'status' => 'aligned', 'proof' => 'Credentials remain in your Key Vault; response bodies can be filtered per policy.'],
        ['article' => 'PI1.1 — Processing Integrity', 'capability' => 'Audit trail of every Graph call', 'status' => 'supported', 'proof' => 'Every call captured with method, path, status, and identity — verifiable chain of custody.'],
        ['article' => 'P1.1 — Privacy', 'capability' => 'Data minimization via Response Filter and limited Graph scope via Ruleset', 'status' => 'aligned', 'proof' => 'PII exposure reduced at the API layer by declarative field allowlists and endpoint restrictions.'],
    ]"
    articleHeader="Trust Service Criterion"
    capabilityHeader="GraphWarden capability"
    statusHeader="Status"
    proofHeader="Technical proof"
/>

## Concrete scenario

A SaaS vendor pursuing SOC 2 Type II integrates three M365-connected products into its service offering. The auditors ask for evidence of logical access control on data flowing through third-party APIs under CC6.1, and for a chain-of-custody record for Graph responses served to end users under PI1.1. The vendor produces the three App Identity rulesets (one per product) together with a 9-month export of the audit log, correlated by App Identity and correlation-ID. The rulesets document the access-control policy; the audit log demonstrates operating effectiveness over the Type II window.

## Hosting and data residency

Hosted tier: the proxy runtime is in **Azure Canada Central**; the control plane runs in **Canada East (OVHCloud)**. On-premise tier (Windows Service or Docker) inside your own infrastructure: processing remains entirely under your control, which simplifies the subservice-organization analysis. For a SOC 2 Type II attestation, include the applicable tier (Hosted or On-premise) in your complementary subservice-organization controls (CSOC) section — geography itself is not material to the Trust Service Criteria, but documenting the deployment target is. Graph credentials (client secrets, certificates) never leave your Azure Key Vault: GraphWarden holds only their SHA-256 fingerprint to authenticate calls from your applications.

## Limits

GraphWarden helps address several Trust Service Criteria but does not cover an entire SOC 2 attestation scope. The following items remain your responsibility.

- GraphWarden does NOT cover controls outside the Graph API surface — HR processes, physical security, vendor management, and change management extend beyond the proxy.
- GraphWarden does NOT provide the 6-12 months of evidence a Type II report requires on its own — GraphWarden supplies the mechanisms; evidence collection, retention, and presentation are your responsibility.
- GraphWarden does NOT carry a SOC 2 attestation — a SOC 2 report is issued by a CPA firm to a specific service organization. Page-level status is `aligned`, not a formal attestation.
- GraphWarden does NOT cover Incident Response (CC7.x) — the audit log informs incident scoping, but your incident-response process, communications, and post-incident review remain your responsibility.
- GraphWarden does NOT cover Change Management (CC8.1) end-to-end — ruleset changes are version-controlled and auditable, but your broader change-management program (code deployments, infrastructure changes, third-party integrations) extends beyond the proxy.
- GraphWarden does NOT cover Risk Assessment (CC3) or Control Environment (CC1) — these are organizational controls, not technical ones.

## Prepare your SOC 2 brief with an AI assistant

<x-doc.ai-prompt title="Prepare a SOC 2 compliance brief">
Prepare a SOC 2 compliance brief covering CC6, A1, C1, PI1, and P1 for my M365-integrated product using GraphWarden.

I need to deliver to my SOC 2 project lead:
1. Which Trust Service Criteria GraphWarden helps meet (criterion-by-criterion mapping)
2. Which criteria remain under my responsibility (out of scope — incident response, change management, risk assessment, control environment)
3. The technical artifacts I can export for the assessor package (YAML rulesets, audit log, App Identity inventory)

Reference documentation: https://graphwarden.com/llms.txt

Ask me:
- Type I or Type II attestation and the planned attestation window
- Which Trust Service Criteria I have committed to beyond Security
- How many Graph-integrated applications are in scope
</x-doc.ai-prompt>

## Troubleshooting

- **My auditor asks for evidence of logical access control (CC6.1) on Graph calls.** Export the ruleset YAML and the audit log for the relevant App Identities and period; see [Agent API](/docs/api-reference/agent-api).
- **My auditor asks how we enforce confidentiality (C1.1) at the API layer.** Walk through a Response Filter on a representative ruleset and show the field-level transform; see [Rulesets and Rules](/docs/concepts/rulesets-and-rules).
- **The audit log has a gap during a specific hour.** Check whether the proxy instance restarted or lost connectivity to the audit endpoint; the `heartbeat` cadence helps reconstruct the downtime window — see [Agent API](/docs/api-reference/agent-api).
- **A complementary subservice organization control question lands on us.** The hosting section above captures the CSOC anchor; refer the assessor to your GraphWarden deployment contract for the applicable region.
- **The assessor asks for a list of every system integrated to Graph.** Export the App Identity inventory from your GraphWarden admin — each App Identity is an explicit entry in scope.

## Resources

- For deployment, see [On-Premise Windows Installation](/docs/deployment/on-premise-windows).
- For app identities, see [App Identities](/docs/concepts/app-identities).
- For the proxy trust model, see [Trust Model](/docs/concepts/trust-model).
- Data Processing Agreement (DPA) template — <x-doc.status-badge status="planned">coming in a later phase</x-doc.status-badge>.

## Next steps

For a demo tailored to your SOC 2 deployment, [contact the GraphWarden team](/en/contact). Review the [use cases](/en/use-cases) to see how other SaaS vendors have mapped rulesets to their Trust Service Criteria documentation. Bring to the session: your attestation type (I or II), your committed Trust Service Criteria, your list of Graph-integrated applications, and the desired audit retention tier (90 days, 1 year, or 7 years).

<x-doc.last-reviewed date="2026-04-19" />



## Developer integration (landing)

URL: /docs/developers

Route your applications through GraphWarden without rewriting your Microsoft Graph calls.

Sub-pages:

- Migration guide → /docs/developers/migration-guide
- .NET → /docs/developers/dotnet
- Node.js → /docs/developers/nodejs
- Python → /docs/developers/python
- PHP / Laravel → /docs/developers/php-laravel
- Go → /docs/developers/go


## PowerShell integration (landing)

URL: /docs/powershell

Route Microsoft Graph PowerShell scripts through GraphWarden without changing your cmdlets.

Sub-pages:

- Quickstart → /docs/powershell/quickstart
- Microsoft.Graph module → /docs/powershell/microsoft-graph-module
- Legacy AzureAD / MSOnline → /docs/powershell/legacy-azuread-msonline
- Exchange Online → /docs/powershell/exchange-online
- Cookbook → /docs/powershell/cookbook


## API reference (landing)

URL: /docs/api-reference

Canonical specifications for the GraphWarden proxy, rulesets, and agent API.

Sub-pages:

- Environment variables → /docs/api-reference/environment-variables
- Agent API → /docs/api-reference/agent-api
- Rule schema → /docs/api-reference/rule-schema
- Condition types → /docs/api-reference/condition-types
- Transform types → /docs/api-reference/transform-types


## ISV integration (landing)

URL: /docs/isv

Declare GraphWarden compatibility and support customers who run their Microsoft Graph calls through the proxy.

Sub-pages:

- Why support GraphWarden → /docs/isv/overview
- Compatibility guide → /docs/isv/compatibility-guide
- Compatibility statement → /docs/isv/compatibility-statement
- Certified partners → /docs/isv/certified-partners
- Webhooks and callbacks → /docs/isv/webhooks-and-callbacks


## CI/CD integration (landing)

URL: /docs/ci-cd

Run GraphWarden proxy deployments and automated tests from your CI/CD pipeline.

Sub-pages:

- Azure DevOps → /docs/ci-cd/azure-devops
- GitHub Actions → /docs/ci-cd/github-actions
- Terraform → /docs/ci-cd/terraform
- Secrets management → /docs/ci-cd/secrets-management


## Deployment (landing)

URL: /docs/deployment

Install and operate the GraphWarden proxy on-premises or in hybrid mode.

Sub-pages:

- On-premise (Windows) → /docs/deployment/on-premise-windows
- Docker → /docs/deployment/docker
- Azure Container Apps → /docs/deployment/azure-container-apps
- Networking & firewall → /docs/deployment/networking-firewall
- Sizing → /docs/deployment/sizing


## AI agents (landing)

URL: /docs/ai-agents

Build GraphWarden integrations using Claude Code, Cursor, Copilot, and ChatGPT.

Sub-pages:

- How the docs are built for AI → /docs/ai-agents/overview
- Prompts → /docs/ai-agents/prompts


## Trust (landing)

URL: /en/trust

Zero-knowledge credentials, seven aligned compliance frameworks, audit-ready logging.