[App Configuration] - Add audience error handling policy (#36573)

### Packages impacted by this PR
@azure/app-configuration

### Issues associated with this PR


### Describe the problem that is addressed by this PR

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.




### 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?)_


### 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](https://github.com/Azure/autorest.typescript)
repository and link it here)_
- [ ] Added a changelog (if necessary)

Author: zhiyuanliang-ms

sdk/appconfiguration/app-configuration/src/appConfigurationClient.ts

@@ -56,6 +56,7 @@ import type { PagedAsyncIterableIterator, PagedResult } from "@azure/core-paging
 import { getPagedAsyncIterator } from "@azure/core-paging";
 import type { PipelinePolicy, RestError } from "@azure/core-rest-pipeline";
 import { bearerTokenAuthenticationPolicy } from "@azure/core-rest-pipeline";
+import { audienceErrorHandlingPolicy } from "./internal/audienceErrorHandlingPolicy.js";
 import { SyncTokens, syncTokenPolicy } from "./internal/syncTokenPolicy.js";
 import { queryParamPolicy } from "./internal/queryParamPolicy.js";
 import type { TokenCredential } from "@azure/core-auth";
@@ -196,6 +197,13 @@ export class AppConfigurationClient {
       options?.apiVersion ?? appConfigurationApiVersion,
       internalClientPipelineOptions,
     );
+    this.client.pipeline.addPolicy(
+      audienceErrorHandlingPolicy(appConfigOptions?.audience !== undefined),
+      {
+        phase: "Sign",
+        beforePolicies: [authPolicy.name],
+      },
+    );
     this.client.pipeline.addPolicy(authPolicy, { phase: "Sign" });
     this.client.pipeline.addPolicy(queryParamPolicy());
     this.client.pipeline.addPolicy(syncTokenPolicy(this._syncTokens), { afterPhase: "Retry" });

sdk/appconfiguration/app-configuration/src/internal/audienceErrorHandlingPolicy.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  RestError,
+  type PipelinePolicy,
+  type PipelineRequest,
+  type PipelineResponse,
+  type SendRequest,
+} from "@azure/core-rest-pipeline";
+
+const AadAudienceErrorCode = "AADSTS500011";
+const NoAudienceErrorMessage =
+  "Unable to authenticate to Azure App Configuration. No authentication token audience was provided. Please set AppConfigurationClientOptions.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.";
+const WrongAudienceErrorMessage =
+  "Unable to authenticate to Azure App Configuration. An incorrect token audience was provided. Please set AppConfigurationClientOptions.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.";
+
+/**
+ * Creates a PipelinePolicy that provides more helpful errors when Entra ID audience misconfiguration is detected.
+ */
+export function audienceErrorHandlingPolicy(isAudienceConfigured: boolean): PipelinePolicy {
+  return {
+    name: "audienceErrorHandlingPolicy",
+    async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {
+      try {
+        return await next(request);
+      } catch (error: any) {
+        if (typeof error.message === "string" && error.message.includes(AadAudienceErrorCode)) {
+          if (isAudienceConfigured) {
+            throw new RestError(WrongAudienceErrorMessage);
+          } else {
+            throw new RestError(NoAudienceErrorMessage);
+          }
+        }
+        throw error;
+      }
+    },
+  };
+}

sdk/appconfiguration/app-configuration/test/internal/audienceErrorHandlingPolicy.spec.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { describe, it, expect } from "vitest";
+import {
+  createEmptyPipeline,
+  createPipelineRequest,
+  createDefaultHttpClient,
+  type PipelinePolicy,
+} from "@azure/core-rest-pipeline";
+import { audienceErrorHandlingPolicy } from "../../src/internal/audienceErrorHandlingPolicy.js";
+
+describe("audienceErrorHandlingPolicy", () => {
+  function buildPipelineWithThrowingPolicy(isAudienceConfigured: boolean, thrownError: Error) {
+    const pipeline = createEmptyPipeline();
+
+    const throwingPolicy: PipelinePolicy = {
+      name: "throwingPolicy",
+      async sendRequest() {
+        throw thrownError;
+      },
+    };
+
+    // audienceErrorHandlingPolicy should wrap errors coming from later policies
+    pipeline.addPolicy(audienceErrorHandlingPolicy(isAudienceConfigured));
+    pipeline.addPolicy(throwingPolicy);
+
+    return pipeline;
+  }
+
+  it("throws helpful RestError when AAD audience error occurs and audience is not configured", async () => {
+    const originalError = new Error(
+      "Some auth failure including AADSTS500011: No resource matches the audience",
+    );
+
+    const pipeline = buildPipelineWithThrowingPolicy(false, originalError);
+    const httpClient = createDefaultHttpClient();
+    const request = createPipelineRequest({ url: "https://example.com" });
+
+    await expect(pipeline.sendRequest(httpClient, request)).rejects.toMatchObject({
+      message: expect.stringMatching(/No authentication token audience was provided/),
+      name: "RestError",
+    });
+  });
+
+  it("throws helpful RestError when AAD audience error occurs and audience is configured", async () => {
+    const originalError = new Error(
+      "Some auth failure including AADSTS500011: Invalid resource for this tenant",
+    );
+
+    const pipeline = buildPipelineWithThrowingPolicy(true, originalError);
+    const httpClient = createDefaultHttpClient();
+    const request = createPipelineRequest({ url: "https://example.com" });
+
+    await expect(pipeline.sendRequest(httpClient, request)).rejects.toMatchObject({
+      message: expect.stringMatching(/An incorrect token audience was provided/),
+      name: "RestError",
+    });
+  });
+
+  it("rethrows non-AAD audience errors unchanged", async () => {
+    const originalError = new Error("Network timeout, no AADSTS code here");
+
+    const pipeline = buildPipelineWithThrowingPolicy(true, originalError);
+    const httpClient = createDefaultHttpClient();
+    const request = createPipelineRequest({ url: "https://example.com" });
+
+    await expect(pipeline.sendRequest(httpClient, request)).rejects.toBe(originalError);
+  });
+});