[AppConfig] Added Audience Scope support (#44539)

* introduce ConfigurationAudience

* added the configuration audience scope

* added unit tests

* Entra instead of EntraID

* renaming

* remove unnecessary changes

* replace aad by entra

Author: mssfang

sdk/appconfiguration/azure-data-appconfiguration/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Added support for specifying the token credential's Microsoft Entra audience when creating a client.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/appconfiguration/azure-data-appconfiguration/README.md

@@ -80,7 +80,7 @@ az appconfig create --name <config-store-name> --resource-group <resource-group-
 ### Authenticate the client
 
 In order to interact with the App Configuration service you'll need to create an instance of the Configuration Client 
-class. To make this possible you'll need the connection string of the Configuration Store. Alternatively, use AAD token
+class. To make this possible you'll need the connection string of the Configuration Store. Alternatively, use Entra token
 to connect to the service.
 
 #### Use connection string
@@ -113,7 +113,7 @@ ConfigurationAsyncClient configurationClient = new ConfigurationClientBuilder()
     .buildAsyncClient();
 ```
 
-#### Use AAD token
+#### Use Entra token
 
 Here we demonstrate using [DefaultAzureCredential][default_cred_ref]
 to authenticate as a service principal. However, the configuration client
@@ -162,7 +162,7 @@ configuration client.
 Constructing the client also requires your configuration store's URL, which you can
 get from the Azure CLI or the Azure Portal. In the Azure Portal, the URL can be found listed as the service "Endpoint".
 
-```java readme-sample-aadAuthentication
+```java readme-sample-entraAuthentication
 DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
 ConfigurationClient configurationClient = new ConfigurationClientBuilder()
     .credential(credential)

sdk/appconfiguration/azure-data-appconfiguration/TROUBLESHOOTING.md

@@ -41,7 +41,7 @@ ConfigurationClient configurationClient = new ConfigurationClientBuilder()
         .buildClient();
 // or
 DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
-ConfigurationClient configurationClientAad = new ConfigurationClientBuilder()
+ConfigurationClient configurationClientEntraId = new ConfigurationClientBuilder()
         .credential(credential)
         .endpoint(endpoint)
         .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))

sdk/appconfiguration/azure-data-appconfiguration/src/main/java/com/azure/data/appconfiguration/ConfigurationAsyncClient.java

@@ -71,7 +71,7 @@
  *
  * <p>In order to interact with the App Configuration service you'll need to create an instance of the
  * {@link com.azure.data.appconfiguration.ConfigurationAsyncClient} class. To make this possible you'll need the
- * connection string of the configuration store. Alternatively, you can use AAD authentication via
+ * connection string of the configuration store. Alternatively, you can use Entra authentication via
  * <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable"> Azure Identity</a>
  * to connect to the service.</p>
  * <ol>

sdk/appconfiguration/azure-data-appconfiguration/src/main/java/com/azure/data/appconfiguration/ConfigurationClient.java

@@ -71,7 +71,7 @@
  *
  * <p>In order to interact with the App Configuration service you'll need to create an instance of the
  * {@link ConfigurationClient} class. To make this possible you'll need the connection
- * string of the configuration store. Alternatively, you can use AAD authentication via
+ * string of the configuration store. Alternatively, you can use Entra authentication via
  * <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable"> Azure Identity</a>
  * to connect to the service.</p>
  * <ol>

sdk/appconfiguration/azure-data-appconfiguration/src/main/java/com/azure/data/appconfiguration/ConfigurationClientBuilder.java

@@ -43,6 +43,7 @@
 import com.azure.data.appconfiguration.implementation.ConfigurationClientCredentials;
 import com.azure.data.appconfiguration.implementation.ConfigurationCredentialsPolicy;
 import com.azure.data.appconfiguration.implementation.SyncTokenPolicy;
+import com.azure.data.appconfiguration.models.ConfigurationAudience;
 
 import java.net.MalformedURLException;
 import java.net.URL;
@@ -144,6 +145,8 @@ public final class ConfigurationClientBuilder implements TokenCredentialTrait<Co
     private Configuration configuration;
     private ConfigurationServiceVersion version;
 
+    private ConfigurationAudience audience;
+
     /**
      * Constructs a new builder used to configure and build {@link ConfigurationClient ConfigurationClients} and
      * {@link ConfigurationAsyncClient ConfigurationAsyncClients}.
@@ -270,7 +273,7 @@ private HttpPipeline createDefaultHttpPipeline(SyncTokenPolicy syncTokenPolicy,
 
         if (tokenCredential != null) {
             // User token based policy
-            policies.add(new BearerTokenAuthenticationPolicy(tokenCredential, String.format("%s/.default", endpoint)));
+            policies.add(new BearerTokenAuthenticationPolicy(tokenCredential, getDefaultScope(endpoint)));
         } else if (credentials != null) {
             // Use credentialS based policy
             policies.add(new ConfigurationCredentialsPolicy(credentials));
@@ -537,4 +540,36 @@ public ConfigurationClientBuilder serviceVersion(ConfigurationServiceVersion ver
         this.version = version;
         return this;
     }
+
+    /**
+     * Sets the {@link ConfigurationAudience} to use for authentication with Microsoft Entra. The audience is not
+     * considered when using a shared key.
+     *
+     * @param audience {@link ConfigurationAudience} of the service to be used when making requests.
+     * @return The updated ConfigurationClientBuilder object.
+     */
+    public ConfigurationClientBuilder audience(ConfigurationAudience audience) {
+        this.audience = audience;
+        return this;
+    }
+
+    /**
+     * Gets the default scope for the given endpoint.
+     *
+     * @param endpoint The endpoint to get the default scope for.
+     * @return The default scope for the given endpoint.
+     */
+    private String getDefaultScope(String endpoint) {
+        String defaultValue = "/.default";
+        if (audience == null || audience.toString().isEmpty()) {
+            if (endpoint.endsWith("azconfig.azure.us") || endpoint.endsWith("appconfig.azure.us")) {
+                return ConfigurationAudience.AZURE_US_GOVERNMENT + defaultValue;
+            } else if (endpoint.endsWith("azconfig.azure.cn") || endpoint.endsWith("appconfig.azure.cn")) {
+                return ConfigurationAudience.AZURE_CHINA + defaultValue;
+            } else {
+                return ConfigurationAudience.AZURE_PUBLIC_CLOUD + defaultValue;
+            }
+        }
+        return audience + defaultValue;
+    }
 }

sdk/appconfiguration/azure-data-appconfiguration/src/main/java/com/azure/data/appconfiguration/models/ConfigurationAudience.java

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.data.appconfiguration.models;
+
+import com.azure.core.util.ExpandableStringEnum;
+
+import java.util.Collection;
+
+/**
+ * Configuration Audience is used to specify the target audience for the Azure App Configuration service.
+ * Microsoft Entra audience is configurable via the {@link com.azure.data.appconfiguration.ConfigurationClientBuilder#audience(ConfigurationAudience)} method.
+ */
+public final class ConfigurationAudience extends ExpandableStringEnum<ConfigurationAudience> {
+    /**
+     * The Azure App Configuration service audience for China Cloud.
+     */
+    public static final ConfigurationAudience AZURE_CHINA = fromString("https://appconfig.azure.cn");
+
+    /**
+     * The Azure App Configuration service audience for US Government Cloud.
+     */
+    public static final ConfigurationAudience AZURE_US_GOVERNMENT = fromString("https://appconfig.azure.us");
+
+    /**
+     * The Azure App Configuration service audience for Public Cloud.
+     */
+    public static final ConfigurationAudience AZURE_PUBLIC_CLOUD = fromString("https://appconfig.azure.com");
+
+    /**
+     * Creates a new instance of ConfigurationAudience value.
+     *
+     * @deprecated Use the {@link #fromString(String)} factory method.
+     */
+    @Deprecated
+    public ConfigurationAudience() {
+    }
+
+    /**
+     * Creates or finds a ConfigurationAudience from its string representation.
+     *
+     * @param name a name to look for.
+     * @return the corresponding ConfigurationAudience.
+     */
+    public static ConfigurationAudience fromString(String name) {
+        return fromString(name, ConfigurationAudience.class);
+    }
+
+    /**
+     * Gets known ConfigurationAudience values.
+     *
+     * @return known ConfigurationAudience values.
+     */
+    public static Collection<ConfigurationAudience> values() {
+        return values(ConfigurationAudience.class);
+    }
+}

sdk/appconfiguration/azure-data-appconfiguration/src/main/java/com/azure/data/appconfiguration/package-info.java

@@ -17,7 +17,7 @@
  *
  * <p>In order to interact with the App Configuration service you'll need to create an instance of the Configuration
  * Client class. To make this possible you'll need the connection string of the configuration store. Alternatively,
- * you can use AAD authentication via
+ * you can use Entra authentication via
  * <a href="https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable"> Azure Identity</a>
  * to connect to the service.</p>
  * <ol>

sdk/appconfiguration/azure-data-appconfiguration/src/samples/README.md

@@ -32,7 +32,7 @@ The following sections provide several code snippets covering some of the most c
 - [Set a configuration setting to read only][sample_read_only]
 - [Clear read only from a configuration setting][sample_read_only]
 - [Conditional request a configuration setting][sample_conditional_request]
-- [AAD Authentication][sample_aad]
+- [Entra Authentication][sample_entra_authentication]
 - [HTTP client with proxy option][proxy_option]
 - [Feature Flag configuration setting][sample_feature_flag_setting]
 - [Secret Reference configuration setting][sample_secret_reference_setting]
@@ -65,7 +65,7 @@ This project welcomes contributions and suggestions. Find [more contributing][SD
 [sample_read_only]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/ReadOnlySample.java
 [sample_read_revision_history]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/ReadRevisionHistory.java
 [sample_read_revision_history_tags]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/ReadRevisionHistoryWIthTagsFilter.java
-[sample_aad]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/AadAuthentication.java
+[sample_entra_authentication]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/EntraIdAuthentication.java
 [sample_feature_flag_setting]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/FeatureFlagConfigurationSettingSample.java
 [sample_secret_reference_setting]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/SecretReferenceConfigurationSettingSample.java
 [sample_snapshot_CRU_usage]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/CreateSnapshot.java

sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/AadAuthentication.java renamed to sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/EntraIdAuthentication.java

@@ -3,23 +3,24 @@
 
 package com.azure.data.appconfiguration;
 
+import com.azure.core.util.Configuration;
 import com.azure.data.appconfiguration.models.ConfigurationSetting;
 import com.azure.identity.DefaultAzureCredential;
 import com.azure.identity.DefaultAzureCredentialBuilder;
 
 /**
- * Sample demonstrates how to use AAD token to build a configuration client.
+ * Sample demonstrates how to use Entra token to build a configuration client.
  */
-public class AadAuthentication {
+public class EntraIdAuthentication {
     /**
-     * Sample for how to use AAD token Authentication.
+     * Sample for how to use Entra token Authentication.
      *
      * @param args Unused. Arguments to the program.
      */
     public static void main(String[] args) {
         // The endpoint can be obtained by going to your App Configuration instance in the Azure portal
         // and navigating to "Overview" page. Looking for the "Endpoint" keyword.
-        String endpoint = "{endpoint_value}";
+        String endpoint = Configuration.getGlobalConfiguration().get("AZ_CONFIG_ENDPOINT");
 
         // Default token credential could be obtained from Identity service.
         // It tries to create a valid credential in the following order:
@@ -30,7 +31,7 @@ public static void main(String[] args) {
         DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
 
         final ConfigurationClient client = new ConfigurationClientBuilder()
-            .credential(tokenCredential) // AAD authentication
+            .credential(tokenCredential) // Entra authentication
             .endpoint(endpoint)
             .buildClient();
 

sdk/appconfiguration/azure-data-appconfiguration/src/samples/java/com/azure/data/appconfiguration/ReadmeSamples.java

@@ -69,14 +69,14 @@ public void createAsyncClient() {
         // END: readme-sample-createAsyncClient
     }
 
-    public void aadAuthentication() {
-        // BEGIN: readme-sample-aadAuthentication
+    public void entraAuthentication() {
+        // BEGIN: readme-sample-entraAuthentication
         DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
         ConfigurationClient configurationClient = new ConfigurationClientBuilder()
             .credential(credential)
             .endpoint(endpoint)
             .buildClient();
-        // END: readme-sample-aadAuthentication
+        // END: readme-sample-entraAuthentication
     }
 
     public void sqlExample() {
@@ -364,7 +364,7 @@ public void enableHttpLogging() {
                 .buildClient();
         // or
         DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
-        ConfigurationClient configurationClientAad = new ConfigurationClientBuilder()
+        ConfigurationClient configurationClientEntraId = new ConfigurationClientBuilder()
                 .credential(credential)
                 .endpoint(endpoint)
                 .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))

sdk/appconfiguration/azure-data-appconfiguration/src/test/java/com/azure/data/appconfiguration/ConfigurationClientBuilderTest.java

@@ -23,12 +23,15 @@
 import com.azure.core.util.Header;
 import com.azure.data.appconfiguration.implementation.ClientConstants;
 import com.azure.data.appconfiguration.implementation.ConfigurationClientCredentials;
+import com.azure.data.appconfiguration.models.ConfigurationAudience;
 import com.azure.data.appconfiguration.models.ConfigurationSetting;
+import com.azure.identity.DefaultAzureCredentialBuilder;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.MethodSource;
 import reactor.core.publisher.Mono;
 
+import java.lang.reflect.Method;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.time.Duration;
@@ -146,7 +149,7 @@ public void invalidConnectionStringSegmentCount() {
 
     @Test
     @DoNotRecord
-    public void nullAADCredential() {
+    public void nullEntraCredential() {
         assertThrows(NullPointerException.class, () -> {
             final ConfigurationClientBuilder builder = new ConfigurationClientBuilder();
             builder.endpoint(ENDPOINT).credential(null).buildAsyncClient();
@@ -299,4 +302,74 @@ private static URI getURI(String endpointFormat, String namespace, String domain
                 exception);
         }
     }
+
+    @Test
+    @DoNotRecord
+    public void testGetUsGovScope() throws Exception {
+        ConfigurationClientBuilder builder = new ConfigurationClientBuilder();
+        Method method = ConfigurationClientBuilder.class.getDeclaredMethod("getDefaultScope", String.class);
+        method.setAccessible(true);
+
+        String expectedScope = "https://appconfig.azure.us/.default";
+
+        String legacyEndpoint = "https://example1.azconfig.azure.us";
+        String actualScope = (String) method.invoke(builder, legacyEndpoint);
+        assertEquals(expectedScope, actualScope);
+
+        String endpoint = "https://example1.appconfig.azure.us";
+        actualScope = (String) method.invoke(builder, endpoint);
+        assertEquals(expectedScope, actualScope);
+    }
+
+    @Test
+    @DoNotRecord
+    public void testGetDefaultScope() throws Exception {
+        ConfigurationClientBuilder builder = new ConfigurationClientBuilder();
+        Method method = ConfigurationClientBuilder.class.getDeclaredMethod("getDefaultScope", String.class);
+        method.setAccessible(true);
+
+        String expectedScope = "https://appconfig.azure.com/.default";
+
+        String legacyEndpoint = "https://example1.azconfig.azure.com";
+        String actualScope = (String) method.invoke(builder, legacyEndpoint);
+        assertEquals(expectedScope, actualScope);
+
+        String endpoint = "https://example1.appconfig.azure.com";
+        actualScope = (String) method.invoke(builder, endpoint);
+        assertEquals(expectedScope, actualScope);
+    }
+
+    @Test
+    @DoNotRecord
+    public void testGetChinaScope() throws Exception {
+        ConfigurationClientBuilder builder = new ConfigurationClientBuilder();
+        Method method = ConfigurationClientBuilder.class.getDeclaredMethod("getDefaultScope", String.class);
+        method.setAccessible(true);
+
+        String expectedScope = "https://appconfig.azure.cn/.default";
+
+        String legacyEndpoint = "https://example1.azconfig.azure.cn";
+        String actualScope = (String) method.invoke(builder, legacyEndpoint);
+        assertEquals(expectedScope, actualScope);
+
+        String endpoint = "https://example1.appconfig.azure.cn";
+        actualScope = (String) method.invoke(builder, endpoint);
+        assertEquals(expectedScope, actualScope);
+    }
+
+    @Test
+    @DoNotRecord
+    public void testUserDefinedScope() throws Exception {
+        String fakeEndpoint = "https://example1.azconfig.azure.com";
+        ConfigurationClientBuilder builder
+            = new ConfigurationClientBuilder().endpoint("https://example1.azconfig.azure.com")
+                .credential(new DefaultAzureCredentialBuilder().build())
+                .audience(ConfigurationAudience.AZURE_CHINA);
+        builder.buildClient();
+        Method method = ConfigurationClientBuilder.class.getDeclaredMethod("getDefaultScope", String.class);
+        method.setAccessible(true);
+
+        String actualScope = (String) method.invoke(builder, fakeEndpoint);
+        assertEquals(ConfigurationAudience.AZURE_CHINA + "/.default", actualScope);
+    }
 }