Partage via

Développer des applications Azure AI services avec Azure Key Vault

  • Article

Découvrez comment développer des applications Azure AI Services en toute sécurité en utilisant Azure Key Vault.

Key Vault réduit les risques de fuite accidentelle des secrets, car vous évitez de stocker les informations de sécurité dans votre application.

Prérequis

Remarque

Passez en revue la documentation et les articles de démarrage rapide pour le service Azure AI que vous utilisez pour comprendre les points suivants :

  • Les informations d’identification et d’autres informations dont vous aurez besoin pour envoyer des appels d’API.
  • Les packages et le code dont vous aurez besoin pour exécuter votre application.

Obtenir vos informations d’identification à partir de votre ressource Azure AI Services

Avant d’ajouter vos informations d’identification à votre coffre de clés Azure, vous devez les récupérer à partir de votre ressource Azure AI Services. Par exemple, si votre service a besoin d’une clé et d’un point de terminaison, vous les trouverez en procédant comme suit :

  1. Accédez à votre ressource Azure dans le portail Azure.

  2. Dans le menu réductible de gauche, sélectionnez Clés et point de terminaison.

    Capture d’écran montrant la page de la clé et du point de terminaison sur le Portail Azure.

Certains Azure AI Services nécessitent différentes informations pour authentifier les appels d’API, tels qu’une clé et une région. Veillez à récupérer ces informations avant de continuer.

Ajouter vos informations d’identification à votre coffre de clés

Pour que votre application récupère et utilise vos informations d’identification pour authentifier les appels d’API, vous devez les ajouter à vos secrets de coffre de clés.

Répétez ces étapes pour générer un secret pour chaque informations d’identification de ressource requises. Par exemple, une clé et un point de terminaison. Ces noms de secrets seront utilisés ultérieurement pour authentifier votre application.

  1. Ouvrez une nouvel onglet ou une nouvelle fenêtre de navigateur. Accédez à votre coffre de clés dans le Portail Azure.

  2. Dans le menu réductible de gauche, sélectionnez Objets>Secrets.

  3. Sélectionnez Générer/Importer.

    Capture d’écran montrant la page de la clé du coffre de clés sur le Portail Azure.

  4. Sur l’écran Créer un secret, entrez les valeurs suivantes :

    Nom Valeur
    Options de chargement Manuel
    Nom Nom du secret de votre clé ou de votre point de terminaison. Par exemple : « CognitiveServicesKey » ou « CognitiveServicesEndpoint »
    Valeur Votre clé ou point de terminaison de ressource Azure AI Services.

    Plus tard, votre application utilisera le secret « Name » pour accéder en toute sécurité à la « Valeur ».

  5. Conservez les valeurs par défaut des autres options. Sélectionnez Create (Créer).

    Conseil

    Veillez à mémoriser les noms que vous définissez pour vos secrets, car vous les utiliserez plus tard dans votre application.

Vous devez maintenant avoir des secrets nommés pour vos informations de ressource.

Créer une variable d’environnement pour le nom de votre coffre de clés

Nous vous recommandons de créer une variable d’environnement pour le nom de votre coffre de clés Azure. Votre application lit cette variable d’environnement au moment de l’exécution pour récupérer vos informations de clé et de point de terminaison.

Pour définir des variables d’environnement, utilisez l’une des commandes suivantes. KEY_VAULT_NAME par le nom de la variable d’environnement, puis remplacez Your-Key-Vault-Name par le nom de votre coffre de clés, qui sera stocké dans la variable d’environnement.

Créez et assignez une variable d’environnement persistante, en fonction de la valeur donnée.

setx KEY_VAULT_NAME "Your-Key-Vault-Name"

Dans une nouvelle instance de l’invite de commandes, lisez la variable d’environnement.

echo %KEY_VAULT_NAME%

S’authentifier auprès d’Azure à l’aide de Visual Studio

Les développeurs utilisant Visual Studio 2017 ou version ultérieure peuvent authentifier un compte Microsoft Entra via Visual Studio. Cela vous permet d’accéder aux secrets dans votre coffre de clés en vous connectant à votre abonnement Azure à partir de l’IDE.

Pour vous authentifier dans Visual Studio, sélectionnez Outils dans le menu de navigation supérieur, puis sélectionnez Options. Accédez à l’option Azure Service Authentication pour vous connecter avec votre nom d’utilisateur et votre mot de passe.

S’authentifier à l’aide de la ligne de commande

Avant de pouvoir accorder l’accès à votre coffre de clés, vous devez vous authentifier avec votre nom d’utilisateur et mot de passe Microsoft Entra.

Pour une authentification avec Azure CLI, exécutez la commande az login.

az login

Sur les systèmes avec un navigateur web par défaut, Azure CLI lance le navigateur pour l’authentification. Sur les systèmes sans navigateur web par défaut, la commande az login utilise le flux d’authentification de code d’appareil. Vous pouvez également spécifier l’argument --use-device-code pour forcer Azure CLI à utiliser le flux de code d’appareil au lieu de lancer un navigateur.

Si vous avez plusieurs abonnements, veillez à sélectionner l’abonnement Azure qui contient votre coffre de clés.

Accorder l’accès à votre coffre de clés

Créez une stratégie d’accès pour votre coffre de clés, qui accorde des autorisations de secret à votre compte d’utilisateur.

Pour définir la stratégie d’accès, exécutez la commande az keyvault set-policy. Remplacez Your-Key-Vault-Name par le nom de votre coffre de clés. Remplacez user@domain.com par votre nom d’utilisateur Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Créer une application C#

En utilisant l’IDE Visual Studio, créez une application console .NET Core. Cette action va créer un projet nommé « Hello World » avec un seul fichier source C# : program.cs.

Installez les bibliothèques clientes suivantes en cliquant avec le bouton droit sur la solution dans l’Explorateur de solutions et en sélectionnant Gérer les packages NuGet. Dans le gestionnaire de package qui s’ouvre, sélectionnez Parcourir et recherchez les bibliothèques suivantes, puis sélectionnez Installer pour chacune d’elles :

  • Azure.Security.KeyVault.Secrets
  • Azure.Identity

Importer l’exemple de code

Copiez le code exemple suivant dans votre fichier program.cs. Remplacez Your-Key-Secret-Name et Your-Endpoint-Secret-Name par les noms de secrets que vous définissez dans votre coffre de clés.

using System;
using System.Threading.Tasks;
using Azure;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using System.Net;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            //Name of your key vault
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");

            //variables for retrieving the key and endpoint from your key vault.
            //Set these variables to the names you created for your secrets
            const string keySecretName = "Your-Key-Secret-Name";
            const string endpointSecretName = "Your-Endpoint-Secret-Name";

            //Endpoint for accessing your key vault
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var keyVaultClient = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.WriteLine($"Retrieving your secrets from {keyVaultName}.");

            //Key and endpoint secrets retrieved from your key vault
            var keySecret = await keyVaultClient.GetSecretAsync(keySecretName);
            var endpointSecret = await keyVaultClient.GetSecretAsync(endpointSecretName);
            Console.WriteLine($"Your key secret value is: {keySecret.Value.Value}");
            Console.WriteLine($"Your endpoint secret value is: {endpointSecret.Value.Value}");
            Console.WriteLine("Secrets retrieved successfully");

        }
    }
}

Exécution de l'application

Exécutez l’application en sélectionnant le bouton Déboguer en haut de Visual Studio. Vos secrets de clé et de point de terminaison seront récupérés à partir de votre coffre de clés.

Envoyer un appel de service de langage de test (facultatif)

Si vous utilisez une ressource multiservices ou une ressource de langage, vous pouvez mettre à jour votre application en suivant ces étapes pour envoyer un exemple d’appel Reconnaissance d’entité nommée en récupérant une clé et un point de terminaison à partir de votre coffre de clés.

  1. Installez la bibliothèque Azure.AI.TextAnalytics en cliquant avec le bouton droit sur la solution dans l’Explorateur de solutions et en sélectionnant Gérer les packages NuGet. Dans le gestionnaire de package qui s’ouvre, sélectionnez Parcourir et recherchez les bibliothèques suivantes, puis sélectionnez Installer pour chacune d’elles :

  2. Ajoutez la directive suivante en haut du fichier program.cs.

    using Azure.AI.TextAnalytics;

  3. Ajoutez l’exemple code suivant à votre application.

    // Example method for extracting named entities from text 
private static void EntityRecognitionExample(string keySecret, string endpointSecret)
{
    //String to be sent for Named Entity Recognition
    var exampleString = "I had a wonderful trip to Seattle last week.";

    AzureKeyCredential azureKeyCredential = new AzureKeyCredential(keySecret);
    Uri endpoint = new Uri(endpointSecret);
    var languageServiceClient = new TextAnalyticsClient(endpoint, azureKeyCredential);

    Console.WriteLine($"Sending a Named Entity Recognition (NER) request");
    var response = languageServiceClient.RecognizeEntities(exampleString);
    Console.WriteLine("Named Entities:");
    foreach (var entity in response.Value)
    {
        Console.WriteLine($"\tText: {entity.Text},\tCategory: {entity.Category},\tSub-Category: {entity.SubCategory}");
        Console.WriteLine($"\t\tScore: {entity.ConfidenceScore:F2},\tLength: {entity.Length},\tOffset: {entity.Offset}\n");
    }
}

  4. Ajoutez le code suivant pour appeler EntityRecognitionExample() à partir de votre méthode principale, avec vos valeurs de clé et de point de terminaison.

    EntityRecognitionExample(keySecret.Value.Value, endpointSecret.Value.Value);

  5. Exécutez l'application.

Authentifier votre application

Avant de pouvoir accorder l’accès à votre coffre de clés, vous devez vous authentifier avec votre nom d’utilisateur et mot de passe Microsoft Entra.

Pour une authentification avec Azure CLI, exécutez la commande az login.

az login

Sur les systèmes avec un navigateur web par défaut, Azure CLI lance le navigateur pour l’authentification. Sur les systèmes sans navigateur web par défaut, la commande az login utilise le flux d’authentification de code d’appareil. Vous pouvez également spécifier l’argument --use-device-code pour forcer Azure CLI à utiliser le flux de code d’appareil au lieu de lancer un navigateur.

Si vous avez plusieurs abonnements, veillez à sélectionner l’abonnement Azure qui contient votre coffre de clés.

Accorder l’accès à votre coffre de clés

Créez une stratégie d’accès pour votre coffre de clés, qui accorde des autorisations de secret à votre compte d’utilisateur.

Pour définir la stratégie d’accès, exécutez la commande az keyvault set-policy. Remplacez Your-Key-Vault-Name par le nom de votre coffre de clés. Remplacez user@domain.com par votre nom d’utilisateur Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Créer une application Python

Créez un dossier nommé keyVaultExample. Utilisez ensuite votre éditeur de code préféré pour créer un fichier nommé program.py dans le dossier nouvellement créé.

Installer Key Vault et les packages de service Language

  1. Dans un terminal ou une invite de commandes, accédez au dossier de votre projet et installez la bibliothèque d’identités Microsoft Entra :

    pip install azure-identity

  2. Installez la bibliothèque de secrets Key Vault :

    pip install azure-keyvault-secrets

Importer l’exemple de code

Ajoutez l’exemple code suivant au fichier nommé program.py. Remplacez Your-Key-Secret-Name et Your-Endpoint-Secret-Name par les noms de secrets que vous définissez dans votre coffre de clés.

import os
from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
from azure.core.credentials import AzureKeyCredential

keyVaultName = os.environ["KEY_VAULT_NAME"]

# Set these variables to the names you created for your secrets
keySecretName = "Your-Key-Secret-Name"
endpointSecretName = "Your-Endpoint-Secret-Name"

# URI for accessing key vault
KVUri = f"https://{keyVaultName}.vault.azure.net"

# Instantiate the client and retrieve secrets
credential = DefaultAzureCredential()
kv_client = SecretClient(vault_url=KVUri, credential=credential)

print(f"Retrieving your secrets from {keyVaultName}.")

retrieved_key = kv_client.get_secret(keySecretName).value
retrieved_endpoint = kv_client.get_secret(endpointSecretName).value

print(f"Your secret key value is {retrieved_key}.");
print(f"Your secret endpoint value is {retrieved_endpoint}.");

Exécution de l'application

Utilisez la commande suivante pour exécuter l’application. Vos secrets de clé et de point de terminaison seront récupérés à partir de votre coffre de clés.

python ./program.py

Envoyer un appel de service de langage de test (facultatif)

Si vous utilisez une ressource multiservices ou une ressource de langage, vous pouvez mettre à jour votre application en suivant ces étapes pour envoyer un exemple d’appel Reconnaissance d’entité nommée en récupérant une clé et un point de terminaison à partir de votre coffre de clés.

  1. Installez la bibliothèque de service de langage :

    pip install azure-ai-textanalytics==5.1.0

  2. Ajoutez le code suivant à votre application

    from azure.ai.textanalytics import TextAnalyticsClient
# Authenticate the key vault secrets client using your key and endpoint 
azure_key_credential = AzureKeyCredential(retrieved_key)
# Now you can use key vault credentials with the Language service
language_service_client = TextAnalyticsClient(
    endpoint=retrieved_endpoint, 
    credential=azure_key_credential)

# Example of recognizing entities from text

print("Sending NER request")

try:
    documents = ["I had a wonderful trip to Seattle last week."]
    result = language_service_client.recognize_entities(documents = documents)[0]
    print("Named Entities:\n")
    for entity in result.entities:
        print("\tText: \t", entity.text, "\tCategory: \t", entity.category, "\tSubCategory: \t", entity.subcategory,
                "\n\tConfidence Score: \t", round(entity.confidence_score, 2), "\tLength: \t", entity.length, "\tOffset: \t", entity.offset, "\n")

except Exception as err:
    print("Encountered exception. {}".format(err))

  3. Exécutez l'application.

Authentifier votre application

Avant de pouvoir accorder l’accès à votre coffre de clés, vous devez vous authentifier avec votre nom d’utilisateur et mot de passe Microsoft Entra.

Pour une authentification avec Azure CLI, exécutez la commande az login.

az login

Sur les systèmes avec un navigateur web par défaut, Azure CLI lance le navigateur pour l’authentification. Sur les systèmes sans navigateur web par défaut, la commande az login utilise le flux d’authentification de code d’appareil. Vous pouvez également spécifier l’argument --use-device-code pour forcer Azure CLI à utiliser le flux de code d’appareil au lieu de lancer un navigateur.

Si vous avez plusieurs abonnements, veillez à sélectionner l’abonnement Azure qui contient votre coffre de clés.

Accorder l’accès à votre coffre de clés

Créez une stratégie d’accès pour votre coffre de clés, qui accorde des autorisations de secret à votre compte d’utilisateur.

Pour définir la stratégie d’accès, exécutez la commande az keyvault set-policy. Remplacez Your-Key-Vault-Name par le nom de votre coffre de clés. Remplacez user@domain.com par votre nom d’utilisateur Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Créer une application Java

Dans votre IDE préféré, créez un projet d’application console Java et créez une classe nommée Example.

Ajout de dépendances

Dans votre projet, ajoutez les dépendances suivantes à votre fichier pom.xml.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-security-keyvault-secrets</artifactId>
        <version>4.2.3</version>
    </dependency>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity</artifactId>
        <version>1.2.0</version>
    </dependency>
</dependencies>

Importer l’exemple de code

Copiez le code suivant dans un fichier nommé Example.java. Remplacez Your-Key-Secret-Name et Your-Endpoint-Secret-Name par les noms de secrets que vous définissez dans votre coffre de clés.

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.core.credential.AzureKeyCredential;

public class Example {

    public static void main(String[] args) {

        String keyVaultName = System.getenv("KEY_VAULT_NAME");
        String keyVaultUri = "https://" + keyVaultName + ".vault.azure.net";

        //variables for retrieving the key and endpoint from your key vault.
        //Set these variables to the names you created for your secrets
        String keySecretName = "Your-Key-Secret-Name";
        String endpointSecretName = "Your-Endpoint-Secret-Name";

        //Create key vault secrets client
        SecretClient secretClient = new SecretClientBuilder()
                .vaultUrl(keyVaultUri)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();

        //retrieve key and endpoint from key vault
        String keyValue = secretClient.getSecret(keySecretName).getValue();
        String endpointValue = secretClient.getSecret(endpointSecretName).getValue();
        System.out.printf("Your secret key value is: %s", keyValue)
        System.out.printf("Your secret endpoint value is: %s", endpointValue)
    }
}

Envoyer un appel de service de langage de test (facultatif)

Si vous utilisez une ressource multiservices ou une ressource de langage, vous pouvez mettre à jour votre application en suivant ces étapes pour envoyer un exemple d’appel Reconnaissance d’entité nommée en récupérant une clé et un point de terminaison à partir de votre coffre de clés.

  1. Dans votre application, ajoutez la dépendance suivante :

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
    <version>5.1.12</version>
</dependency>

  2. ajoutez les instructions d’importation suivantes à votre fichier.

    import com.azure.ai.textanalytics.models.*;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.TextAnalyticsClient;

  3. Ajoutez le code suivant à la méthode main() dans votre application :

    
TextAnalyticsClient languageClient = new TextAnalyticsClientBuilder()
        .credential(new AzureKeyCredential(keyValue))
        .endpoint(endpointValue)
        .buildClient();

// Example for recognizing entities in text
String text = "I had a wonderful trip to Seattle last week.";

for (CategorizedEntity entity : languageClient.recognizeEntities(text)) {
    System.out.printf(
            "Recognized entity: %s, entity category: %s, entity sub-category: %s, score: %s, offset: %s, length: %s.%n",
            entity.getText(),
            entity.getCategory(),
            entity.getSubcategory(),
            entity.getConfidenceScore(),
            entity.getOffset(),
            entity.getLength());
}

  4. Exécuter votre application

Authentifier votre application

Avant de pouvoir accorder l’accès à votre coffre de clés, vous devez vous authentifier avec votre nom d’utilisateur et mot de passe Microsoft Entra.

Pour une authentification avec Azure CLI, exécutez la commande az login.

az login

Sur les systèmes avec un navigateur web par défaut, Azure CLI lance le navigateur pour l’authentification. Sur les systèmes sans navigateur web par défaut, la commande az login utilise le flux d’authentification de code d’appareil. Vous pouvez également spécifier l’argument --use-device-code pour forcer Azure CLI à utiliser le flux de code d’appareil au lieu de lancer un navigateur.

Si vous avez plusieurs abonnements, veillez à sélectionner l’abonnement Azure qui contient votre coffre de clés.

Accorder l’accès à votre coffre de clés

Créez une stratégie d’accès pour votre coffre de clés, qui accorde des autorisations de secret à votre compte d’utilisateur.

Pour définir la stratégie d’accès, exécutez la commande az keyvault set-policy. Remplacez Your-Key-Vault-Name par le nom de votre coffre de clés. Remplacez user@domain.com par votre nom d’utilisateur Microsoft Entra.

az keyvault set-policy --name Your-Key-Vault-Name --upn user@domain.com --secret-permissions delete get list set purge

Création d’une application Node.js

Créez une application Node.js qui utilise votre coffre-fort de clé.

Dans un terminal, créez un dossier nommé key-vault-js-example et modifiez-le dans ce dossier :

mkdir key-vault-js-example && cd key-vault-js-example

Initialiser le projet Node.js :

npm init -y

Installer Key Vault et les packages de service Language

  1. À l’aide du terminal, installez la bibliothèque de secrets Azure Key Vault, @azure/keyvault-certificates pour Node.js.

    npm install @azure/keyvault-secrets

  2. Installez la bibliothèque d’identité Azure, @azure/package d’identité pour vous authentifier dans un coffre-fort de clé.

    npm install @azure/identity

Importer l’exemple de code

Ajoutez l’exemple code suivant à un fichier nommé index.js. Remplacez Your-Key-Secret-Name et Your-Endpoint-Secret-Name par les noms de secrets que vous définissez dans votre coffre de clés.

const { SecretClient } = require("@azure/keyvault-secrets");
const { DefaultAzureCredential } = require("@azure/identity");
// Load the .env file if it exists
const dotenv = require("dotenv");
dotenv.config();

async function main() {
    const credential = new DefaultAzureCredential();

    const keyVaultName = process.env["KEY_VAULT_NAME"];
    const url = "https://" + keyVaultName + ".vault.azure.net";

    const kvClient = new SecretClient(url, credential);

    // Set these variables to the names you created for your secrets
    const keySecretName = "Your-Key-Secret-Name";
    const endpointSecretName = "Your-Endpoint-Secret-Name";

    console.log("Retrieving secrets from ", keyVaultName);
    const retrievedKey = await (await kvClient.getSecret(keySecretName)).value;
    const retrievedEndpoint = await (await kvClient.getSecret(endpointSecretName)).value;
    console.log("Your secret key value is: ", retrievedKey);
    console.log("Your secret endpoint value is: ", retrievedEndpoint);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Exécuter l’exemple d’application

Utilisez la commande suivante pour exécuter l’application. Vos secrets de clé et de point de terminaison seront récupérés à partir de votre coffre de clés.

node index.js

Envoyer un appel de service de langage de test (facultatif)

Si vous utilisez une ressource multiservices ou une ressource de langage, vous pouvez mettre à jour votre application en suivant ces étapes pour envoyer un exemple d’appel Reconnaissance d’entité nommée en récupérant une clé et un point de terminaison à partir de votre coffre de clés.

  1. Installez la bibliothèque Azure AI Service for Language, @azure/ai-text-analytics pour envoyer des demandes d’API au service Language.

    npm install @azure/ai-text-analytics@5.1.0

  2. Ajoutez le code suivant à votre application :

    const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
// Authenticate the language client with your key and endpoint
const languageClient = new TextAnalyticsClient(retrievedEndpoint,  new AzureKeyCredential(retrievedKey));

// Example for recognizing entities in text
console.log("Sending NER request")
const entityInputs = [
    "I had a wonderful trip to Seattle last week."
];
const entityResults = await languageClient.recognizeEntities(entityInputs);
entityResults.forEach(document => {
    console.log(`Document ID: ${document.id}`);
    document.entities.forEach(entity => {
        console.log(`\tName: ${entity.text} \tCategory: ${entity.category} \tSubcategory: ${entity.subCategory ? entity.subCategory : "N/A"}`);
        console.log(`\tScore: ${entity.confidenceScore}`);
    });
});

  3. Exécutez l'application.

Étapes suivantes