Add API to enforce Env Vars in DAC (Azure#46595)

g2vinay · web-flow · commit 81b099e98446 · 2025-09-08T07:52:07.000-07:00
diff --git a/sdk/identity/azure-identity/CHANGELOG.md b/sdk/identity/azure-identity/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 - Added claims challenge handling support to `AzureCliCredential`. When a token request includes claims, the credential will now throw a `CredentialUnavailableException` with instructions to use Azure PowerShell directly with the appropriate `-ClaimsChallenge` parameter.
 - Added claims challenge handling support to `AzurePowerShellCredential`. When a token request includes claims, the credential will now throw a `CredentialUnavailableException` with instructions to use Azure PowerShell directly with the appropriate `-ClaimsChallenge` parameter.
+- Added `AzureIdentityEnvVars` expandable string enum for type-safe environment variable names used in Azure Identity credentials.
+- Added `requireEnvVars(AzureIdentityEnvVars... envVars)` method to `DefaultAzureCredentialBuilder` to enforce the presence of specific environment variables at build time. When configured, the credential will throw an `IllegalStateException` during `build()` if any of the specified environment variables are missing or empty.
 
 ### Features Added
 
@@ -1111,4 +1113,4 @@ for more details. User authentication will be added in an upcoming preview
 release.
 
 This release supports only global Microsoft Entra tenants, i.e. those
-using the https://login.microsoftonline.com authentication endpoint.
+using the https://login.microsoftonline.com authentication endpoint.
diff --git a/sdk/identity/azure-identity/TROUBLESHOOTING.md b/sdk/identity/azure-identity/TROUBLESHOOTING.md
@@ -87,6 +87,8 @@ The underlying MSAL library, MSAL4J, also has detailed logging. It is highly ver
 | `CredentialUnavailableException` raised with message. "DefaultAzureCredential failed to retrieve a token from the included credentials." |All credentials in the `DefaultAzureCredential` chain failed to retrieve a token, each throwing a `CredentialUnavailableException`| <ul><li>[Enable logging](#enable-and-configure-logging) to verify the credentials being tried, and get further diagnostic information.</li><li>Consult the troubleshooting guide for underlying credential types for more information.</li><ul><li>[EnvironmentCredential](#troubleshoot-environmentcredential-authentication-issues)</li><li>[ManagedIdentityCredential](#troubleshoot-managedidentitycredential-authentication-issues)</li><li>[AzureCLICredential](#troubleshoot-azureclicredential-authentication-issues)</li><li>[AzurePowershellCredential](#troubleshoot-azurepowershellcredential-authentication-issues)</li></ul> |
 | `HttpResponseException` raised from the client with a status code of 401 or 403                                                          |Authentication succeeded but the authorizing Azure service responded with a 401 (Authenticate), or 403 (Forbidden) status code. This can often be caused by the `DefaultAzureCredential` authenticating an account other than the intended or that the intended account does not have the correct permissions or roles assigned.| <ul><li>[Enable logging](#enable-and-configure-logging) to determine which credential in the chain returned the authenticating token.</li><li>In the case a credential other than the expected is returning a token, look too bypass this by signing out of the corresponding development tool.`</li><li>Ensure that the correct role is assigned to the account being used. For example, a service specific role rather than the subscription Owner role.</li></ul> |
 | `IllegalArgumentException` raised with message "Invalid value for AZURE_TOKEN_CREDENTIALS..."                                            | The value provided in env var `AZURE_TOKEN_CREDENTIALS` doesn't map to one of `prod`, `dev`, or a specific credential name such as `EnvironmentCredential`, `ManagedIdentityCredential`, etc. | Ensure you specify a valid value as per your application's requirements. Specifying `prod` activates production environment credentials (`EnvironmentCredential`, `WorkloadIdentityCredential`, and `ManagedIdentityCredential`). Specifying `dev` activates development tool credentials (`IntelliJCredential`, `AzureCliCredential`, `AzurePowershellCredential`, `AzureDeveloperCliCredential`, and `VisualStudioCodeCredential`). Specifying a specific credential name targets that individual credential only as part of `DefaultAzureCredential`. |
+| `IllegalStateException` raised with message "Required environment variables are missing: [variable names]"                               | The `DefaultAzureCredential` was configured to require specific environment variables using `requireEnvVars(AzureIdentityEnvVars...)`, but one or more of those variables are not set or are empty. | <ul><li>Set the missing environment variables listed in the error message.</li><li>Ensure environment variables are set **prior to application startup**.</li><li>Verify variable names are spelled correctly and match exactly what was specified in `requireEnvVars()`. When using predefined `AzureIdentityEnvVars` constants, ensure the correct enum values are used. When using custom environment variables, ensure they were created with `AzureIdentityEnvVars.fromString()`.</li><li>Check that variables are not set to empty strings or null values.</li><li>If using containerized environments, ensure environment variables are properly passed to the container.</li></ul> |
+
 
 ## Troubleshoot `EnvironmentCredential` authentication issues
 `CredentialUnavailableException`
@@ -376,3 +378,4 @@ You may also log in another MSA account by selecting "Microsoft account":
 ## Get additional help
 
 Additional information on ways to reach out for support can be found in the [SUPPORT.md](https://github.com/Azure/azure-sdk-for-java/blob/main/SUPPORT.md) at the root of the repo.
+
diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/AzureIdentityEnvVars.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/AzureIdentityEnvVars.java
@@ -0,0 +1,97 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.identity;
+
+import com.azure.core.util.ExpandableStringEnum;
+
+import java.util.Collection;
+
+/**
+ * <p>Defines well-known Azure Identity environment variable names that can be used with 
+ * {@link DefaultAzureCredentialBuilder#requireEnvVars(AzureIdentityEnvVars...)}.</p>
+ *
+ * <p>This expandable enum provides a type-safe way to reference common Azure Identity environment
+ * variables while still allowing for custom environment variable names.</p>
+ *
+ * @see DefaultAzureCredentialBuilder#requireEnvVars(AzureIdentityEnvVars...)
+ */
+public final class AzureIdentityEnvVars extends ExpandableStringEnum<AzureIdentityEnvVars> {
+
+    /**
+     * Creates a new instance of {@link AzureIdentityEnvVars} without a {@link #toString()} value.
+     * <p>
+     * This constructor shouldn't be called as it will produce a {@link AzureIdentityEnvVars} which doesn't have a String enum
+     * value.
+     *
+     * @deprecated Use one of the constants or the {@link #fromString(String)} factory method.
+     */
+    @Deprecated
+    public AzureIdentityEnvVars() {
+    }
+
+    /**
+     * The Azure tenant ID environment variable.
+     */
+    public static final AzureIdentityEnvVars AZURE_TENANT_ID = fromString("AZURE_TENANT_ID");
+
+    /**
+     * The Azure client ID environment variable.
+     */
+    public static final AzureIdentityEnvVars AZURE_CLIENT_ID = fromString("AZURE_CLIENT_ID");
+
+    /**
+     * The Azure client secret environment variable.
+     */
+    public static final AzureIdentityEnvVars AZURE_CLIENT_SECRET = fromString("AZURE_CLIENT_SECRET");
+
+    /**
+     * The Azure client certificate path environment variable.
+     */
+    public static final AzureIdentityEnvVars AZURE_CLIENT_CERTIFICATE_PATH
+        = fromString("AZURE_CLIENT_CERTIFICATE_PATH");
+
+    /**
+     * The Azure client certificate password environment variable.
+     */
+    public static final AzureIdentityEnvVars AZURE_CLIENT_CERTIFICATE_PASSWORD
+        = fromString("AZURE_CLIENT_CERTIFICATE_PASSWORD");
+
+    /**
+     * The Azure authority host environment variable.
+     */
+    public static final AzureIdentityEnvVars AZURE_AUTHORITY_HOST = fromString("AZURE_AUTHORITY_HOST");
+
+    /**
+     * The Azure token credentials environment variable for selecting credential types.
+     */
+    public static final AzureIdentityEnvVars AZURE_TOKEN_CREDENTIALS = fromString("AZURE_TOKEN_CREDENTIALS");
+
+    /**
+     * The Azure client send certificate chain environment variable.
+     */
+    public static final AzureIdentityEnvVars AZURE_CLIENT_SEND_CERTIFICATE_CHAIN
+        = fromString("AZURE_CLIENT_SEND_CERTIFICATE_CHAIN");
+
+    /**
+     * Creates or finds an AzureIdentityEnvVars from its string representation.
+     *
+     * @param name a name to look for.
+     * @return the corresponding AzureIdentityEnvVars.
+     */
+    public static AzureIdentityEnvVars fromString(String name) {
+        if (name == null) {
+            return null;
+        }
+        return fromString(name, AzureIdentityEnvVars.class);
+    }
+
+    /**
+     * Gets known AzureIdentityEnvVars values.
+     *
+     * @return known AzureIdentityEnvVars values.
+     */
+    public static Collection<AzureIdentityEnvVars> values() {
+        return values(AzureIdentityEnvVars.class);
+    }
+}
diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/DefaultAzureCredentialBuilder.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/DefaultAzureCredentialBuilder.java
@@ -60,6 +60,7 @@ public class DefaultAzureCredentialBuilder extends CredentialBuilderBase<Default
     private String managedIdentityResourceId;
     private List<String> additionallyAllowedTenants
         = IdentityUtil.getAdditionalTenantsFromEnvironment(Configuration.getGlobalConfiguration().clone());
+    private AzureIdentityEnvVars[] requiredEnvVars;
 
     /**
      * Creates an instance of a DefaultAzureCredentialBuilder.
@@ -238,6 +239,29 @@ public DefaultAzureCredentialBuilder disableInstanceDiscovery() {
         return this;
     }
 
+    /**
+     * Specifies environment variables that must be present when building the credential.
+     * If any of the specified environment variables are missing, {@link #build()} will throw an 
+     * {@link IllegalStateException}.
+     *
+     * @param envVars the environment variables that must be present
+     * @return An updated instance of this builder with the required environment variables set as specified.
+     */
+    public DefaultAzureCredentialBuilder requireEnvVars(AzureIdentityEnvVars... envVars) {
+        Objects.requireNonNull(envVars, "envVars cannot be null");
+
+        // Check for null elements in the array
+        for (int i = 0; i < envVars.length; i++) {
+            if (envVars[i] == null) {
+                throw LOGGER.logExceptionAsError(
+                    new IllegalArgumentException("Environment variable at index " + i + " cannot be null"));
+            }
+        }
+
+        this.requiredEnvVars = envVars.clone();
+        return this;
+    }
+
     /**
      * Creates new {@link DefaultAzureCredential} with the configured options set.
      *
@@ -252,6 +276,34 @@ public DefaultAzureCredential build() {
                 "Only one of managedIdentityClientId and managedIdentityResourceId can be specified."));
         }
 
+        // Check required environment variables
+        if (requiredEnvVars != null && requiredEnvVars.length > 0) {
+            Configuration configuration = identityClientOptions.getConfiguration() == null
+                ? Configuration.getGlobalConfiguration().clone()
+                : identityClientOptions.getConfiguration();
+
+            List<String> missingVars = new ArrayList<>();
+            for (AzureIdentityEnvVars envVar : requiredEnvVars) {
+                if (CoreUtils.isNullOrEmpty(configuration.get(envVar.toString()))) {
+                    missingVars.add(envVar.toString());
+                }
+            }
+
+            if (!missingVars.isEmpty()) {
+                String errorMessage;
+                if (missingVars.size() == 1) {
+                    errorMessage = "Required environment variable is missing: " + missingVars.get(0)
+                        + ". Ensure this environment variable is set before creating the DefaultAzureCredential.";
+                } else {
+                    errorMessage = "Required environment variables are missing: " + String.join(", ", missingVars)
+                        + ". Ensure these environment variables are set before creating the DefaultAzureCredential.";
+                }
+
+                throw LOGGER.logExceptionAsError(new IllegalStateException(errorMessage
+                    + " See https://aka.ms/azsdk/java/identity/defaultazurecredential/troubleshoot for more information."));
+            }
+        }
+
         if (!CoreUtils.isNullOrEmpty(additionallyAllowedTenants)) {
             identityClientOptions.setAdditionallyAllowedTenants(additionallyAllowedTenants);
         }
diff --git a/sdk/identity/azure-identity/src/test/java/com/azure/identity/DefaultAzureCredentialTest.java b/sdk/identity/azure-identity/src/test/java/com/azure/identity/DefaultAzureCredentialTest.java
@@ -31,6 +31,7 @@
 import java.util.UUID;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -811,4 +812,88 @@ private List<TokenCredential> extractCredentials(DefaultAzureCredential credenti
             throw new RuntimeException("Failed to extract credentials", e);
         }
     }
+
+    @Test
+    public void testRequireEnvVarsSuccess() {
+        // Setup - create configuration with required environment variables present
+        TestConfigurationSource configSource = new TestConfigurationSource().put("AZURE_CLIENT_ID", CLIENT_ID)
+            .put("AZURE_TENANT_ID", TENANT_ID)
+            .put("AZURE_CLIENT_SECRET", "test-secret");
+        Configuration configuration = TestUtils.createTestConfiguration(configSource);
+
+        // Test - should not throw when all required env vars are present
+        DefaultAzureCredential credential
+            = new DefaultAzureCredentialBuilder()
+                .requireEnvVars(AzureIdentityEnvVars.AZURE_CLIENT_ID, AzureIdentityEnvVars.AZURE_TENANT_ID,
+                    AzureIdentityEnvVars.AZURE_CLIENT_SECRET)
+                .configuration(configuration)
+                .build();
+
+        // Verify the credential was created successfully
+        Assertions.assertNotNull(credential);
+    }
+
+    @Test
+    public void testRequireEnvVarsSingleMissing() {
+        // Setup - create configuration missing one required environment variable
+        TestConfigurationSource configSource
+            = new TestConfigurationSource().put("AZURE_CLIENT_ID", CLIENT_ID).put("AZURE_TENANT_ID", TENANT_ID);
+        // AZURE_CLIENT_SECRET is missing
+        Configuration configuration = TestUtils.createTestConfiguration(configSource);
+
+        // Test - should throw when required env var is missing
+        IllegalStateException exception = assertThrows(IllegalStateException.class,
+            () -> new DefaultAzureCredentialBuilder()
+                .requireEnvVars(AzureIdentityEnvVars.AZURE_CLIENT_ID, AzureIdentityEnvVars.AZURE_TENANT_ID,
+                    AzureIdentityEnvVars.AZURE_CLIENT_SECRET)
+                .configuration(configuration)
+                .build());
+
+        // Verify error message
+        assertTrue(exception.getMessage().contains("Required environment variable is missing: AZURE_CLIENT_SECRET"));
+    }
+
+    @Test
+    public void testRequireEnvVarsMultipleMissing() {
+        // Setup - create configuration missing multiple required environment variables
+        TestConfigurationSource configSource = new TestConfigurationSource().put("AZURE_CLIENT_ID", CLIENT_ID);
+        // AZURE_TENANT_ID and AZURE_CLIENT_SECRET are missing
+        Configuration configuration = TestUtils.createTestConfiguration(configSource);
+
+        // Test - should throw when multiple required env vars are missing
+        IllegalStateException exception = assertThrows(IllegalStateException.class,
+            () -> new DefaultAzureCredentialBuilder()
+                .requireEnvVars(AzureIdentityEnvVars.AZURE_CLIENT_ID, AzureIdentityEnvVars.AZURE_TENANT_ID,
+                    AzureIdentityEnvVars.AZURE_CLIENT_SECRET)
+                .configuration(configuration)
+                .build());
+
+        // Verify error message contains all missing variables
+        assertTrue(exception.getMessage().contains("Required environment variables are missing:"));
+        assertTrue(exception.getMessage().contains("AZURE_TENANT_ID"));
+        assertTrue(exception.getMessage().contains("AZURE_CLIENT_SECRET"));
+        // Should not contain AZURE_CLIENT_ID since it is present
+        String message = exception.getMessage();
+        assertFalse(message.contains("AZURE_CLIENT_ID"));
+    }
+
+    @Test
+    public void testRequireEnvVarsEmptyValue() {
+        // Setup - create configuration with empty string for required environment variable
+        TestConfigurationSource configSource = new TestConfigurationSource().put("AZURE_CLIENT_ID", CLIENT_ID)
+            .put("AZURE_TENANT_ID", TENANT_ID)
+            .put("AZURE_CLIENT_SECRET", ""); // Empty string should be treated as missing
+        Configuration configuration = TestUtils.createTestConfiguration(configSource);
+
+        // Test - should throw when required env var is empty
+        IllegalStateException exception = assertThrows(IllegalStateException.class,
+            () -> new DefaultAzureCredentialBuilder()
+                .requireEnvVars(AzureIdentityEnvVars.AZURE_CLIENT_ID, AzureIdentityEnvVars.AZURE_TENANT_ID,
+                    AzureIdentityEnvVars.AZURE_CLIENT_SECRET)
+                .configuration(configuration)
+                .build());
+
+        // Verify error message
+        assertTrue(exception.getMessage().contains("Required environment variable is missing: AZURE_CLIENT_SECRET"));
+    }
 }
