|
| 1 | +--- |
| 2 | +title: 'Credential chains in the Azure Identity library for .NET' |
| 3 | +description: 'This article describes the DefaultAzureCredential and ChainedTokenCredential classes in the Azure Identity library.' |
| 4 | +ms.topic: conceptual |
| 5 | +ms.date: 08/13/2024 |
| 6 | +--- |
| 7 | + |
| 8 | +# Credential chains in the Azure Identity library for .NET |
| 9 | + |
| 10 | +The Azure Identity library provides *credentials*—public classes derived from the Azure Core library's [TokenCredential](/dotnet/api/azure.core.tokencredential?view=azure-dotnet&preserve-view=true) class. A credential represents a distinct authentication flow for acquiring an access token from Microsoft Entra ID. These credentials can be chained together to form an ordered sequence of authentication mechanisms to be attempted. |
| 11 | + |
| 12 | +## How a chained credential works |
| 13 | + |
| 14 | +At runtime, a credential chain attempts to authenticate using the sequence's first credential. If that credential fails to acquire an access token, the next credential in the sequence is attempted, and so on, until an access token is successfully obtained. The following sequence diagram illustrates this behavior: |
| 15 | + |
| 16 | +:::image type="content" source="../media/mermaidjs/ChainSequence.svg" alt-text="Credential chain sequence diagram"::: |
| 17 | + |
| 18 | +## Why use credential chains |
| 19 | + |
| 20 | +A chained credential can offer the following benefits: |
| 21 | + |
| 22 | +- **Environment awareness**: Automatically selects the most appropriate credential based on the environment in which the app is running. Without it, you'd have to write code like this: |
| 23 | + |
| 24 | + :::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_NoChain"::: |
| 25 | + |
| 26 | +- **Seamless transitions**: Your app can move from local development to your staging or production environment without changing authentication code. |
| 27 | +- **Improved resiliency**: Includes a fallback mechanism that moves to the next credential when the prior fails to acquire an access token. |
| 28 | + |
| 29 | +## How to choose a chained credential |
| 30 | + |
| 31 | +There are two disparate philosophies to credential chaining: |
| 32 | + |
| 33 | +- **"Tear down" a chain**: Start with a preconfigured chain and exclude what you don't need. For this approach, see the [DefaultAzureCredential overview](#defaultazurecredential-overview) section. |
| 34 | +- **"Build up" a chain**: Start with an empty chain and include only what you need. For this approach, see the [ChainedTokenCredential overview](#chainedtokencredential-overview) section. |
| 35 | + |
| 36 | +## DefaultAzureCredential overview |
| 37 | + |
| 38 | +[DefaultAzureCredential](/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet&preserve-view=true) is an opinionated, preconfigured chain of credentials. It's designed to support many environments, along with the most common authentication flows and developer tools. In graphical form, the underlying chain looks like this: |
| 39 | + |
| 40 | +:::image type="content" source="../media/mermaidjs/DefaultAzureCredentialAuthFlow.svg" alt-text="DefaultAzureCredential auth flowchart"::: |
| 41 | + |
| 42 | +The order in which `DefaultAzureCredential` attempts credentials follows. |
| 43 | + |
| 44 | +| Order | Credential | Description | Enabled by default? | |
| 45 | +|-------|---------------------|-------------|---------------------| |
| 46 | +| 1 | [Environment][env-cred] |Reads a collection of environment variables to determine if an application service principal (application user) is configured for the app. If so, `DefaultAzureCredential` uses these values to authenticate the app to Azure. This method is most often used in server environments but can also be used when developing locally. | Yes | |
| 47 | +| 2 | [Workload Identity][wi-cred] |If the app is deployed to an Azure host with Workload Identity enabled, authenticate that account. | Yes | |
| 48 | +| 3 | [Managed Identity][mi-cred] |If the app is deployed to an Azure host with Managed Identity enabled, authenticate the app to Azure using that Managed Identity. | Yes | |
| 49 | +| 4 | [Visual Studio][vs-cred] |If the developer authenticated to Azure by logging into Visual Studio, authenticate the app to Azure using that same account. | Yes | |
| 50 | +| 5 | [Azure CLI][az-cred] |If the developer authenticated to Azure using Azure CLI's `az login` command, authenticate the app to Azure using that same account. | Yes | |
| 51 | +| 6 | [Azure PowerShell][pwsh-cred] |If the developer authenticated to Azure using Azure PowerShell's `Connect-AzAccount` cmdlet, authenticate the app to Azure using that same account. | Yes | |
| 52 | +| 7 | [Azure Developer CLI][azd-cred] |If the developer authenticated to Azure using Azure Developer CLI's `azd auth login` command, authenticate with that account. | Yes | |
| 53 | +| 8 | [Interactive browser][int-cred] |If enabled, interactively authenticate the developer via the current system's default browser. | No | |
| 54 | + |
| 55 | +[env-cred]: /dotnet/api/azure.identity.environmentcredential?view=azure-dotnet&preserve-view=true |
| 56 | +[wi-cred]: /dotnet/api/azure.identity.workloadidentitycredential?view=azure-dotnet&preserve-view=true |
| 57 | +[mi-cred]: /dotnet/api/azure.identity.managedidentitycredential?view=azure-dotnet&preserve-view=true |
| 58 | +[vs-cred]: /dotnet/api/azure.identity.visualstudiocredential?view=azure-dotnet&preserve-view=true |
| 59 | +[az-cred]: /dotnet/api/azure.identity.azureclicredential?view=azure-dotnet&preserve-view=true |
| 60 | +[pwsh-cred]: /dotnet/api/azure.identity.azurepowershellcredential?view=azure-dotnet&preserve-view=true |
| 61 | +[azd-cred]: /dotnet/api/azure.identity.azuredeveloperclicredential?view=azure-dotnet&preserve-view=true |
| 62 | +[int-cred]: /dotnet/api/azure.identity.interactivebrowsercredential?view=azure-dotnet&preserve-view=true |
| 63 | + |
| 64 | +In its simplest form, you can use the parameterless version of `DefaultAzureCredential` as follows: |
| 65 | + |
| 66 | +:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Dac"::: |
| 67 | + |
| 68 | +### How to customize DefaultAzureCredential |
| 69 | + |
| 70 | +To remove a credential from `DefaultAzureCredential`, use the corresponding `Exclude`-prefixed property in [DefaultAzureCredentialOptions](/dotnet/api/azure.identity.defaultazurecredentialoptions?view=azure-dotnet&preserve-view=true#properties). For example: |
| 71 | + |
| 72 | +:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_DacExcludes" highlight="4-5"::: |
| 73 | + |
| 74 | +In the preceding code sample, `EnvironmentCredential` and `WorkloadIdentityCredential` are removed from the credential chain. As a result, the first credential to be attempted is `ManagedIdentityCredential`. The modified chain looks like this: |
| 75 | + |
| 76 | +:::image type="content" source="../media/mermaidjs/DefaultAzureCredentialExcludes.svg" alt-text="DefaultAzureCredential using Excludes properties"::: |
| 77 | + |
| 78 | +> [!NOTE] |
| 79 | +> `InteractiveBrowserCredential` is excluded by default and therefore isn't shown in the preceding diagram. To include `InteractiveBrowserCredential`, use constructor <xref:Azure.Identity.DefaultAzureCredential.%23ctor%28System.Boolean%29>. |
| 80 | +
|
| 81 | +As more `Exclude`-prefixed properties are set to `true` (credential exclusions are configured), the advantages of using `DefaultAzureCredential` diminish. In such cases, `ChainedTokenCredential` is a better choice and requires less code. To illustrate, these two code samples behave the same way: |
| 82 | + |
| 83 | +### [DefaultAzureCredential](#tab/dac) |
| 84 | + |
| 85 | +:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_DacEquivalents"::: |
| 86 | + |
| 87 | +### [ChainedTokenCredential](#tab/ctc) |
| 88 | + |
| 89 | +:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_CtcEquivalents"::: |
| 90 | + |
| 91 | +--- |
| 92 | + |
| 93 | +## ChainedTokenCredential overview |
| 94 | + |
| 95 | +[ChainedTokenCredential](/dotnet/api/azure.identity.chainedtokencredential?view=azure-dotnet&preserve-view=true) is an empty chain to which you add credentials to suit your app's needs. For example: |
| 96 | + |
| 97 | +:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Ctc"::: |
| 98 | + |
| 99 | +The preceding code sample creates a tailored credential chain comprised of two credentials. The user-assigned managed identity variant of `ManagedIdentityCredential` is attempted first, followed by `VisualStudioCredential`, if necessary. In graphical form, the chain looks like this: |
| 100 | + |
| 101 | +:::image type="content" source="../media/mermaidjs/ChainedTokenCredentialAuthFlow.svg" alt-text="ChainedTokenCredential"::: |
| 102 | + |
| 103 | +> [!TIP] |
| 104 | +> For improved performance, optimize credential ordering in `ChainedTokenCredential` for your production environment. Credentials intended for use in the local development environment should be added last. |
| 105 | +
|
| 106 | +## Usage guidance for DefaultAzureCredential |
| 107 | + |
| 108 | +`DefaultAzureCredential` is undoubtedly the easiest way to get started with the Azure Identity library, but with that convenience comes tradeoffs. Once you deploy your app to Azure, you should understand the app's authentication requirements. For that reason, strongly consider moving from `DefaultAzureCredential` to one of the following solutions: |
| 109 | + |
| 110 | +- A specific `TokenCredential` implementation, such as `ManagedIdentityCredential`. See the [**Derived** list](/dotnet/api/azure.core.tokencredential?view=azure-dotnet&preserve-view=true#definition) for options. |
| 111 | +- A pared-down `ChainedTokenCredential` implementation optimized for the Azure environment in which your app runs. |
| 112 | + |
| 113 | +Here's why: |
| 114 | + |
| 115 | +- **Debugging challenges**: When authentication fails, it can be challenging to debug and identify the offending credential. You must enable logging to see the progression from one credential to the next and the success/failure status of each. For more information, see [Debug a chained credential](#debug-a-chained-credential). |
| 116 | +- **Performance overhead**: The process of sequentially trying multiple credentials can introduce performance overhead. For example, when running on a local development machine, managed identity is unavailable. Consequently, `ManagedIdentityCredential` always fails in the local development environment, unless explicitly disabled via its corresponding `Exclude`-prefixed property. |
| 117 | +- **Unpredictable behavior**: `DefaultAzureCredential` checks for the presence of certain [environment variables](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md#environment-variables). It's possible that someone could add or modify these 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. |
| 118 | + |
| 119 | +## Debug a chained credential |
| 120 | + |
| 121 | +To diagnose an unexpected issue or to understand what a chained credential is doing, [enable logging](../logging.md) in your app. Optionally, filter the logs to only those events emitted from the Azure Identity library. For example: |
| 122 | + |
| 123 | +:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_FilteredLogging"::: |
| 124 | + |
| 125 | +For illustration purposes, assume the parameterless form of `DefaultAzureCredential` was used to authenticate a request to a Log Analytics workspace. The app ran in the local development environment, and Visual Studio was authenticated to an Azure account. The next time the app ran, the following pertinent entries appeared in the output: |
| 126 | + |
| 127 | +:::code language="output" source="../snippets/authentication/credential-chains/dac-logs.txt"::: |
| 128 | + |
| 129 | +In the preceding output, notice that: |
| 130 | + |
| 131 | +- `EnvironmentCredential`, `WorkloadIdentityCredential`, and `ManagedIdentityCredential` each failed to acquire a Microsoft Entra access token, in that order. |
| 132 | +- The `DefaultAzureCredential credential selected:`-prefixed entry indicates the credential that was selected—`VisualStudioCredential` in this case. Since `VisualStudioCredential` succeeded, no credentials beyond it were used. |
0 commit comments