docs(adr): adr-0026 + reference sample for foundry ai gateway pdp (RFC #2470)#2536
Merged
Merged
Conversation
Implements the 'do now' plan from RFC #2470: - New ADR-0026 documenting the recommended PEP/PDP architecture and the v1.0 decision contract (allow/deny/allow_with_conditions/require_approval, fail-closed default, managed identity + Easy Auth, sha256 input digest, ttlSeconds cache hint, schemaVersion from day one). - New runnable reference sample under examples/foundry-ai-gateway-pdp/ with APIM PEP policy fragment, Python Function PDP, Bicep deployment (APIM + Function App + Easy Auth + named values), and a tiny latency harness. Addresses peer-review blockers: function-level auth combined with Easy Auth (authsettingsV2) wired in Bicep, parameterized Entra app id, APIM policy whitelists allow/allow_with_conditions and denies everything else (including malformed/unknown decisions), set-body JSON built via JObject for correct escaping, README clarifies APIM API import is a deliberate manual step, PDP validates required fields and sha256 digest shape, harness uses nearest-rank percentile. Signed-off-by: Ricky Gummadi <ricky.gummadi@outlook.com>
github-actions
Bot
added
documentation
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.OpenSSF Scorecard
Scanned Files
|
🤖 AI Agent: breaking-change-detector — API CompatibilityAPI CompatibilityNo breaking changes detected. |
🤖 AI Agent: security-scanner — View detailsNo security issues found. |
🤖 AI Agent: docs-sync-checker — Docs SyncDocs SyncDocumentation is in sync. |
PR Review Summary
Verdict: ✅ Ready for human review |
Ricky-G
changed the title
- harness.py: drop hashlib import; use secrets.token_hex(32) to fabricate digest-shaped strings (the PDP only validates shape). Satisfies no-custom-crypto without expanding the allowlist. - .cspell-repo-terms.txt: add APIM, fmean, traceparent. - docs/dependency-audits/2026-05-23-foundry-ai-gateway-pdp-azure-functions.md: dep audit doc for the new azure-functions==1.21.3 pin. Signed-off-by: Ricky Gummadi <ricky.gummadi@outlook.com>
azure-functions is the Microsoft-published Python Functions worker on PyPI (used by examples/foundry-ai-gateway-pdp/function/requirements.txt). Add both hyphen and underscore variants to REGISTERED_PACKAGES so the dependency-confusion scan recognises it. Signed-off-by: Ricky Gummadi <ricky.gummadi@outlook.com>
🤖 AI Agent: code-reviewer — View detailsNo issues found. Clean change. |
Member
|
Approved. Merge conflict from recent merges - can you rebase on main? |
…-ai-gateway-adr # Conflicts: # .cspell-repo-terms.txt
🤖 AI Agent: test-generator — `examples/foundry-ai-gateway-pdp/function/decide/__init__.py`
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the "🟢 Proposing to do now" plan from RFC #2470: lands an ADR documenting the recommended PEP/PDP architecture for closing the Foundry prompt-based agent MCP governance gap, and a runnable reference sample under
examples/that adopters can deploy today with APIM + Azure Functions.Closes the "do now" half of #2470. The
integrations/foundry-ai-gateway/package remains tracked as a separate follow-up pending Foundry product-team alignment.Problem
Foundry prompt-based agents invoke MCP tools from the Foundry backend. Because that path is backend-initiated, MCP tool calls do not naturally traverse the same AI Gateway policy boundary that mediates model traffic. This creates an asymmetric posture: model requests pass through centralized policy enforcement, while MCP tool calls can bypass it. Customers need an Azure-native pattern they can adopt today (without waiting for native Foundry support) that keeps both surfaces inside a unified PEP/PDP boundary with versioned, fail-closed semantics.
Changes
docs/adr/0026-foundry-ai-gateway-functions-pdp.mdallow/deny/allow_with_conditions/require_approval), fail-closed default with explicit opt-in fail-open, managed identity + Easy Auth posture, SHA-256inputDigest(no raw prompts by default),ttlSecondscache hint, andschemaVersionfrom day one.docs/adr/index.mdexamples/foundry-ai-gateway-pdp/README.mdexamples/foundry-ai-gateway-pdp/azure.yamlazdconfig wiring thepdpservice to the Bicep template.examples/foundry-ai-gateway-pdp/infra/main.bicepauthsettingsV2) requiring Entra ID, and APIM (Developer SKU) with the named values consumed by the policy fragment.pdpAadAppIdis a required parameter.examples/foundry-ai-gateway-pdp/policy/pdp-callout.xml<fragment>policy: builds the v1.0 request envelope, calls the PDP viaauthentication-managed-identity, fails closed on transport / schema errors, whitelistsallow/allow_with_conditionsand rejects every other decision (including malformed/unknown).examples/foundry-ai-gateway-pdp/function/decide/__init__.pyschemaVersion, required fields, andsha256:digest shape. Emits structured audit logs (no reservedLogRecordkeys viaextra).examples/foundry-ai-gateway-pdp/function/decide/function.jsonauthLevel: function(defence in depth alongside Easy Auth).examples/foundry-ai-gateway-pdp/function/host.jsonexamples/foundry-ai-gateway-pdp/function/requirements.txtazure-functions==1.21.3.examples/foundry-ai-gateway-pdp/load/harness.pyTesting
Context / Decision / Consequencestemplate and is linked fromdocs/adr/index.md.schemaVersion) end-to-end.azd up+ Easy Auth provisioning intentionally deferred to adopters — production Entra app registration is a customer-owned artifact.Follow-ups (separate issues)
integrations/foundry-ai-gateway/component with a typed PDP SDK — gated on Foundry product-team contract alignment.