Add configurable Azure Managed token audiences and credential authority

[Bernd Verst (berndverst)]

Summary

What changed?

• Extend the existing .resourceId() / .setResourceId() APIs with normalization and per-options defaults; add connection-string ResourceId and an optional fourth resourceId argument to the client and worker convenience factories. Existing calls remain valid.
• When the audience is missing, null, or empty, use https://durabletask.azure.us for case-insensitive REGION_NAME prefixes usgov / usdod; otherwise retain https://durabletask.io. Explicit audiences take precedence. Do not infer audiences from service endpoints or other cloud regions.
• Trim surrounding whitespace and trailing slashes, remove exactly one case-insensitive /.default suffix, then trim remaining trailing slashes. Preserve URI casing and reject nonempty values that normalize to empty, including whitespace-only connection-string values.
• Add optional connection-string AuthorityHost forwarding to supported SDK-created Azure Identity credentials. Omission preserves Azure Identity defaults, including environment authority configuration where applicable. Caller-supplied credentials own their authority; managed identity and developer-tool cloud configuration remain separate.
• Document the public API, government-cloud sample configuration, authority responsibilities, and migration guidance in the Azure Managed changelog. No package or dependency versions change.

Why is this change needed?

• Enable Azure Government/DoD and custom token audiences without conflating token audience, credential authority/cloud, and scheduler endpoint.
• Resolve the default once per options instance and retain the audience across lazy token acquisition, caching, concurrent refresh, worker reconnects, channel recreation, and worker restarts.

Issues / work items

• Related behavior reference: Add configurable Azure Managed token resource IDs durabletask-python#272 (currently an open PR, not released Python functionality).
• Original .NET guidance: Azure DevOps PR 17297459.
• Python implementation-commit references: regression cases and usage documentation.
• No issue is closed by this PR.

---

Project checklist

• Release notes are not required for the next release
  • Otherwise: Notes added to packages/durabletask-js-azuremanaged/CHANGELOG.md
• Backport is not required
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• All required tests have been added/updated (unit tests, E2E tests)
• Breaking change?
  • If yes:
    • Impact: Missing/null/empty audiences in government or DoD REGION_NAME environments now default to the government audience. Explicit malformed audiences fail during configuration instead of generating invalid token scopes.
    • Migration guidance: Set ResourceId=https://durabletask.io or .resourceId("https://durabletask.io") to retain public-cloud authentication in a government-region environment. Configure authority/cloud and the endpoint independently.

---

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

• No
• Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
• Yes, an AI agent generated most of this PR

If AI was used:

• Tool(s): GitHub Copilot App.
• AI-assisted areas/files: Azure Managed audience and credential configuration, regression tests, package documentation/changelog, and government sample documentation.
• What you changed after AI output: The agent iterated on typed transport test doubles and fake-timer shutdown handling, then reran validation. Human review is pending.

AI verification (required if AI was used; completed by the agent):

• I understand the code and can explain it
• I verified referenced APIs/types exist and are correct
• I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
• I reviewed concurrency/async behavior
• I checked for unintended breaking or behavior changes

---

Testing

Automated tests

• Result: Passed.
• Azure Managed: 804 tests across 10 suites, including recording-credential checks for every options/builder/factory path, all supported connection-string credential types, region/default/override/normalization cases, invalid anonymous input, lazy acquisition, token caching, concurrent refresh, and per-instance default resolution.
• Worker audience recovery: exercise real worker control flow with recording credentials and stubbed gRPC methods through reconnect, channel recreation, and stop/start; verify scopes, task hub/worker metadata, unchanged endpoint, preserved channel credentials, and caller channel options.
• Core transport regressions: 43 tests across 3 suites (worker-startup, worker-stream-recovery, worker-response-delivery-grpc).
• npm run build:core and npm run build:azuremanaged passed, including TypeScript compilation/declaration generation.
• npm run lint, new-test Prettier checks, and git diff --check passed.

Manual validation (only if runtime/behavior changed)

• Environment (OS, Node.js version, components): Windows, Node.js v24.16.0, repository-locked dependencies.
• Steps + observed results:
  1. Inspected existing authentication architecture, Azure Identity constructor options/environment fallback, and the Python/.NET guidance.
  2. Verified actual requested scopes using recording credentials, including refresh and worker transport recovery; no token acquisition is introduced during construction.
  3. Reviewed public documentation and government-cloud configuration examples. No live Azure public/government authentication or cloud deployment was performed.
• Evidence: Automated test/build/lint results above; scope verification is mocked, not proof of live cloud authentication.

---

Notes for reviewers

• Normalization happens only when configuring options. Parsed connection strings retain raw ResourceId values so whitespace-only input is not mistaken for empty input, and successive layers do not strip meaningful repeated /.default URI segments.
• The SDK has one asynchronous client/worker authentication stack and no separate synchronous or sandbox management/registration transports. All applicable JavaScript public authentication paths are covered.
• Token cache and core transport implementations are unchanged; tests guard caching/concurrency, anonymous behavior, and channel configuration preservation.

[Copilot]

Copilot review overview

🟢 Approval recommended

All reviewed changes have corresponding coverage and no unresolved blocking issues were identified.

Review effort: Lite
Findings: None

What changed in this PR

Adds configurable Azure Managed token audiences, authority forwarding, government-cloud defaults, normalization, tests, and documentation.

Changes:

• Adds ResourceId support across options, builders, factories, and connection strings.
• Adds optional AuthorityHost forwarding for supported credentials.
• Adds regression coverage and Azure Government guidance.

File	Summary
packages/​durabletask-js-azuremanaged/​test/​unit/​resource-id.spec.ts	Tests audience defaults and normalization.
packages/​durabletask-js-azuremanaged/​test/​unit/​resource-id-reconnect.spec.ts	Tests persistence across recovery and restart.
packages/​durabletask-js-azuremanaged/​test/​unit/​options.spec.ts	Tests regional audience isolation.
packages/​durabletask-js-azuremanaged/​test/​unit/​credential-factory.spec.ts	Tests credential authority forwarding.
packages/​durabletask-js-azuremanaged/​test/​unit/​connection-string.spec.ts	Tests connection-string parsing.
packages/​durabletask-js-azuremanaged/​src/​worker-builder.ts	Adds worker audience APIs.
packages/​durabletask-js-azuremanaged/​src/​options.ts	Implements audience defaults and normalization.
packages/​durabletask-js-azuremanaged/​src/​credential-factory.ts	Forwards authority configuration.
packages/​durabletask-js-azuremanaged/​src/​connection-string.ts	Parses ResourceId and AuthorityHost.
packages/​durabletask-js-azuremanaged/​src/​client-builder.ts	Adds client audience APIs.
packages/​durabletask-js-azuremanaged/​README.md	Documents public APIs and cloud configuration.
packages/​durabletask-js-azuremanaged/​CHANGELOG.md	Records release notes and migration guidance.
examples/​azure-managed/​README.md	Adds government-cloud configuration guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.