Cadenas de credenciales en la biblioteca cliente de Identidad de Azure para C++

La biblioteca cliente de Identidad de Azure proporciona credenciales: tipos públicos que derivan de la clase base abstracta 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.

Funcionamiento de una credencial encadenada

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:

¿Por qué usar cadenas de credenciales?

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:

  // Set up credential based on environment (Azure or local development)
  std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
  if (!std::getenv("WEBSITE_HOSTNAME"))
  {
      credential = std::make_shared<Azure::Identity::AzureCliCredential>();
  }
  else
  {
      credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
  }
  

• 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.

• Resiliencia mejorada: incluye un mecanismo de respaldo que pasa a la siguiente credencial cuando la anterior no logra obtener un token de acceso.

Cómo elegir una credencial encadenada

Con C++, hay dos opciones para el encadenamiento de credenciales:

• Usa una cadena preconfigurada: utiliza la cadena preconfigurada implementada por el tipo DefaultAzureCredential. Para este enfoque, consulte la sección Información general sobre DefaultAzureCredential.
• Crear una cadena de credenciales personalizada: comience con una cadena vacía e incluya solo lo que necesita. Para este enfoque, consulte la sección Información general sobre ChainedTokenCredential.

Información general sobre DefaultAzureCredential

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:

El orden en el que DefaultAzureCredential intenta las credenciales es el siguiente.

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

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

Información general sobre ChainedTokenCredential

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

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::AzureCliCredential>(),
            std::make_shared<Azure::Identity::ManagedIdentityCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

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

Guía de uso para DefaultAzureCredential

DefaultAzureCredential es sin duda la manera más fácil de empezar a trabajar con la biblioteca cliente de Azure Identity, pero esa comodidad viene con ciertas 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.

Este es el motivo:

• 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 tanto, ManagedIdentityCredential siempre produce un error en el entorno de desarrollo local.
• 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.

Depuración de una credencial encadenada

Para diagnosticar un problema inesperado o comprender lo que hace una credencial encadenada, habilite el registro en la aplicación. Para que se vea de ejemplo, supongamos que se usa la forma sin parámetros de DefaultAzureCredential para autenticar una solicitud en una cuenta de Blob Storage. La aplicación se ejecuta en el entorno de desarrollo local y el desarrollador se autentica en Azure mediante la CLI de Azure. Cuando se ejecuta la aplicación, aparecen las siguientes entradas pertinentes en la salida:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, AzureCliCredential, ManagedIdentityCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 11223344-5566-7788-9900-aabbccddeeff Correlation ID: ffeeddcc-bbaa-9988-7766-554433221100 Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"11223344-5566-7788-9900-aabbccddeeff","correlation_id":"ffeeddcc-bbaa-9988-7766-554433221100","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"01234567-89ab-cdef-fedc-ba9876543210\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from AzureCliCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

En la salida anterior, puede ver lo siguiente:

• EnvironmentCredential, WorkloadIdentityCredential y cada uno fracasó en adquirir un token de acceso de Microsoft Entra, en ese orden.
• El AzureCliCredential tiene éxito, como lo indica una entrada que comienza con "Successfully got token from AzureCliCredential". Dado que AzureCliCredential se autenticó correctamente, no se intentaron otras credenciales adicionales.