Add configurable Azure Managed token resource IDs

[Bernd Verst (berndverst)]

Summary

• Add optional resource_id configuration to the sync/async Azure Managed clients, worker, and preview sandbox client and worker.
• When omitted or empty, select https://durabletask.azure.us when REGION_NAME starts with usgov or usdod (case-insensitive); otherwise retain https://durabletask.io. Explicit values always take precedence.
• Normalize surrounding whitespace, trailing slashes, and an existing /.default suffix before requesting tokens; reject values that become empty. Resolve defaults per instance and preserve the selected audience across refreshes and sandbox registration reconnects.
• Document usage, separate endpoint/credential-authority configuration, and the Azure Managed changelog. No package versions or dependency minimums change.

Authority host configuration

Source inspection confirms that all Azure Managed clients (DurableTaskSchedulerClient, AsyncDurableTaskSchedulerClient, and SandboxActivitiesClient) and the standard DurableTaskSchedulerWorker accept caller-created credentials. They do not construct Azure Identity credentials. token_credential is a required argument, but passing None disables SDK token authentication; it does not create a default credential. Custom implementations of Azure Core's credential protocols are also supported, not just classes from Azure Identity.

No additional authority-host parameter is needed on these clients or the standard worker. They pass the supplied credential through to token managers, which call get_token(scope) or await it. The TokenCredential / AsyncTokenCredential contract has no supported per-request authority override. The SDK supplies the resource scope; the credential owns authority selection.

Verified implementation paths at the feature commit:

• Sync and async clients and standard worker: accept and forward credentials.
• Sandbox client and transport: forward the credential; caller-supplied channels retain responsibility for authentication.
• Token managers: retain the supplied credential and request only the selected scope.
• Sandbox worker credential construction: the sole internal Azure Identity credential construction path is ManagedIdentityCredential(client_id=...) using the injected DTS_UMI_CLIENT_ID. Managed identities use their hosting environment's identity endpoint and ignore the authority setting, so no authority override is needed here either.

Applications can explicitly configure the authority on their credential:

from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
from durabletask.azuremanaged import DurableTaskSchedulerClient

credential = DefaultAzureCredential(
    authority=AzureAuthorityHosts.AZURE_GOVERNMENT,
)

client = DurableTaskSchedulerClient(
    host_address=endpoint,
    taskhub=taskhub,
    token_credential=credential,
    resource_id="https://durabletask.azure.us",
)

Omitting authority preserves Azure Identity's default behavior, including AZURE_AUTHORITY_HOST where applicable. Credentials backed by developer tools use those tools' cloud configuration. The async client follows the same pattern with azure.identity.aio.DefaultAzureCredential.

REGION_NAME selects only the resource audience. Neither it nor resource_id changes the service endpoint or the credential's authority/cloud configuration. The usage documentation now explicitly explains credential ownership, None behavior, custom credential protocols, and the sandbox managed identity exception in addition to the government authority example.

Validation

• 179 targeted tests passed, covering default selection, explicit overrides, normalization, invalid values, sync/async token refresh, public API forwarding, sandbox reconnects, and existing authentication/resiliency regressions.
• Strict Pyright checks passed for the Azure Managed package and new audience tests using CI-style package installs; restored editable installs for runtime tests.
• Flake8 passed separately for Azure Managed source and tests; Markdown lint passed for the updated documentation.
• Follow-up credential-ownership clarification is documentation-only; verified the construction/forwarding paths and Azure Identity authority behavior from source and reran Markdown lint.

Token requests are verified with recording credentials and local test doubles; live Azure Government authentication was not exercised.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Custom-channel sandbox transports bypass resource ID validation and must validate values before the channel branch.

Review effort: Lite
Findings: None

What changed in this PR

Adds configurable Azure Managed token resource IDs with region-aware defaults, normalization, refresh/reconnect preservation, documentation, and tests.

Changes:

• Adds resource_id support across clients, workers, and sandbox components.
• Selects Azure Government defaults and normalizes token scopes.
• Updates tests, documentation, and changelog entries.

File	Reviewed changes
tests/​durabletask-azuremanaged/​test_sandboxes_extension.py	Sandbox audience and reconnect tests.
tests/​durabletask-azuremanaged/​test_resource_id.py	Defaults, overrides, normalization, and refresh tests.
examples/​sandboxes/​README.md	Sandbox audience configuration documentation.
durabletask-azuremanaged/​durabletask/​azuremanaged/​worker.py	Worker resource ID support.
durabletask-azuremanaged/​durabletask/​azuremanaged/​preview/​sandboxes/​worker.py	Audience preservation across reconnects.
durabletask-azuremanaged/​durabletask/​azuremanaged/​preview/​sandboxes/​transport.py	Sandbox transport audience handling.
durabletask-azuremanaged/​durabletask/​azuremanaged/​preview/​sandboxes/​client.py	Sandbox client resource ID support.
durabletask-azuremanaged/​durabletask/​azuremanaged/​internal/​durabletask_grpc_interceptor.py	Token audience forwarding.
durabletask-azuremanaged/​durabletask/​azuremanaged/​internal/​access_token_manager.py	Audience resolution and normalization.
durabletask-azuremanaged/​durabletask/​azuremanaged/​client.py	Sync and async client configuration.
durabletask-azuremanaged/​CHANGELOG.md	User-facing change documentation.
docs/​getting-started.md	Authentication configuration documentation.

---

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

[andystaples]

Reviewed for correctness, API compatibility, and documentation consistency. No actionable findings.

[Bernd Verst (berndverst)]

Token audience selection at a glance

Explicit resource IDs override region defaults. Without an explicit value, case-insensitive usgov/usdod region prefixes select https://durabletask.azure.us; everything else retains https://durabletask.io. The SDK normalizes the resource URI, rejects values that become empty, and requests its /.default scope.

Authority stays on the caller-provided credential; sandbox managed identity uses the hosting environment. Neither resource_id nor REGION_NAME changes the authority or service endpoint.