Improve Azure Identity credential env var docs (Azure#47889)

* Improve DAC env var docs

* Edit pass

* Revert changes to EBN properties

* Update DAC options XML docs

* Improve XML docs for options classes

* Update sdk/identity/Azure.Identity/src/Credentials/EnvironmentCredentialOptions.cs

Co-authored-by: Christopher Scott <[email protected]>

---------

Co-authored-by: Christopher Scott <[email protected]>

Author: scottaddie

sdk/identity/Azure.Identity/README.md

@@ -270,7 +270,7 @@ Not all credentials require this configuration. Credentials that authenticate th
 
 ## Environment variables
 
-[`DefaultAzureCredential`][ref_DefaultAzureCredential] and [`EnvironmentCredential`][ref_EnvironmentCredential] can be configured with environment variables. Each type of authentication requires values for specific variables.
+[`DefaultAzureCredential`][ref_DefaultAzureCredential] and [`EnvironmentCredential`][ref_EnvironmentCredential] can be configured with environment variables. Each type of authentication requires values for specific variables. Configuration is attempted in the order in which these environment variables are listed. For example, if values for a client secret and certificate are both present, the client secret is used by `EnvironmentCredential`.
 
 ### Service principal with secret
 
@@ -299,13 +299,17 @@ Not all credentials require this configuration. Credentials that authenticate th
 |`AZURE_USERNAME`|a username (usually an email address)
 |`AZURE_PASSWORD`|that user's password
 
-### Managed identity (`DefaultAzureCredential`)
+### Workload identity (`DefaultAzureCredential`)
 
 |Variable name|Value
 |-|-
-|`AZURE_CLIENT_ID`|The client ID for the user-assigned managed identity. If defined, used as the default value for `ManagedIdentityClientId` in `DefaultAzureCredentialOptions`
+|`AZURE_CLIENT_ID`|The client ID of the application the workload identity will authenticate. If defined, used as the default value for `WorkloadIdentityClientId` in `DefaultAzureCredentialOptions`.
+
+### Managed identity (`DefaultAzureCredential`)
 
-Configuration is attempted in the order in which these environment variables are listed. For example, if values for a client secret and certificate are both present, the client secret is used.
+|Variable name|Value
+|-|-
+|`AZURE_CLIENT_ID`|The client ID for the user-assigned managed identity. If defined, used as the default value for `ManagedIdentityClientId` in `DefaultAzureCredentialOptions`.
 
 ## Continuous Access Evaluation
 

sdk/identity/Azure.Identity/src/Credentials/DefaultAzureCredentialOptions.cs

@@ -48,6 +48,9 @@ public T Value
         /// <summary>
         /// The ID of the tenant to which the credential will authenticate by default. If not specified, the credential will authenticate to any requested tenant, and will default to the tenant to which the chosen authentication method was originally authenticated.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_TENANT_ID</c>.
+        /// </remarks>
         public string TenantId
         {
             get => _tenantId.Value;
@@ -101,7 +104,7 @@ public string InteractiveBrowserTenantId
         }
 
         /// <summary>
-        /// Specifies the tenant id of the preferred authentication account, to be retrieved from the shared token cache for single sign on authentication with
+        /// Specifies the tenant ID of the preferred authentication account, to be retrieved from the shared token cache for single sign on authentication with
         /// development tools, in the case multiple accounts are found in the shared token.
         /// </summary>
         /// <remarks>
@@ -167,8 +170,10 @@ public string VisualStudioCodeTenantId
         /// Specifies tenants in addition to the specified <see cref="TenantId"/> for which the credential may acquire tokens.
         /// Add the wildcard value "*" to allow the credential to acquire tokens for any tenant the logged in account can access.
         /// If no value is specified for <see cref="TenantId"/>, this option will have no effect on that authentication method, and the credential will acquire tokens for any requested tenant when using that method.
-        /// This value can also be set by setting the environment variable AZURE_ADDITIONALLY_ALLOWED_TENANTS.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_ADDITIONALLY_ALLOWED_TENANTS</c>.
+        /// </remarks>
         public IList<string> AdditionallyAllowedTenants { get; internal set; } = EnvironmentVariables.AdditionallyAllowedTenants;
 
         /// <summary>
@@ -177,25 +182,30 @@ public string VisualStudioCodeTenantId
         /// </summary>
         /// <remarks>
         /// If multiple accounts are found in the shared token cache and no value is specified, or the specified value matches no accounts in
-        /// the cache the SharedTokenCacheCredential will not be used for authentication.
+        /// the cache, the SharedTokenCacheCredential won't be used for authentication.
+        /// Defaults to the value of environment variable <c>AZURE_USERNAME</c>.
         /// </remarks>
         public string SharedTokenCacheUsername { get; set; } = EnvironmentVariables.Username;
 
         /// <summary>
-        /// Specifies the client id of the selected credential
+        /// Specifies the client ID of the selected credential.
         /// </summary>
         public string InteractiveBrowserCredentialClientId { get; set; }
 
         /// <summary>
-        /// Specifies the client id of the application the workload identity will authenticate.
+        /// Specifies the client ID of the application the workload identity will authenticate.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_CLIENT_ID</c>.
+        /// </remarks>
         public string WorkloadIdentityClientId { get; set; } = EnvironmentVariables.ClientId;
 
         /// <summary>
         /// Specifies the client ID of a user-assigned managed identity. If this value is configured, then <see cref="ManagedIdentityResourceId"/> should not be configured.
         /// </summary>
         /// <remarks>
         /// If neither the <see cref="ManagedIdentityClientId"/> nor the <see cref="ManagedIdentityResourceId"/> property is set, then a system-assigned managed identity is used.
+        /// Defaults to the value of environment variable <c>AZURE_CLIENT_ID</c>.
         /// </remarks>
         public string ManagedIdentityClientId { get; set; } = EnvironmentVariables.ClientId;
 
@@ -213,20 +223,20 @@ public string VisualStudioCodeTenantId
         public TimeSpan? CredentialProcessTimeout { get; set; } = TimeSpan.FromSeconds(30);
 
         /// <summary>
-        /// Specifies whether the <see cref="EnvironmentCredential"/> will be excluded from the authentication flow. Setting to true disables reading
+        /// Specifies whether the <see cref="EnvironmentCredential"/> will be excluded from the authentication flow. Setting to <c>true</c> disables reading
         /// authentication details from the process' environment variables.
         /// </summary>
         public bool ExcludeEnvironmentCredential { get; set; }
 
         /// <summary>
-        /// Specifies whether the <see cref="WorkloadIdentityCredential"/> will be excluded from the authentication flow. Setting to true disables reading
+        /// Specifies whether the <see cref="WorkloadIdentityCredential"/> will be excluded from the authentication flow. Setting to <c>true</c> disables reading
         /// authentication details from the process' environment variables.
         /// </summary>
         public bool ExcludeWorkloadIdentityCredential { get; set; }
 
         /// <summary>
         /// Specifies whether the <see cref="ManagedIdentityCredential"/> will be excluded from the <see cref="DefaultAzureCredential"/> authentication flow.
-        /// Setting to true disables authenticating with managed identity endpoints.
+        /// Setting to <c>true</c> disables authenticating with managed identity endpoints.
         /// </summary>
         public bool ExcludeManagedIdentityCredential { get; set; }
 
@@ -237,14 +247,14 @@ public string VisualStudioCodeTenantId
 
         /// <summary>
         /// Specifies whether the <see cref="SharedTokenCacheCredential"/> will be excluded from the <see cref="DefaultAzureCredential"/> authentication flow.
-        /// Setting to true disables single sign on authentication with development tools which write to the shared token cache.
+        /// Setting to <c>true</c> disables single sign-on authentication with development tools which write to the shared token cache.
         /// The default is <c>true</c>.
         /// </summary>
         public bool ExcludeSharedTokenCacheCredential { get; set; } = true;
 
         /// <summary>
         /// Specifies whether the <see cref="InteractiveBrowserCredential"/> will be excluded from the <see cref="DefaultAzureCredential"/> authentication flow.
-        /// Setting to true disables launching the default system browser to authenticate in development environments.
+        /// Setting to <c>true</c> disables launching the default system browser to authenticate in development environments.
         /// The default is <c>true</c>.
         /// </summary>
         public bool ExcludeInteractiveBrowserCredential { get; set; } = true;

sdk/identity/Azure.Identity/src/Credentials/EnvironmentCredentialOptions.cs

@@ -41,7 +41,7 @@ public class EnvironmentCredentialOptions : TokenCredentialOptions, ISupportsDis
         internal bool SendCertificateChain { get; set; } = EnvironmentVariables.ClientSendCertificateChain;
 
         /// <summary>
-        /// The username of the user account the credeential will authenticate. This value defaults to the value of the environment variable AZURE_USERNAME.
+        /// The username of the user account the credential will authenticate. This value defaults to the value of the environment variable AZURE_USERNAME.
         /// </summary>
         internal string Username { get; set; } = EnvironmentVariables.Username;
 
@@ -67,8 +67,10 @@ public class EnvironmentCredentialOptions : TokenCredentialOptions, ISupportsDis
         /// Specifies tenants in addition to the specified <see cref="TenantId"/> for which the credential may acquire tokens.
         /// Add the wildcard value "*" to allow the credential to acquire tokens for any tenant the logged in account can access.
         /// If no value is specified for <see cref="TenantId"/>, this option will have no effect on that authentication method, and the credential will acquire tokens for any requested tenant when using that method.
-        /// This value defaults to the value of the environment variable AZURE_ADDITIONALLY_ALLOWED_TENANTS.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_ADDITIONALLY_ALLOWED_TENANTS</c>. Values can be a semi-colon delimited list of tenant IDs , or '*' to denote any tenant ID.
+        /// </remarks>
         public IList<string> AdditionallyAllowedTenants { get; internal set; } = EnvironmentVariables.AdditionallyAllowedTenants;
     }
 }

sdk/identity/Azure.Identity/src/Credentials/UsernamePasswordCredentialOptions.cs

@@ -11,7 +11,7 @@ namespace Azure.Identity
     public class UsernamePasswordCredentialOptions : TokenCredentialOptions, ISupportsTokenCachePersistenceOptions, ISupportsDisableInstanceDiscovery, ISupportsAdditionallyAllowedTenants
     {
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If no options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

sdk/identity/Azure.Identity/src/Credentials/WorkloadIdentityCredentialOptions.cs

@@ -13,18 +13,27 @@ namespace Azure.Identity
     public class WorkloadIdentityCredentialOptions : TokenCredentialOptions, ISupportsDisableInstanceDiscovery, ISupportsAdditionallyAllowedTenants
     {
         /// <summary>
-        /// The tenant ID of the service principal. Defaults to the value of the environment variable AZURE_TENANT_ID.
+        /// The tenant ID of the service principal.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_TENANT_ID</c>.
+        /// </remarks>
         public string TenantId { get; set; } = EnvironmentVariables.TenantId;
 
         /// <summary>
-        /// The client (application) ID of the service principal. Defaults to the value of the environment variable AZURE_CLIENT_ID.
+        /// The client (application) ID of the service principal.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_CLIENT_ID</c>.
+        /// </remarks>
         public string ClientId { get; set; } = EnvironmentVariables.ClientId;
 
         /// <summary>
-        /// The path to a file containing the workload identity token. Defaults to the value of the environment variable AZURE_FEDERATED_TOKEN_FILE.
+        /// The path to a file containing the workload identity token.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_FEDERATED_TOKEN_FILE</c>.
+        /// </remarks>
         public string TokenFilePath { get; set; } = EnvironmentVariables.AzureFederatedTokenFile;
 
         /// <inheritdoc />
@@ -34,8 +43,10 @@ public class WorkloadIdentityCredentialOptions : TokenCredentialOptions, ISuppor
         /// Specifies tenants in addition to the specified <see cref="TenantId"/> for which the credential may acquire tokens.
         /// Add the wildcard value "*" to allow the credential to acquire tokens for any tenant the logged in account can access.
         /// If no value is specified for <see cref="TenantId"/>, this option will have no effect, and the credential will acquire tokens for any requested tenant.
-        /// Defaults to the value of the environment variable AZURE_ADDITIONALLY_ALLOWED_TENANTS.
         /// </summary>
+        /// <remarks>
+        /// Defaults to the value of environment variable <c>AZURE_ADDITIONALLY_ALLOWED_TENANTS</c>.
+        /// </remarks>
         public IList<string> AdditionallyAllowedTenants { get; internal set; } = EnvironmentVariables.AdditionallyAllowedTenants;
 
         internal CredentialPipeline Pipeline { get; set; }