[Region] Redesign regional

src/client/Microsoft.Identity.Client/ApiConfig/AcquireTokenForClientParameterBuilder.cs

@@ -72,51 +72,21 @@ public AcquireTokenForClientParameterBuilder WithSendX5C(bool withSendX5C)
         }
 
         /// <summary>
-        /// Specifies if the token request should be sent to regional ESTS.
-        /// If set, MSAL tries to auto-detect and use a regional Azure authority. This helps keep the authentication traffic inside the Azure region. 
-        /// If the region cannot be determined (e.g. not running on Azure), MSALClientException is thrown with error code region_discovery_failed.
-        /// This feature requires configuration at tenant level.
-        /// By default the value for this variable is false.
-        /// See https://aka.ms/msal-net-region-discovery for more details.
+        /// Please use WithAzureRegion on the ConfidentialClientApplicationBuilder object
         /// </summary>
-        /// <param name="useAzureRegion"><c>true</c> if the token request should be sent to regional ESTS. The default is <c>false</c>.
-        /// </param>
-        /// <returns>The builder to chain the .With methods</returns>
-        [Obsolete("This method name has been changed to a more relevant name, please use WithPreferredAzureRegion instead which also includes added features.", true)]
+        [Obsolete("Please use WithAzureRegion on the ConfidentialClientApplicationBuilder object", true)]
         public AcquireTokenForClientParameterBuilder WithAzureRegion(bool useAzureRegion)
         {
-            ValidateUseOfExpirementalFeature();
-
-            CommonParameters.AddApiTelemetryFeature(ApiTelemetryFeature.WithAzureRegion, useAzureRegion);
-            Parameters.AutoDetectRegion = useAzureRegion;
-            return this;
+            throw new NotImplementedException();
         }
 
         /// <summary>
-        /// Specifies if the token request should be sent to regional ESTS.
-        /// If set, MSAL tries to auto-detect and use a regional Azure authority. This helps keep the authentication traffic inside the Azure region. 
-        /// If the region cannot be determined (e.g. not running on Azure), MSALClientException is thrown with error code region_discovery_failed.
-        /// This feature requires configuration at tenant level.
-        /// By default the value for this variable is false.
-        /// See https://aka.ms/msal-net-region-discovery for more details.
-        /// </summary>
-        /// <param name="useAzureRegion"><c>true</c> if the token request should be sent to regional ESTS. The default is <c>false</c>.
-        /// </param>
-        /// <param name="regionUsedIfAutoDetectFails"> optional parameter to provide region to MSAL. This parameter will be used along with auto detection of region.
-        /// If the region is auto detected, the provided region will be compared with the detected region and used in telemetry to do analysis on correctness of the region provided.
-        /// If auto region detection fails, the provided region will be used for instance metadata.</param>
-        /// <param name="fallbackToGlobal"><c>true</c> to fallback to global ESTS endpoint when calls to regional ESTS fail.
-        /// This will only happen when MSAL is not able to detect a region or if there is no provided region.</param>
-        /// <returns>The builder to chain the .With methods</returns>
+        /// Please use WithAzureRegion on the ConfidentialClientApplicationBuilder object
+        /// </summary>        
+        [Obsolete("Please use WithAzureRegion on the ConfidentialClientApplicationBuilder object", true)]
         public AcquireTokenForClientParameterBuilder WithPreferredAzureRegion(bool useAzureRegion = true, string regionUsedIfAutoDetectFails = "", bool fallbackToGlobal = true)
         {
-            ValidateUseOfExpirementalFeature();
-
-            CommonParameters.AddApiTelemetryFeature(ApiTelemetryFeature.WithAzureRegion, useAzureRegion);
-            Parameters.AutoDetectRegion = useAzureRegion;
-            Parameters.RegionToUse = regionUsedIfAutoDetectFails;
-            Parameters.FallbackToGlobal = fallbackToGlobal;
-            return this;
+            throw new NotImplementedException();            
         }
 
         /// <inheritdoc />

src/client/Microsoft.Identity.Client/ApiConfig/Executors/ConfidentialClientExecutor.cs

@@ -59,15 +59,8 @@ public ConfidentialClientExecutor(IServiceBundle serviceBundle, ConfidentialClie
                 requestContext,
                 _confidentialClientApplication.AppTokenCacheInternal);
 
-            if (clientParameters.AutoDetectRegion && requestContext.ServiceBundle.Config.AuthorityInfo.AuthorityType == AuthorityType.Adfs)
-            {
-                throw new MsalClientException(MsalError.RegionDiscoveryNotEnabled, MsalErrorMessage.RegionDiscoveryNotAvailable);
-            }
-
+
             requestParams.SendX5C = clientParameters.SendX5C;
-            requestContext.ServiceBundle.Config.AuthorityInfo.AutoDetectRegion = clientParameters.AutoDetectRegion;
-            requestContext.ServiceBundle.Config.AuthorityInfo.RegionToUse = clientParameters.RegionToUse;
-            requestContext.ServiceBundle.Config.AuthorityInfo.FallbackToGlobal = clientParameters.FallbackToGlobal;
 
             var handler = new ClientCredentialRequest(
                 ServiceBundle,

src/client/Microsoft.Identity.Client/ApiConfig/Parameters/AcquireTokenForClientParameters.cs

@@ -16,28 +16,12 @@ internal class AcquireTokenForClientParameters : IAcquireTokenParameters
         /// </summary>
         public bool SendX5C { get; set; }
 
-        /// <summary>
-        /// When set to true, the request is sent to regional endpoint.
-        /// </summary>
-        public bool AutoDetectRegion { get; set; }
-
-        /// <summary>
-        /// This field wil contain the region provided by user and will be used along with region auto detection.
-        /// </summary>
-        public string RegionToUse { get; set; }
-
-        /// <summary>
-        /// </summary>
-        public bool FallbackToGlobal { get; set; }
-
         /// <inheritdoc />
         public void LogParameters(ICoreLogger logger)
         {
             var builder = new StringBuilder();
             builder.AppendLine("=== AcquireTokenForClientParameters ===");
             builder.AppendLine("SendX5C: " + SendX5C);
-            builder.AppendLine("WithAzureRegion: " + AutoDetectRegion);
-            builder.AppendLine("RegionToUse: " + RegionToUse);
             builder.AppendLine("ForceRefresh: " + ForceRefresh);
             logger.Info(builder.ToString());
         }

src/client/Microsoft.Identity.Client/AppConfig/ConfidentialClientApplicationBuilder.cs

@@ -45,6 +45,12 @@ internal ConfidentialClientApplicationBuilder(ApplicationConfiguration configura
             {
                 builder = builder.WithClientSecret(options.ClientSecret);
             }
+
+            if (!string.IsNullOrWhiteSpace(options.AzureRegion))
+            {
+                builder = builder.WithAzureRegion(options.AzureRegion);
+            }
+
             return builder;
         }
 
@@ -174,6 +180,38 @@ public ConfidentialClientApplicationBuilder WithClientAssertion(Func<string> cli
             return this;
         }
 
+
+        /// <summary>
+        /// Instructs MSAL to use an Azure regional token service using the region given.
+        /// 
+        /// If the calling app knows the region it is deployed to, it should use this information. 
+        /// 
+        /// Otherwise, set the variable to <see cref="ConfidentialClientApplication.AttemptRegionAutoDiscovery"/>, and MSAL will attempt to auto-detect the region. This process
+        /// works on a limited number of Azure artifacts (TBD - which ones!?). If auto-discovery fails, MSAL will use the non-regional service.
+        ///         
+        /// See https://aka.ms/msal-net-region-discovery for more details.
+        /// </summary>
+        /// <param name="azureRegion">A string indicating the azure region, as per https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.management.resourcemanager.fluent.core.region?view=azure-dotnet
+        /// Or <see cref="ConfidentialClientApplication.AttemptRegionAutoDiscovery"/> to have MSAL auto-detect the region.
+        /// </param>
+        /// <remarks>
+        /// Not all flows can use the regional token service. 
+        /// Service To Service (client credential) requests can be obtained from the regional service.
+        /// Requires configuration at the tenant level.
+        /// </remarks>
+        /// <returns>The builder to chain the .With methods</returns>
+        public ConfidentialClientApplicationBuilder WithAzureRegion(string azureRegion = ConfidentialClientApplication.AttemptRegionAutoDiscovery)
+        {
+            if (string.IsNullOrEmpty(azureRegion))
+            {
+                throw new ArgumentNullException(nameof(azureRegion));
+            }
+
+            Config.AzureRegion = azureRegion;
+
+            return this;
+        }
+
         internal ConfidentialClientApplicationBuilder WithAppTokenCacheInternalForTest(ITokenCacheInternal tokenCacheInternal)
         {
             Config.AppTokenCacheInternalForTest = tokenCacheInternal;

src/client/Microsoft.Identity.Client/AppConfig/ConfidentialClientApplicationOptions.cs

@@ -15,5 +15,13 @@ public class ConfidentialClientApplicationOptions : ApplicationOptions
         /// application registration with PowerShell AzureAD, PowerShell AzureRM, or Azure CLI.
         /// </summary>
         public string ClientSecret { get; set; }
+
+        /// <summary>
+        /// Instructs MSAL to use an Azure regional token service using the region given.
+        /// If the calling app knows the region it is deployed to, it should use this information. Region strings are available at https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.management.resourcemanager.fluent.core.region?view=azure-dotnet
+        /// Otherwise, set the variable to "AutoDetect", and MSAL will attempt to auto-detect the region. This process
+        /// works on a limited number of Azure artifacts (TBD - which ones!?). If auto-discovery fails, MSAL will use the non-regional service.
+        /// </summary>
+        public string AzureRegion { get; set; }
     }
 }

src/client/Microsoft.Identity.Client/ConfidentialClientApplication.cs

@@ -37,6 +37,11 @@ public sealed partial class ConfidentialClientApplication
             IConfidentialClientApplicationWithCertificate,
             IByRefreshToken
     {
+        /// <summary>
+        /// Instructs MSAL to try to auto discover the Azure region.
+        /// </summary>
+        public const string AttemptRegionAutoDiscovery = "AutoDetect";
+
         internal ConfidentialClientApplication(
             ApplicationConfiguration configuration)
             : base(configuration)