[@azure/cosmos] Add AAD Scope Override and fallback

[amanrao23]

Packages impacted by this PR

@azure/cosmos

Issues associated with this PR

#36015

Describe the problem that is addressed by this PR

Added support for overriding AAD authentication scope via the new aadScope option in CosmosClientOptions. When no custom scope is provided, the system uses the account-specific scope for authentication and implements a fallback mechanism to https://cosmos.azure.com/.default in case of AADSTS500011 errors. When a custom scope is explicitly provided via the aadScope option, no fallback occurs.

What are the possible designs available to address the problem? If there are more than one possible design, why was the one in this PR chosen?

Are there test cases added in this PR? (If not, why?)

Yes

Provide a list of related PRs (if any)

Command used to generate this PR:**(Applicable only to SDK release request PRs)

Checklists

• Added impacted package name to the issue description
• Does this PR needs any fixes in the SDK Generator?** (If so, create an Issue in the Autorest/typescript repository and link it here)
• Added a changelog (if necessary)

[Copilot]

Pull Request Overview

This PR adds support for AAD scope override functionality to the Azure Cosmos DB client. The implementation allows users to specify a custom AAD authentication scope while providing a fallback mechanism when using the default account-specific scope.

Key changes include:

• Addition of the aadScope option to CosmosClientOptions for custom scope specification
• Implementation of a fallback mechanism from account-specific scope to the default Cosmos scope when encountering AADSTS500011 errors
• Comprehensive test coverage for the new functionality and sample code demonstrating usage

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/CosmosClientOptions.ts	Adds the new aadScope optional property to the client options interface
src/ClientContext.ts	Implements the core authentication logic with scope selection and fallback mechanism
src/common/constants.ts	Defines the default AAD scope constant
src/CosmosClient.ts	Updates JSDoc with example usage of the new AAD scope feature
test/internal/unit/aadScopeOverride.spec.ts	Comprehensive unit tests covering scope selection, fallback behavior, and token handling
test/snippets.spec.ts	Adds a snippet test demonstrating the AAD scope override usage
samples/	Sample files showing practical usage of the AAD scope override feature
review/cosmos-node.api.md	API surface update reflecting the new aadScope option
CHANGELOG.md	Documents the new feature addition

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

@azure/cosmos

[topshot99]

overall LGTM.
added some comments and also check sdk/cosmosdb/cosmos/test/internal/unit/aadScopeOverride.spec.ts
the test cases there is a scope of refactoring them.

[topshot99]