Region Discovery Troubleshooting

Feature available from 4.21.1 as an experimental feature. To use this feature there is additional configuration required and is not available to use generally. There can be changes to this API in future as we are taking feedback and updating it based on that. To make sure you have the latest updates to this API use the latest MSAL version.

What is region discovery?

App developers using MSAL don’t need to be aware of the regional endpoints when running their app on Azure. The WithAzureRegion(bool autoDetectRegion) method provides a developer friendly approach to opt in to use reginal endpoints which will be auto detected by MSAL.

How to enable region discovery?

app = ConfidentialClientApplicationBuilder.Create(“client_id”)
.WithCertificate(certificate)
.WithExperimentalFeatures(true)
.WithAuthority(new Uri("https://login.microsoft.com/1234-5678”))
.Build();

var result = app.AcquireTokenForClient(scopes)
    .WithPreferredAzureRegion(
        useAzureRegion: true, // Set to true to opt in to auto region discovery
        regionUsedIfAutoDetectFails: "", // Set the region where the service is deployed if known
        fallbackToGlobal: true).ExecuteAsync(); // Set to true in case you want to use global endpoint in case region detection fails

Note: To enable Auto detection of region WithExperimentalFeatures should be set to true. If it is not set, the following exception is thrown:

The API WithAzureRegion is marked as experimental and you should be mindful about using it in production. It may change without incrementing the major version of the library. Call .WithExperimentalFeatures() when creating the public / confidential client to bypass this. See https://aka.ms/msal-net-experimental-features for details.

Troubleshooting

In case you get the following exception:

MsalClientException: ErrorCode: region_discovery_failed
Microsoft.Identity.Client.MsalClientException: Region discovery for the instance failed. Region discovery can only be made if the service resides in Azure function or Azure VM. 

The region can only be detected when the service is running either in Azure function where the region can be found in Environment variable and fallbackToGlobal is set to false. Or the service is running inside an Azure VM for which a call to Local IMDS is made to detect the region. The above exception comes when region could not be discovered from either way mentioned above. MSAL cannot detect the region in case the service is deployed on Azure cloud services. Make sure to provide region if known using regionUsedIfAutoDetectFails.