fixes

Author: alexwolfmsft

docs/azure/sdk/authentication/authentication-best-practices.md

@@ -22,13 +22,13 @@ Reuse credential instances when possible to improve app resilience and reduce th
 
 In an ASP.NET Core app, implement credential reuse through the `UseCredential` method of `Microsoft.Extensions.Azure`:
 
-:::code language="csharp" source="../snippets/auth-best-practices/Program.cs" id="snippet_credential_reuse_Dac" highlight="6,7" :::
+:::code language="csharp" source="../snippets/authentication/best-practices/Program.cs" id="snippet_credential_reuse_Dac" highlight="6,7" :::
 
 For information on this approach, see [Authenticate using Microsoft Entra ID](/dotnet/azure/sdk/aspnetcore-guidance?tabs=api#authenticate-using-microsoft-entra-id).
 
 Other types of .NET apps can reuse credential instances as follows:
 
-:::code language="csharp" source="../snippets/auth-best-practices/Program.cs" id="snippet_credential_reuse_noDac" highlight="8, 12" :::
+:::code language="csharp" source="../snippets/authentication/best-practices/Program.cs" id="snippet_credential_reuse_noDac" highlight="8, 12" :::
 
 ## Understand the managed identity retry strategy
 
@@ -38,8 +38,8 @@ The Azure Identity library for .NET allows you to authenticate via managed ident
   - No retries are attempted when token acquisition fails, which makes this the least resilient option.
 - When used via any other approach, such as `ChainedTokenCredential` or `ManagedIdentityCredential` directly:
   - The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted.
-  - If the Azure service to which you're authenticating provides a `Retry-After` response header, the next retry is delayed by the duration specified in that header's value.
-  - If the service doesn't provide a `Retry-After` header, the maximum permissible delay between retries is 1 minute.
   - To change any of the default retry settings, use the `Retry` property on `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds:
 
-:::code language="csharp" source="../snippets/auth-best-practices/Program.cs" id="snippet_retries" highlight="5-9":::
+:::code language="csharp" source="../snippets/authentication/best-practices/Program.cs" id="snippet_retries" highlight="5-9" :::
+
+For more information on customizing retry policies, see [Setting a custom retry policy](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md#setting-a-custom-retry-policy)

docs/azure/sdk/includes/default-azure-credential-usage.md

@@ -1,19 +1,18 @@
 
-`DefaultAzureCredential` is the most approachable way to get started with the Azure Identity library, but that convenience also introduces certain tradeoffs. For example, the specific credential in the [chain](/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) that will succeed and be used for request authentication can't be guaranteed ahead of time. In a production environment, this unpredictability can introduce significant and sometimes subtle problems.
+`DefaultAzureCredential` is the most approachable way to get started with the Azure Identity library, but that convenience also introduces certain tradeoffs:
 
-For example, consider the following hypothetical sequence of events:
+- **Debugging challenges**: When authentication fails, it can be difficult to identify and [debug the offending credential](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#debug-a-chained-credential). Enable logging to see the sequential progression and success or failure status of each credential.
+- **Performance overhead**: Sequential credential attempts can introduce performance overhead. For example, managed identity is unavailable on a local development machine. Consequently, `ManagedIdentityCredential` always fails locally, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
+- **Unpredictable behavior**: `DefaultAzureCredential` checks for the presence of certain environment variables as part of its sequential search through a [chain](/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) of potential credentials. It's possible that someone could add or modify these [environment variables](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md#environment-variables) at the system level on the host machine. Those changes apply globally and therefore alter the behavior of `DefaultAzureCredential` at runtime in any app running on that machine. A user could also install and sign-in to tooling such as the Azure CLI on the host machine that could potentially impact with credential is selected by `DefaultAzureCredential`.
+
+In a production environment, the unpredictability of `DefaultAzureCredential` can introduce significant and sometimes subtle problems. For example, consider the following hypothetical sequence of events:
 
 1. An organization's security team mandates all apps use managed identity to authenticate to Azure resources.
 1. For months, a .NET app hosted on an Azure Virtual Machine (VM) successfully uses `DefaultAzureCredential` to authenticate via managed identity.
 1. Without telling the support team, a developer installs the Azure CLI on that VM and runs the `az login` command to sign-in to Azure.
 1. Due to a separate configuration change in the Azure environment, authentication via the original managed identity unexpectedly begins to fail silently.
 1. `DefaultAzureCredential` skips the failed `ManagedIdentityCredential` and searches for the next available credential, which is the Azure CLI credentials.
-1. The team is unaware of the hidden authentication failure because logging is disabled by default.
-
-`DefaultAzureCredential` also introduces the following challenges in some scenarios:
-
-- **Debugging challenges**: When authentication fails, it can be difficult to identify and [debug the offending credential](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#debug-a-chained-credential). Enable logging to see the sequential progression and success or failure status of each credential.
-- **Performance overhead**: Sequential credential attempts can introduce performance overhead. For example, managed identity is unavailable on a local development machine. Consequently, `ManagedIdentityCredential` always fails locally, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
+1. The application starts utilizing the Azure CLI credentials rather than the managed identity, which may fail or result in unexpected elevation or reduction of privileges.
 
 To prevent these types of subtle issues or silent failures in production apps, strongly consider moving from `DefaultAzureCredential` to one of the following deterministic solutions:
 

docs/azure/sdk/snippets/auth-best-practices/AuthBestPractices.csproj renamed to docs/azure/sdk/snippets/authentication/best-practices/AuthBestPractices.csproj

@@ -9,8 +9,8 @@
 #region snippet_credential_reuse_Dac
 builder.Services.AddAzureClients(clientBuilder =>
 {
-    clientBuilder.AddSecretClient(new Uri("<key_vault_url>"));
-    clientBuilder.AddBlobServiceClient(new Uri("<storage_url>"));
+    clientBuilder.AddSecretClient(new Uri("<key-vault-url>"));
+    clientBuilder.AddBlobServiceClient(new Uri("<blob-storage-uri>"));
 
     DefaultAzureCredential credential = new();
     clientBuilder.UseCredential(credential);
@@ -28,7 +28,7 @@
     credentialChain);
 
 SecretClient secretClient = new(
-    new Uri("<key_vault_url>"),
+    new Uri("<key-vault-url>"),
     credentialChain);
 #endregion snippet_credential_reuse_noDac