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:

Diagrama que muestra la secuencia de la cadena de credenciales.

¿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::ManagedIdentityCredential>();
}
else
{
    credential = std::make_shared<Azure::Identity::AzureCliCredential>();
}

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. Su diseño admite 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:

Diagrama que muestra el flujo de autenticación DefaultAzureCredential.

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

Pedido	Credencial	Descripción
1	Medio ambiente	Lee una colección de variables de entorno para determinar si un principal de servicio de aplicación (usuario de aplicación) está configurado para la aplicación. Si es así, `DefaultAzureCredential` usa estos valores para autenticar la aplicación en Azure. Este método se usa con más frecuencia en entornos de servidor, pero también se puede usar al desarrollar localmente.
2	Identidad de carga de trabajo	Si la aplicación se implementa en un host de Azure con la identidad de carga de trabajo habilitada, autentica esa cuenta.
3	Identidad administrada	Si la aplicación se implementa en un host de Azure con la identidad administrada habilitada, se autentica la aplicación en Azure usando esa identidad administrada.
4	Azure CLI	Si el desarrollador se autenticó en Azure mediante el comando `az login` de la CLI de Azure, se autentica la aplicación en Azure con esa misma cuenta.

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};
}

Personalización de DefaultAzureCredential

En las secciones siguientes se describen las estrategias para controlar qué credenciales se incluyen en la cadena.

Excluir una categoría de tipo de credencial

Para excluir todas las credenciales Developer tool o Deployed service, establezca la variable de entorno AZURE_TOKEN_CREDENTIALS a prod o dev, respectivamente. Cuando se usa un valor de prod, la cadena de credenciales subyacente tiene el siguiente aspecto:

Diagrama que muestra DefaultAzureCredential con AZURE_TOKEN_CREDENTIALS establecido en

Cuando se usa un valor de dev , la cadena solo incluye AzureCliCredential.

Para asegurarse de que la variable de entorno está definida y establecida en una cadena admitida, pase true al DefaultAzureCredential constructor :

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Importante

La mencionada sobrecarga del constructor se admite en las versiones del paquete azure-identity-cpp 1.13.1 y posteriores.

Uso de una credencial específica

Para excluir todas las credenciales excepto para una, establezca la variable AZURE_TOKEN_CREDENTIALS de entorno en el nombre de la credencial. Por ejemplo, puede reducir la DefaultAzureCredential cadena a AzureCliCredential estableciendo AZURE_TOKEN_CREDENTIALS en AzureCliCredential. La comparación de cadenas se realiza de forma que no distingue mayúsculas de minúsculas. Entre los valores de cadena válidos para la variable de entorno se incluyen:

AzureCliCredential
EnvironmentCredential
ManagedIdentityCredential
WorkloadIdentityCredential

Para asegurarse de que la variable de entorno está definida y establecida en una cadena admitida, pase true al DefaultAzureCredential constructor :

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Importante

La mencionada sobrecarga del constructor se admite en las versiones del paquete azure-identity-cpp 1.13.1 y posteriores.

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::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // 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 ManagedIdentityCredential, seguido de AzureCliCredentialsi es necesario. En forma gráfica, la cadena tiene este aspecto:

Diagrama que muestra el flujo de autenticación de una instancia ChainedTokenCredential compuesta por ManagedIdentityCredential y AzureCliCredential.

Sugerencia

Para mejorar el rendimiento, optimice el orden de las credenciales en ChainedTokenCredential de la mayoría a las credenciales menos usadas.

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.
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: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
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: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
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 ManagedIdentityCredential. 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 ManagedIdentityCredential no pudieron adquirir un token de acceso de Microsoft Entra, en ese orden.
ManagedIdentityCredential tiene éxito, como se indica en una entrada que comienza por "Successfully got token from ManagedIdentityCredential".

Comentarios

¿Le resultó útil esta página?

Last updated on 2025-11-24