[App Configuration] - Add audience error handling policy #53834
+63 −1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
github-actions bot added the App Configuration Copilot finished reviewing on behalf of zhiyuanliang-ms November 12, 2025 07:37
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds improved error handling for audience configuration issues in the Azure App Configuration SDK. When users in non-public clouds fail to configure or misconfigure the ConfigurationClientOptions.Audience, they now receive clearer error messages that guide them to the appropriate documentation.
Key Changes:
- Adds
AudienceErrorHandlingPolicyto intercept AADSTS500011 authentication errors and provide context-specific guidance - Integrates the new policy into the HTTP pipeline
- Adds
Azure.Identitypackage dependency forAuthenticationFailedException
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
sdk/appconfiguration/Azure.Data.AppConfiguration/src/AudienceErrorHandlingPolicy.cs | New pipeline policy that catches audience-related authentication failures and rethrows with improved error messages |
sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs | Integrates the new policy into the HTTP pipeline (contains critical bugs) |
sdk/appconfiguration/Azure.Data.AppConfiguration/src/Azure.Data.AppConfiguration.csproj | Adds Azure.Identity package reference for AuthenticationFailedException |
sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs Outdated Show resolved Hide resolved
sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs Outdated Show resolved Hide resolved
zhiyuanliang-ms force-pushed the zhiyuanliang/audience-error branch from be14225 to 530f325 Compare 
API Change CheckAPIView identified API level changes in this PR and created the following API reviews |
zhiyuanliang-ms commented Nov 12, 2025
sdk/appconfiguration/Azure.Data.AppConfiguration/src/AudienceErrorHandlingPolicy.cs Outdated Show resolved Hide resolved
zhiyuanliang-ms commented Nov 12, 2025
sdk/appconfiguration/Azure.Data.AppConfiguration/src/Azure.Data.AppConfiguration.csproj Outdated Show resolved Hide resolved
jimmyca15 reviewed Nov 12, 2025
sdk/appconfiguration/Azure.Data.AppConfiguration/src/AudienceErrorHandlingPolicy.cs Outdated Show resolved Hide resolved
jimmyca15 reviewed Nov 12, 2025
sdk/appconfiguration/Azure.Data.AppConfiguration/src/AudienceErrorHandlingPolicy.cs Outdated Show resolved Hide resolved
jimmyca15 reviewed Nov 12, 2025
| } | ||
| | ||
| string message = _isAudienceConfigured ? WrongAudienceErrorMessage : NoAudienceErrorMessage; | ||
| throw new AuthenticationFailedException(message, ex); |
Member
There was a problem hiding this comment.
Keep the throw statement in the catch block only. If a helper is needed, return any state back to the catch block and throw.
Otherwise it's not clear that there are multiple throw paths.
zhiyuanliang-ms commented Nov 13, 2025
sdk/appconfiguration/Azure.Data.AppConfiguration/src/AudienceErrorHandlingPolicy.cs Show resolved Hide resolved
jimmyca15 reviewed Nov 13, 2025
| { | ||
| ProcessNext(message, pipeline); | ||
| } | ||
| catch (Exception ex) |
avanigupta reviewed Nov 13, 2025
| { | ||
| private readonly bool _isAudienceConfigured; | ||
| private const string AadAudienceErrorCode = "AADSTS500011"; | ||
| private const string NoAudienceErrorMessage = "Unable to authenticate to Azure App Configuration. No authentication token audience was provided. Please set ConfigurationClientOptions.Audience to the appropriate audience for the target cloud. For details on how to configure the authentication token audience visit https://aka.ms/appconfig/client-token-audience."; |
Member
There was a problem hiding this comment.
Use nameof(ConfigurationClientOptions.Audience)
avanigupta reviewed Nov 13, 2025
| { | ||
| await ProcessNextAsync(message, pipeline).ConfigureAwait(false); | ||
| } | ||
| catch (Exception ex) |
Member
There was a problem hiding this comment.
Do we need to catch base Exception or can we catch AuthenticationFailedException/MsalServiceException?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
Users running in clouds other than the public cloud must correctly configure ConfigurationClientOptions.Audience when using the ConfigurationClient from the Azure SDK.
There are two main ways users can misconfigure
They do not specify audience when they are running in non-public cloud
They specify audience, and the audience they specify is the wrong one for the cloud is using
In both cases we will get an error when trying to get an Entra ID token that looks like:
"Microsoft.Identity.Client.MsalServiceException: AADSTS500011: The resource principal named https://appconfig.azure.com was not found in the tenant named msazurecloud. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant."
We should handle this error and surface up an improved error message
Audience not provided
If we get this error and audience is not provided we should surface an error message that says audience should be configured and link to our public doc that documents the appropriate audience for each cloud
Audience provided and incorrect
If we get this error and the audience is provided but is wrong, we should surface an error message that the configured audience is wrong and link to our public doc that documents the appropriate audience for each cloud.