Cadenas de credenciales en la biblioteca de identidades de Azure para .NET

La biblioteca de identidades de Azure proporciona credenciales, clases públicas derivadas de la clase TokenCredential de la biblioteca de Azure Core. Una credencial representa un flujo de autenticación distinto para adquirir un token de acceso de Microsoft Entra ID. Estas credenciales se pueden encadenar para formar una secuencia ordenada de mecanismos de autenticación que se van a intentar.

En tiempo de ejecución, una cadena de credenciales intenta autenticarse mediante la primera credencial de la secuencia. Si esa credencial no puede adquirir un token de acceso, se intenta utilizar la siguiente credencial de la secuencia, y así sucesivamente hasta que se obtenga correctamente un token de acceso. En el siguiente diagrama de secuencia se ilustra este comportamiento:

Una credencial encadenada puede ofrecer las siguientes ventajas:

• Reconocimiento del entorno: selecciona automáticamente la credencial más adecuada en función del entorno en el que se ejecuta la aplicación. Sin ella, tendría que escribir código como este:

  TokenCredential credential;
  
  if (app.Environment.IsProduction() || app.Environment.IsStaging())
  {
      credential = new ManagedIdentityCredential(
          ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
  }
  else
  {
      // local development environment
      credential = new VisualStudioCredential();
  }
  

• Transiciones fluidas: la aplicación puede pasar del desarrollo local al entorno de ensayo o producción sin cambiar el código de autenticación.

• Resistencia mejorada: incluye un mecanismo de reserva que pasa a la siguiente credencial cuando la anterior no puede adquirir un token de acceso.

Hay dos filosofías dispares para encadenar credenciales:

• "Desmontar" una cadena: comience con una cadena preconfigurada y excluya lo que no necesita. Para este enfoque, consulte la sección Información general sobre DefaultAzureCredential.
• "Crear" una cadena: comience con una cadena vacía e incluya solo lo que necesita. Para este enfoque, consulte la sección Información general sobre ChainedTokenCredential.

DefaultAzureCredential es una cadena preconfigurada de credenciales fundamentada. Está diseñada para admitir muchos entornos, junto con los flujos de autenticación y las herramientas de desarrollo más comunes. En forma gráfica, la cadena subyacente tiene este aspecto:

Orden en el que DefaultAzureCredential intenta las credenciales.

En su forma más sencilla, puede usar la versión sin parámetros de DefaultAzureCredential de la siguiente manera:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

Para quitar una credencial de DefaultAzureCredential, use la propiedad correspondiente con el prefijo Exclude en DefaultAzureCredentialOptions. Por ejemplo:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

En el ejemplo de código anterior, EnvironmentCredential, ManagedIdentityCredentialy WorkloadIdentityCredential se quitan de la cadena de credenciales. Como resultado, la primera credencial que se va a intentar es VisualStudioCredential. La cadena modificada contiene únicamente credenciales de tiempo de desarrollo y se ve así:

A medida que se establecen más propiedades con el prefijo Exclude en true (se configuran exclusiones de credenciales), las ventajas de usar DefaultAzureCredential disminuyen. En tales casos, ChainedTokenCredential es una mejor opción y requiere menos código. Para ilustrarlo, estos dos ejemplos de código se comportan de la misma manera:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
    });

credential = new ChainedTokenCredential(
    new VisualStudioCredential(),
    new AzureCliCredential());

ChainedTokenCredential es una cadena vacía a la que agrega credenciales para satisfacer las necesidades de la aplicación. Por ejemplo:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

El ejemplo de código anterior crea una cadena de credenciales adaptada formada por dos credenciales en tiempo de desarrollo. Primero se intenta AzurePowerShellCredential, seguido de VisualStudioCredentialsi es necesario. En forma gráfica, la cadena tiene este aspecto:

DefaultAzureCredential es, sin duda, la manera más fácil de empezar a trabajar con la biblioteca de identidades de Azure, pero esa comodidad conlleva ventajas y desventajas. Una vez que implemente la aplicación en Azure, debe comprender los requisitos de autenticación de la aplicación. Por ese motivo, reemplace DefaultAzureCredential por una implementación de TokenCredential específica, como ManagedIdentityCredential. Consulte la lista de Derived para ver las opciones.

Aquí se detallan los motivos:

• Desafíos de depuración: cuando se produce un error en la autenticación, puede resultar difícil depurar e identificar las credenciales incorrectas. Debe habilitar el registro para ver la progresión de una credencial a la siguiente y el estado de éxito o error de cada una. Para obtener más información, consulte Depuración de una credencial encadenada.
• Sobrecarga de rendimiento: el proceso de probar secuencialmente varias credenciales puede suponer una sobrecarga de rendimiento. Por ejemplo, cuando se ejecuta en una máquina de desarrollo local, la identidad administrada no está disponible. Por lo tanto, ManagedIdentityCredential siempre falla en el entorno de desarrollo local, a menos que se deshabilite explícitamente a través de su propiedad con prefijo Exclude correspondiente.
• Comportamiento imprevisible: DefaultAzureCredential comprueba la presencia de determinadas variables de entorno. Es posible que alguien pueda agregar o modificar estas variables de entorno en el nivel de sistema en el equipo host. Esos cambios se aplican globalmente y, por tanto, modifican el comportamiento de DefaultAzureCredential en tiempo de ejecución en cualquier aplicación que se ejecute en esa máquina. Para obtener más información sobre la imprevisibilidad, consulte Uso de credenciales deterministas en entornos de producción.

Para diagnosticar un problema inesperado o comprender lo que hace una credencial encadenada, habilite el registro en la aplicación. Opcionalmente, filtre los registros solo a esos eventos emitidos desde la biblioteca de identidades de Azure. Por ejemplo:

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

Para fines ilustrativos, supongamos que se usó la forma sin parámetros de DefaultAzureCredential para autenticar una solicitud en un área de trabajo de Log Analytics. La aplicación se ejecutó en el entorno de desarrollo local y Visual Studio se autenticó en una cuenta de Azure. La siguiente vez que se ejecutó la aplicación, aparecieron las siguientes entradas pertinentes en la salida:

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

En la salida anterior, puede ver lo siguiente:

• EnvironmentCredential, WorkloadIdentityCredential y ManagedIdentityCredential no pudieron adquirir un token de acceso de Microsoft Entra, en ese orden.
• La entrada con prefijo DefaultAzureCredential credential selected: indica la credencial seleccionada, VisualStudioCredential en este caso. Dado que VisualStudioCredential se realizó correctamente, no se usaron más credenciales.