From faa3330bf77af3359b57bf70dfc70148deb31844 Mon Sep 17 00:00:00 2001 From: Scott Addie <10702007+scottaddie@users.noreply.github.com> Date: Fri, 21 Jul 2023 18:38:07 -0500 Subject: [PATCH] Edit pass on Azure.Identity troubleshooting guide (#37788) --- .../Azure.Identity/TROUBLESHOOTING.md | 112 ++++++++++++------ 1 file changed, 74 insertions(+), 38 deletions(-) diff --git a/sdk/identity/Azure.Identity/TROUBLESHOOTING.md b/sdk/identity/Azure.Identity/TROUBLESHOOTING.md index 26815861e5be..ffbf01fb575e 100644 --- a/sdk/identity/Azure.Identity/TROUBLESHOOTING.md +++ b/sdk/identity/Azure.Identity/TROUBLESHOOTING.md @@ -1,8 +1,9 @@ # Troubleshoot Azure Identity authentication issues -This troubleshooting guide covers failure investigation techniques, common errors for the credential types in the Azure Identity .NET client library, and mitigation steps to resolve these errors. +This troubleshooting guide covers failure investigation techniques, common errors for the credential types in the Azure Identity library for .NET, and mitigation steps to resolve these errors. ## Table of contents + - [Handle Azure Identity exceptions](#handle-azure-identity-exceptions) - [AuthenticationFailedException](#authenticationfailedexception) - [CredentialUnavailableException](#credentialunavailableexception) @@ -30,11 +31,15 @@ This troubleshooting guide covers failure investigation techniques, common error ## Handle Azure Identity exceptions ### AuthenticationFailedException -Exceptions arising from authentication errors can be raised on any service client method that makes a request to the service. This is because the token is requested from the credential on the first call to the service and on any subsequent requests to the service that need to refresh the token. + +Exceptions arising from authentication errors can be raised on any service client method that makes a request to the service. This is because the token is requested from the credential on: + +- The first call to the service. +- Any subsequent requests to the service that need to refresh the token. To distinguish these failures from failures in the service client, Azure Identity classes raise the `AuthenticationFailedException` with details describing the source of the error in the exception message and possibly the error message. Depending on the application, these errors may or may not be recoverable. -``` c# +```c# using Azure.Identity; using Azure.Security.KeyVault.Secrets; @@ -50,6 +55,7 @@ catch (AuthenticationFailedException e) Console.WriteLine($"Authentication Failed. {e.Message}"); } ``` + ### CredentialUnavailableException The `CredentialUnavailableException` is a special exception type derived from `AuthenticationFailedException`. This exception type is used to indicate that the credential can't authenticate in the current environment, due to lack of required configuration or setup. This exception is also used as a signal to chained credential types, such as `DefaultAzureCredential` and `ChainedTokenCredential`, that the chained credential should continue to try other credential types later in the chain. @@ -78,14 +84,14 @@ The Azure Identity library provides the same [logging capabilities](https://gith The simplest way to see the logs to help debug authentication issues is to enable the console logger. -``` c# +```c# // Setup a listener to monitor logged events. using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger(); ``` All credentials can be configured with diagnostic options, in the same way as other clients in the SDK. -``` c# +```c# DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions() { Diagnostics = @@ -103,56 +109,67 @@ DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions() | Error |Description| Mitigation | |---|---|---| -|`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`|