Change Request: Add note on how to use package in other Azure clouds in the readme

[ramya-rao-a]

Thank you for contributing to the design guidelines for Azure SDKs. We welcome all discussions and contributions. Since the design guidelines affect the client libraries for all Azure services, we thoroughly discuss and vet any design guideline changes before we incorporate them into the official guidance. This process can take some time, so your patience is appreciated.

** Before submitting, ensure you adjust the title of the issue appropriately **

The Basics

• Which design guideline is affected?

There is no design/implementation guideline for supporting other clouds.

• Which target languages are affected?

All

• Describe the change:

Discussions around this have happened in the past but no guideline was formed yet. This issue is about coming up with one that makes supporting different clouds uniform across the SDK packages.

Reasoning

When a resource's functionality is chunked into small permission sets, third-party apps can be built to request only the permissions that they need to perform their function. In OAuth 2.0, these types of permission sets are called scopes. In the Microsoft identity platform, a permission is represented as a string value. An app requests the permissions it needs by specifying the permission in the scope query parameter. For the purposes of this issue, I will refer to the URL of such requests as the scope string. For more information, please refer to this AAD introduction.

For example, the text analytics scope string for the public Azure cloud is: https://cognitiveservices.azure.com/.default. However, it differs for the US and China sovereign clouds as follows respectively: https://cognitiveservices.azure.us/.default and https://cognitiveservices.azure.cn/.default.

These differences between clouds is not consistent across services. For instance storage uses a unified scope string across all clouds but ARM services use https://management.chinacloudapi.cn for China.

Supporting different clouds in the SDK typically comes down to using the corresponding scope string. However, the guidelines do not explain how to determine the cloud in order for the SDK to use that information to set the corresponding scope string.

Previous discussions:

• Remove AuthenticationScope from ACR ClientOptions #2905
• Change Request: Provide cloud configuration with endpoint information for various clouds #663
• Container Registry exposed an audience client constructor optional parameter that takes an enum to specify the cloud. @jeremymeng

[ramya-rao-a]

cc @AlexGhiondea, @joshfree

[lilyjma]

scheduled for 11/9 2-3pm pst

[tg-msft]

For prior art, I think we've had three ways of approaching this:

1. Services with a global scope across all regions, like Blobs
   We make the scope an internal constant and no public API is exposed.

2. Services that provide a global discovery endpoint, like KeyVault
   We use automatic discovery under the hood and no public API is exposed.

3. Services with regional/federated scopes and no discovery, like ACR
   Today we expose a property on the ClientOptions that defaults to the public cloud's scope. In the future we hope to support it via Add cloud configuration support for azure client libraries #1550 (comment).

[deyaaeldeen]

We agreed on going ahead and working on a design for a way such that the customer can specify the audience cloud either by name for known ones or by a list of configurations. The timeline is not known yet but some libs are going GA early 2022 so having the designs by then would benefit them.

[tg-msft]

Recording[MS INTERNAL ONLY]