Summary

Automatic Azure KMS credentials currently only support Azure VM IMDS. The driver does not support the App Service / Functions / Container Apps local managed identity token service (IDENTITY_ENDPOINT / IDENTITY_HEADER), and there is no official way to specify client_id, principal_id / object_id, or mi_res_id for user-assigned identities when using automatic Azure KMS credentials.

Consumers cannot cleanly work around this with named Azure KMS providers because libmongocrypt rejects empty named-provider documents for on-demand credentials. This leaves common Azure hosting environments without a complete managed identity story for automatic Azure KMS credentials.

Motivation

Who is the affected end user?

Application teams using CSFLE or Queryable Encryption with Azure Key Vault as the KMS provider, especially when running in Azure App Service, Azure Functions, Azure Container Apps, or similar managed-identity environments that are not classic Azure VMs.

Who are the stakeholders?

• the DRIVERS project and language driver teams
• libmongocrypt and CSFLE specification maintainers
• downstream application teams deploying encrypted workloads on Azure
• security-conscious teams that want managed identity instead of client secrets or static credentials

How does this affect the end user?

Affected users are partially blocked.

• they cannot rely on the automatic Azure KMS credential path in common Azure hosting environments outside Azure VMs
• they may be forced to fall back to explicit credentials or startup-time accessToken snapshots
• they may be confused because Azure managed identity support appears to exist, but in practice only the Azure VM IMDS path is supported

How likely is it that this problem or use case will occur?

This is not an edge case.

• system-assigned managed identity in App Service / Functions / Container Apps is a common Azure hosting pattern
• user-assigned identity selection is also a common production requirement when teams separate permissions by workload or environment

For Azure-hosted apps using CSFLE with Azure Key Vault, this is close to a main-path deployment scenario.

If the problem does occur, what are the consequences and how severe are they?

The consequence is functional failure.

• encrypted operations can fail once an explicitly supplied token expires
• teams may need to choose weaker operational patterns, such as managing secrets manually or rebuilding clients before token expiry
• when encryption is on the request path, failures can become application-level unavailability for the affected operations

Severity is medium to high for affected applications because the failure mode is authentication failure against the external KMS, not a minor annoyance or a log-only warning.

Is this issue urgent?

Yes.

It is urgent in the sense that it blocks or degrades a real production-style deployment pattern and pushes users toward brittle or less desirable workarounds.

Is this ticket required by a downstream team?

No known internal MongoDB downstream dependency such as Atlas, Shell, or Compass has been identified from the current context.

However, there is a real downstream consumer need from application teams using the C# driver with CSFLE on Azure-hosted workloads.

Is this ticket only for tests?

No.

This ticket has clear functional impact. Test work will be required, but the issue is not limited to test improvements.

Relationship to DRIVERS-2411

This is best understood as a follow-up to DRIVERS-2411.

DRIVERS-2411 solved:

• Azure VM-assigned managed identity
• Azure IMDS endpoint access
• token caching for automatically acquired Azure KMS credentials

This follow-up would address the next gaps:

• App Service / Functions / Container Apps local token service support
• user-assigned identity selection for automatic Azure KMS credentials
• cleaner official escape hatches for consumers who need Azure SDK-backed token acquisition

Acceptance Criteria

Design is complete when:

• The ticket is owned in DRIVERS and the supported Azure environments are clear.
• The design states how user-assigned identity selection will be handled, or explicitly defers it.
• The design states whether named KMS providers remain unsupported for on-demand credentials.
• Required test coverage is identified for endpoint behaviour and supported Azure environments.

Proposed Solutions (summarised)

• Extend the built-in automatic Azure KMS path to support IDENTITY_ENDPOINT / IDENTITY_HEADER, preserve IMDS fallback, and add official support for user-assigned identity selectors.
• If MongoDB wants a smaller driver-specific fallback, allow replacing the base azure provider so language-specific implementations can use their native Azure SDKs.
• As larger future work, change libmongocrypt and the CSFLE spec to allow empty named KMS providers for on-demand credentials.