bibliothèque de client d’identité Azure pour C - version 1.13.3

++

La bibliothèque d’identités Azure fournit Microsoft Entra ID la prise en charge de l’authentification basée sur les jetons dans le Kit de développement logiciel (SDK) Azure. Il fournit un ensemble d’implémentations TokenCredential qui peuvent être utilisées pour construire des clients du Kit de développement logiciel (SDK) Azure qui prennent en charge l’authentification par jeton Microsoft Entra. Cette bibliothèque suit les instructions de conception du Kit de développement logiciel (SDK) Azure pour C++.

Code source | Package (vcpkg) | Documentation de | Documentation | Échantillons

Mise en route

Prerequisites

  • vcpkg pour l’acquisition de package et la gestion des dépendances
  • CMake pour la génération de projet
  • Un abonnement Azure
  • Azure CLI peut également être utile pour l’authentification dans un environnement de développement, la création de comptes et la gestion des rôles de compte.

Installer le package

Le moyen le plus simple d’acquérir le Kit de développement logiciel (SDK) C++ utilise le gestionnaire de package vcpkg et CMake. Consultez la section lisez-moi correspondante du Kit de développement logiciel (SDK) Azure pour C++. Nous allons utiliser vcpkg en mode manifeste. Pour démarrer un projet vcpkg en mode manifeste, utilisez la commande suivante à la racine de votre projet :

vcpkg new --application

Pour installer le package Azure Identity via vcpkg : pour ajouter le package Azure Identity à votre vcpkg, entrez la commande suivante :

vcpkg add port azure-identity-cpp

Ajoutez ensuite ce qui suit dans votre fichier CMake :

find_package(azure-identity-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-identity)

N’oubliez pas de définir CMAKE_TOOLCHAIN_FILE le chemin d’accès à l’un ou l’autre vcpkg.cmake en ajoutant ce qui suit à votre CMakeLists.txt fichier avant l’instruction de votre projet :

set(CMAKE_TOOLCHAIN_FILE "vcpkg-root/scripts/buildsystems/vcpkg.cmake")

Ou en le spécifiant dans vos commandes CMake avec l’argument -DCMAKE_TOOLCHAIN_FILE .

Il existe plusieurs façons d’acquérir et d’installer cette bibliothèque. Consultez nos exemples sur différentes façons de configurer votre projet Azure C++.

Authentifier le client

Lors du débogage et de l’exécution de code localement, il est courant qu’un développeur utilise son propre compte pour authentifier les appels aux services Azure. Il existe plusieurs outils de développement qui peuvent être utilisés pour effectuer cette authentification dans votre environnement de développement.

S’authentifier via Azure CLI

Les développeurs peuvent utiliser Azure CLI pour s’authentifier. Les applications utilisant DefaultAzureCredential ou AzureCliCredential peuvent ensuite utiliser ce compte pour authentifier les appels dans leur application lorsqu'elles sont exécutées localement.

Pour vous authentifier auprès d’Azure CLI, les utilisateurs peuvent exécuter la commande az login. Pour les utilisateurs s’exécutant sur un système avec un navigateur web par défaut, Azure CLI lance le navigateur pour authentifier l’utilisateur.

Concepts clés

Credentials

Les informations d’identification sont une classe qui contient ou peut obtenir les données nécessaires pour qu’un client de service authentifie les demandes. Les clients de service dans le Kit de développement logiciel (SDK) Azure acceptent les informations d’identification lorsqu’ils sont construits, et les clients de service utilisent ces informations d’identification pour authentifier les demandes auprès du service.

La bibliothèque d’identités Azure se concentre sur l’authentification OAuth avec l’ID Microsoft Entra et offre une variété de classes d’informations d’identification capables d’acquérir un jeton Microsoft Entra pour authentifier les demandes de service. Toutes les classes d’informations d’identification de cette bibliothèque sont des implémentations de la TokenCredential classe abstraite dans azure-core, et l’une d’entre elles peut être utilisée pour construire des clients de service capables d’s’authentifier avec un TokenCredential.

Pour obtenir la liste complète des types d’informations d’identification disponibles, consultez Classes d’informations d’identification .

DefaultAzureCredential

DefaultAzureCredentialsimplifie l’authentification lors du développement d’applications qui se déploient sur Azure en combinant les informations d’identification utilisées dans les environnements d’hébergement Azure avec celles utilisées dans le développement local. Pour plus d’informations, consultez la vue d’ensemble de DefaultAzureCredential.

Examples

Consultez les exemples de code.

Informations d’identification du jeton chaîné

ChainedTokenCredential permet aux utilisateurs de configurer un flux d’authentification personnalisé composé de plusieurs informations d’identification.

Un exemple ci-dessous illustre l’utilisation ChainedTokenCredential de laquelle tentera de s’authentifier à l’aide EnvironmentCredentialde , puis revenez à l’authentification à l’aide ManagedIdentityCredentialde .

// A configuration demonstrated below would authenticate using EnvironmentCredential if it is
// available, and if it is not available, would fall back to use AzureCliCredential, and then to
// ManagedIdentityCredential.
auto chainedTokenCredential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
    Azure::Identity::ChainedTokenCredential::Sources{
        std::make_shared<Azure::Identity::EnvironmentCredential>(),
        std::make_shared<Azure::Identity::AzureCliCredential>(),
        std::make_shared<Azure::Identity::ManagedIdentityCredential>()});

Azure::Service::Client azureServiceClient("serviceUrl", chainedTokenCredential);

Prise en charge des identités managées

L’authentification d’identité managée est prise en charge via les ManagedIdentityCredential services Azure suivants :

Spécifier une identité managée affectée par l’utilisateur avec ManagedIdentityCredential

De nombreux hôtes Azure autorisent l’attribution d’une identité managée affectée par l’utilisateur. Les exemples suivants illustrent la configuration ManagedIdentityCredential pour authentifier une identité managée affectée par l’utilisateur lorsqu’elle est déployée sur un hôte Azure. L’exemple de code utilise les informations d’identification pour authentifier une BlobClient bibliothèque cliente Azure ::Storage ::Blobs . Il montre également comment spécifier une identité managée affectée par l’utilisateur par un ID client, un ID de ressource ou un ID d’objet.

ID de client

Pour utiliser un ID client, créez un ManagedIdentityId avec ManagedIdentityIdKind::ClientId, définissez-le comme dans IdentityId le ManagedIdentityCredentialOptions, puis passez-le au ManagedIdentityCredential constructeur. Par exemple:

// When deployed to an Azure host, ManagedIdentityCredential will authenticate the specified
// user-assigned managed identity.

std::string userAssignedClientId = "<your managed identity client ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::FromUserAssignedClientId(userAssignedClientId);

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

ID de ressource

De même, pour utiliser un ID de ressource, créez un ManagedIdentityId avec ManagedIdentityIdKind::ResourceId, définissez-le comme IdentityId dans le ManagedIdentityCredentialOptions, puis transmettez-le au ManagedIdentityCredential constructeur. L’ID de ressource prend la forme /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}. Étant donné que les ID de ressource peuvent être générés par convention, ils peuvent être plus pratiques lorsqu’il existe un grand nombre d’identités managées affectées par l’utilisateur dans votre environnement. Par exemple:

std::string userAssignedResourceId = "/subscriptions/<your managed identity resource ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::FromUserAssignedResourceId(
    Azure::Core::ResourceIdentifier(userAssignedResourceId));

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

ID d’objet

De même, pour utiliser un ID d’objet, créez un ManagedIdentityId avec ManagedIdentityIdKind::ObjectId, définissez-le comme IdentityId dans le ManagedIdentityCredentialOptions, puis transmettez-le au ManagedIdentityCredential constructeur. Par exemple:

std::string userAssignedObjectId = "<your managed identity object ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::FromUserAssignedObjectId(userAssignedObjectId);

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

Spécifier une identité managée affectée par le système avec ManagedIdentityCredential

Vous pouvez exprimer votre intention d’utiliser une identité managée affectée par le système, explicitement, en créant une ManagedIdentityId valeur avec ManagedIdentityIdKind::SystemAssigned et une valeur d’ID vide, définissez-la IdentityId comme dans le ManagedIdentityCredentialOptions, puis transmettez-la au ManagedIdentityCredential constructeur. Par exemple:

ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::SystemAssigned();

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

Une autre façon de spécifier une identité managée affectée par le système, implicitement, consiste à appeler le constructeur par défaut ManagedIdentityCredential . Par exemple:

auto credential = std::make_shared<ManagedIdentityCredential>();
auto blobClient = BlobClient(blobUrl, credential);

Variables d’environnement

DefaultAzureCredential et EnvironmentCredential peuvent être configurés avec des variables d’environnement. Chaque type d’authentification nécessite des valeurs pour des variables spécifiques :

Principal de service avec une clé secrète

Nom de la variable Valeur
AZURE_TENANT_ID ID du locataire Microsoft Entra de l’application
AZURE_CLIENT_ID ID d’une application Microsoft Entra
AZURE_CLIENT_SECRET l’un des secrets clients de l’application
AZURE_AUTHORITY_HOST (facultatif) URL de l’autorité d’authentification

Principal de service avec un certificat

nom de la variable Valeur
AZURE_CLIENT_ID ID d’une application Microsoft Entra
AZURE_TENANT_ID ID du locataire Microsoft Entra de l’application
AZURE_CLIENT_CERTIFICATE_PATH chemin d’accès à un fichier de certificat encodé PFX ou PEM, y compris une clé privée
AZURE_AUTHORITY_HOST (facultatif) URL de l’autorité d’authentification

La configuration est tentée dans l’ordre ci-dessus. Par exemple, si les valeurs d’une clé secrète client et d’un certificat sont présentes, la clé secrète client est utilisée.

Classes d’informations d’identification

Chaînes d'accréditation

Credential Usage
DefaultAzureCredential Fournit une expérience d’authentification simplifiée pour commencer rapidement à développer des applications exécutées dans Azure.
ChainedTokenCredential Permet aux utilisateurs de définir des flux d’authentification personnalisés qui composent plusieurs informations d’identification.

Authentifier des applications hébergées par Azure

Credential Usage
ManagedIdentityCredential Authentifie l’identité managée d’une ressource Azure.
EnvironmentCredential Authentifie un principal de service ou un utilisateur via des informations d’identification spécifiées dans les variables d’environnement.
WorkloadIdentityCredential Authentifier une identité de charge de travail sur Kubernetes.

Authentifier les principaux de service

Credential Usage
AzurePipelinesCredential Prend en charge ID de charge de travail Microsoft Entra sur Azure Pipelines.
ClientAssertionCredential Authentifie un principal de service à l’aide d’une assertion de client signée.
ClientSecretCredential Authentifie un principal de service à l’aide d’un secret.
ClientCertificateCredential Authentifie un principal de service à l’aide d’un certificat.

S’authentifier via des outils de développement

Credential Usage
AzureCliCredential Authentifie dans un environnement de développement avec Azure CLI.

Résolution des problèmes

  1. Les messages du journal du KIT de développement logiciel (SDK) Azure Identity contiennent des informations disgnostiques et commencent par «Identity: ».
  2. Les informations d’identification déclenchent des exceptions lorsqu’elles ne parviennent pas à s’authentifier ou ne peuvent pas exécuter l’authentification. Lorsqu’une information d’identification ne parvient pas à s’authentifier, une AuthenticationException information est levée. L’exception a la what() fonction qui fournit plus d’informations sur l’échec.

Contribution

Pour plus d’informations sur la contribution à ce référentiel, consultez le guide de contribution.

Ce projet accueille les contributions et suggestions. La plupart des contributions vous obligent à accepter un contrat de licence contributeur (CLA) déclarant que vous avez le droit, et en fait, de nous accorder les droits d’utilisation de votre contribution. Pour plus d’informations, consultez le Contrat de licence contributeur.

Lorsque vous envoyez une demande de tirage( pull request), un bot CLA détermine automatiquement si vous devez fournir un CLA et décorer correctement la demande de tirage (par exemple, étiquette, commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source Microsoft. Pour plus d’informations, consultez le forum aux questions du Code de conduite ou contactez avec des questions ou commentaires supplémentaires.

Beaucoup de gens du monde entier ont contribué à améliorer ce projet. Vous voudrez consulter :

Signaler des problèmes de sécurité et des bogues de sécurité

Les problèmes de sécurité et les bogues doivent être signalés en privé, par e-mail, au Centre d'intervention en matière de sécurité Microsoft (MSRC). secure@microsoft.com Vous devez recevoir une réponse dans les 24 heures. Si pour une raison quelconque vous ne le faites pas, veuillez suivre par e-mail pour vous assurer que nous avons reçu votre message d’origine. Vous trouverez plus d’informations, notamment la clé PGP MSRC, dans Security TechCenter.

Licence

Le Kit de développement logiciel (SDK) Azure pour C++ est concédé sous licence MIT .

  • Last updated on