Summary
Improve and fully document Microsoft Entra ID (formerly Azure AD) authentication and Azure RBAC support in the Azure Cosmos DB Data Migration Tool.
The Cosmos extension README references RBAC/passwordless authentication scenarios, but the current experience is difficult to discover and lacks clear end-to-end documentation and examples for Entra ID-based migration workflows.
Many organizations are moving toward keyless authentication models for security, compliance, and operational governance reasons. Improving the discoverability and usability of Entra ID authentication in the migration tooling would significantly improve adoption in enterprise environments where local authentication is disabled or tightly restricted.
Problem Statement
The current documentation and user experience make it unclear:
- Whether Microsoft Entra ID authentication is fully supported
- Which migration scenarios support RBAC authentication
- How to configure source and destination endpoints using Entra ID
- Whether Managed Identity is supported
- Which Azure Identity credential flows are supported
- Whether support applies to both import and export operations
- What RBAC roles are required
- How authentication behaves in CI/CD and containerized environments
Most examples and configuration guidance still rely on account keys and connection strings, which introduces several challenges:
- Conflicts with enterprise security policies that prohibit shared secrets
- Prevents easy adoption in environments where local auth is disabled
- Requires elevated permissions beyond normal RBAC roles
- Increases operational risk through secret handling and rotation
- Creates friction for Managed Identity automation
- Creates inconsistency with modern Azure SDK authentication patterns
This is especially problematic for:
- Production migrations
- CI/CD automation
- Managed identity workloads
- Cross-subscription/platform engineering scenarios
- Enterprises adopting Zero Trust practices
Requested Improvements
Documentation Improvements
Provide explicit documentation for:
- Microsoft Entra ID authentication setup
- Azure RBAC requirements
- Supported credential flows
- Managed Identity scenarios
- End-to-end migration configuration examples
- Troubleshooting guidance
- Local development authentication flows
- CI/CD authentication guidance
Supported Authentication Flow Documentation
Clarify support for:
DefaultAzureCredential- Azure CLI authenticated sessions
- System-assigned Managed Identity
- User-assigned Managed Identity
- Service Principal authentication
Configuration Examples
Provide concrete examples demonstrating Entra ID authentication usage.
Example desired experience:
cosmos-migration-tool \
--source-endpoint https://source.documents.azure.com \
--destination-endpoint https://dest.documents.azure.com \
--auth-mode entra-id
Example SDK-style authentication pattern:
new CosmosClient(
endpoint,
new DefaultAzureCredential())Expected Benefits
- Reduces dependency on account keys
- Aligns with Azure-wide security guidance
- Enables secure enterprise automation
- Simplifies compliance adoption
- Improves parity with modern Cosmos SDK authentication models
- Reduces operational toil around secret management
- Improves discoverability of existing capabilities
Additional Notes
The Cosmos extension README currently references RBAC/passwordless migration scenarios, which suggests that Entra ID support may already exist in some capacity. However, the current documentation does not provide enough detail for users to confidently adopt these workflows.
Azure Data Factory and Cosmos SDKs already provide strong Entra ID authentication guidance and examples. Providing similar clarity and usability in the Data Migration Tool would create a more consistent platform experience.
This would significantly improve usability for enterprise customers adopting RBAC-first and keyless architectures.
Summary
Improve and fully document Microsoft Entra ID (formerly Azure AD) authentication and Azure RBAC support in the Azure Cosmos DB Data Migration Tool.
The Cosmos extension README references RBAC/passwordless authentication scenarios, but the current experience is difficult to discover and lacks clear end-to-end documentation and examples for Entra ID-based migration workflows.
Many organizations are moving toward keyless authentication models for security, compliance, and operational governance reasons. Improving the discoverability and usability of Entra ID authentication in the migration tooling would significantly improve adoption in enterprise environments where local authentication is disabled or tightly restricted.
Problem Statement
The current documentation and user experience make it unclear:
Most examples and configuration guidance still rely on account keys and connection strings, which introduces several challenges:
This is especially problematic for:
Requested Improvements
Documentation Improvements
Provide explicit documentation for:
Supported Authentication Flow Documentation
Clarify support for:
DefaultAzureCredentialConfiguration Examples
Provide concrete examples demonstrating Entra ID authentication usage.
Example desired experience:
Example SDK-style authentication pattern:
Expected Benefits
Additional Notes
The Cosmos extension README currently references RBAC/passwordless migration scenarios, which suggests that Entra ID support may already exist in some capacity. However, the current documentation does not provide enough detail for users to confidently adopt these workflows.
Azure Data Factory and Cosmos SDKs already provide strong Entra ID authentication guidance and examples. Providing similar clarity and usability in the Data Migration Tool would create a more consistent platform experience.
This would significantly improve usability for enterprise customers adopting RBAC-first and keyless architectures.