Skip to content

Preserve host-provided management URL query strings - #313

Merged
Naiyuan Tian (nytian) merged 5 commits into
mainfrom
nytian/management-url
Nov 14, 2026
Merged

Naiyuan Tian (nytian) merged 5 commits into
mainfrom
nytian/management-url

Conversation

@nytian

@nytian Naiyuan Tian (nytian) commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Issue describing the changes in this PR

Preserve host-provided Durable Functions management URL query parameters and handle null, empty, or ?-prefixed binding queries without extra URL separators. Keep the existing Location header consistent with the payload's status URL.

Key exclusion is controlled only by the host's httpSettings.excludeManagementKeyFromUrls opt-in, which defaults to false. No Java-specific flag is introduced. Existing applications retain their URL authentication behavior. This SDK does not extract keys, return requiredHeaders, or introduce new cache headers. HTTP callers using key-free URLs must supply an independently obtained key through x-functions-key.

Update compatibility tests, the changelog, and module documentation. Scope E2E credential/origin/redirect handling to authenticated management requests.

Pull request checklist

  • My changes do not require documentation changes
    • Otherwise: Documentation issue linked to PR
  • My changes are added to the CHANGELOG.md
  • I have added all required tests (Unit tests, E2E tests)

Additional information

  • Documentation is updated in the Functions module README; no separate documentation issue has been created.
  • Related host extension change: Keep Durable system keys out of management URLs Azure/azure-functions-durable-extension#3600.
  • The current CI job covers the default mode. Enabling the environment variables alone is insufficient until the host extension bundle supports the option.
  • Follow-up: add an authenticated opt-in Java E2E CI leg after the released host extension bundle supports key exclusion, provisioning its system key separately.
  • .\gradlew.bat :azurefunctions:check :endtoendtests:testClasses -PprotoBranch=3145f9337fca9de57d2f89a6ff6f07150d34f1c2 --offline --no-daemon --console=plain - passed: 47 Functions module unit tests, static checks, and E2E compilation.
  • Local authenticated Docker validation uses the current host extension and independently supplied synthetic system keys; it is separate from the repository's default CI coverage.
  • JDK 11 Docker validation - passed 47 module tests, all 38 E2Es in default mode, all 38 E2Es with the opt-in enabled, and all 17 sample tests.
  • A disposable local HTTP-server probe verified actual 302 behavior: ordinary requests follow redirects, credential-bearing management requests do not, and untrusted management origins are rejected.

@nytian
Naiyuan Tian (nytian) requested a review from a team as a code owner November 11, 2026 22:34
Copilot AI balanced review requested due to automatic review settings November 11, 2026 22:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the change moving management authentication from URL query strings to required headers.

No open issues 🎉

What changed in this PR

This PR moves Durable Functions management authentication from URL query strings to requiredHeaders, reducing system-key exposure in HTTP access logs. Polling clients must now send the returned headers; existing constructor signatures and gRPC operations remain unchanged.

Changes:

  • Generate key-free management URLs and convert legacy code parameters into x-functions-key header metadata.
  • Use key-free Location headers and add Cache-Control: no-store to check-status responses.
  • Add regression coverage and update E2E callers to send authentication headers.
File Description
endtoendtests/​src/​test/​java/​com/​functions/​EndToEndTests.java Sends required headers to validated management endpoints and checks key-free URLs.
azurefunctions/​src/​test/​java/​com/​microsoft/​durabletask/​azurefunctions/​HttpManagementPayloadTest.java Tests legacy-key conversion, header precedence, immutability, and empty queries.
azurefunctions/​src/​test/​java/​com/​microsoft/​durabletask/​azurefunctions/​DurableClientContextTest.java Tests binding credentials, context isolation, key-free locations, and no-store responses.
azurefunctions/​src/​main/​java/​com/​microsoft/​durabletask/​azurefunctions/​HttpManagementPayload.java Separates authentication headers from management URLs while preserving the existing constructor.
azurefunctions/​src/​main/​java/​com/​microsoft/​durabletask/​azurefunctions/​DurableClientContext.java Passes binding headers into payloads and updates check-status response headers.

Review effort: Balanced

@andystaples andystaples left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The core change looks correct and backward compatible. HttpManagementPayload now handles a null, empty, or ?-prefixed binding query without producing a trailing ?, &, or ?null. URLs are unchanged when a query is present, and Location now reuses the payload's status URI. A few items should be addressed before merge (non-blocking):

  1. PR description is out of date. It still describes returning the key through requiredHeaders / x-functions-key, adding Cache-Control: no-store responses, and a breaking change for polling clients. The final diff does none of these, and the tests now assert that requiredHeaders and Cache-Control are absent. The SDK now passes through whatever requiredQueryStringParameters the host provides, and key exclusion is controlled by the host's httpSettings.excludeManagementKeyFromUrls opt-in (default off). That makes this non-breaking for existing apps. The validation notes (45 module tests, E2E 31/36 with entity timeouts) also look like they describe the earlier revision.
  2. CHANGELOG entry is missing. The checklist box is checked, but ## Unreleased only contains the blob-payload entries.
  3. Docs don't cover the opt-in. The README sample still shows ?code= in every management URL. That's accurate for the default, but there's no mention that enabling excludeManagementKeyFromUrls removes code and that callers must then supply the system key via the x-functions-key header. The "do not require documentation changes" box is also unchecked with no linked doc issue.

andystaples
andystaples previously approved these changes Nov 12, 2026

@andystaples andystaples left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the updates. The code, tests, CHANGELOG, and README changes look good, and CI is green. Approving with two non-blocking nits:

  1. PR description: The description still reflects an earlier version of the change. It mentions requiredHeaders/x-functions-key being returned by the SDK, Cache-Control: no-store, a breaking change for polling clients, and the earlier validation counts. Please update it to describe the current behavior: query parameters from the host pass through unchanged, key exclusion is an opt-in host setting, and the default behavior is unchanged. The documentation checkbox can also be checked now that the README covers the opt-in.
  2. Opt-in CI tracking: See the inline note on the README.

Comment thread azurefunctions/README.md
Comment on lines +267 to +268
The repository's CI currently tests the default mode. An authenticated opt-in CI
leg is tracked as a follow-up in the E2E workflow until the released host extension

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: this says the authenticated opt-in CI leg is tracked as a follow-up, but I couldn't find an issue or workflow TODO for it. Could you open an issue and link it here (or in the PR description)? Alternatively, drop the tracking reference from the user-facing README and keep it in the issue.

@nytian Naiyuan Tian (nytian) changed the title Keep Durable Functions system keys out of management URLs Preserve host-provided management URL query strings Nov 13, 2026
@nytian
Naiyuan Tian (nytian) merged commit fd74699 into main Nov 14, 2026
8 checks passed
@nytian
Naiyuan Tian (nytian) deleted the nytian/management-url branch November 14, 2026 00:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants