Partager via

Connecter votre application à Azure AI Search à l’aide d’identités

Dans votre code d’application, vous pouvez configurer une connexion sans clé à Azure AI Search qui utilise l’ID Et les rôles Microsoft Entra pour l’authentification et l’autorisation. Les demandes d’application adressées à la plupart des services Azure doivent être authentifiées avec des clés ou des connexions sans clé. Les développeurs doivent être vigilants pour ne jamais exposer les clés dans un emplacement non sécurisé. Toute personne ayant accès à la clé est en mesure de s’authentifier auprès du service. L’authentification sans clé offre des avantages de gestion et de sécurité améliorés sur la clé de compte, car il n’existe aucune clé (ou chaîne de connexion) à stocker.

Cet article explique comment utiliser DefaultAzureCredential dans le code de votre application.

Pour implémenter des connexions sans clé dans votre code, procédez comme suit :

  • Activer l’accès en fonction du rôle sur votre service de recherche
  • Définissez des variables d’environnement, si nécessaire.
  • Utilisez un type d’informations d’identification de la bibliothèque d’identités Azure pour créer un objet client Azure AI Search.

Prerequisites

  • Recherche d’IA Azure, n’importe quelle région, mais il doit s’agir d’un niveau facturable (de base ou supérieur).

  • Accès en fonction du rôle activé sur votre service de recherche.

  • Attributions de rôles sur Azure Cognitive Search. Attribuez ces rôles à votre identité :

    • Contributeur de service de recherche et Contributeur de données d’index de recherche pour le développement local (accès complet)
    • Lecteur de données d’index de recherche pour les requêtes en lecture seule en production

    Pour obtenir des instructions pas à pas, consultez Affecter des rôles pour le développement.

Installer la bibliothèque de client Azure Identity

Pour utiliser une approche sans clé, mettez à jour votre code activé par la recherche IA avec la bibliothèque de client Azure Identity.

Installez la bibliothèque de client Azure Identity pour .NET et la bibliothèque de client Documents Recherche Azure :

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

Mettre à jour le code source pour utiliser DefaultAzureCredential

La bibliothèque d’identités Azure vous permet d’exécuter le même code dans l’environnement DefaultAzureCredential de développement local et dans le cloud Azure. Créez des informations d’identification uniques et réutilisez l’instance d’informations d’identification si nécessaire pour tirer parti de la mise en cache des jetons.

Pour plus d’informations sur DefaultAzureCredential .NET, consultez la bibliothèque de client Azure Identity pour .NET.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

Reference :SearchClient, SearchIndexClient, DefaultAzureCredential

Vérifier votre connexion

Après avoir configuré le client, vérifiez votre connexion en exécutant une opération simple. L’exemple suivant répertorie les index sur votre service de recherche :

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

Une connexion réussie imprime les noms de vos index (ou une liste vide si aucun index n’existe). Si vous recevez une erreur d’authentification, vérifiez que l’accès en fonction du rôle est activé et que votre identité a les attributions de rôles requises.

L’autorité par défaut est le cloud public Azure. Les valeurs personnalisées audience pour les clouds souverains ou spécialisés sont les suivantes :

  • https://search.azure.us pour Azure Government
  • https://search.azure.cn pour Azure géré par 21Vianet
  • https://search.microsoftazure.de pour Azure Allemagne

Développement local

Le développement local à l’aide de rôles inclut les étapes suivantes :

  • Effectuez l’affectation de votre identité personnelle aux rôles RBAC sur la ressource spécifique.
  • Utilisez un outil comme Azure CLI ou Azure PowerShell pour vous authentifier auprès d’Azure.
  • Établissez des variables d’environnement pour votre ressource.

Rôles pour le développement local

En tant que développeur local, votre identité Azure a besoin d’un contrôle total sur les opérations de plan de données. Voici les rôles suggérés :

  • Contributeur de service de recherche, création et gestion d’objets
  • Contributeur aux données d’index de recherche, chargement et interrogation d’un index

Recherchez votre identité personnelle avec l’un des outils suivants. Utilisez cette identité comme valeur <identity-id>.

Remplacez les balises de remplacement <role-name>, <identity-id>, <subscription-id> et <resource-group-name> par vos valeurs réelles dans les commandes suivantes.

  1. Connectez-vous à Azure CLI.

    az login

    Une fenêtre de navigateur s’ouvre pour l’authentification. Une fois la connexion réussie, le terminal affiche vos informations d’abonnement.

  2. Obtenez votre identité personnelle.

    az ad signed-in-user show \
    --query id -o tsv

    La commande retourne votre ID d’objet utilisateur (un GUID). Enregistrez cette valeur pour l’étape suivante.

  3. Attribuez le rôle de contrôle d’accès en fonction du rôle (RBAC) à l’identité du groupe de ressources.

    az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

    Une attribution réussie retourne un objet JSON avec les détails de l’attribution de rôle.

Authentification pour le développement local

Utilisez un outil dans votre environnement de développement local pour l’authentification auprès d’une identité Azure. Une fois que vous êtes authentifié, l’instance DefaultAzureCredential de votre code source recherche et utilise votre identité à des fins d’authentification.

Sélectionnez un outil pour l’authentification pendant le développement local.

Configurer des variables d’environnement pour le développement local

Pour vous connecter à Azure AI Search, votre code doit connaître votre point de terminaison de ressource.

Créez une variable d’environnement nommée AZURE_SEARCH_ENDPOINT pour votre point de terminaison Recherche AZURE AI. Cette URL a généralement le format https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Charges de travail de production

Déployer des charges de travail de production inclut les étapes suivantes :

  • Choisissez des rôles RBAC qui respectent le principe du moindre privilège.
  • Attribuez des rôles RBAC à votre identité de production sur la ressource spécifique.
  • Configurez des variables d’environnement pour votre ressource.

Rôles pour les charges de travail de production

Pour créer vos ressources de production, vous devez créer une identité managée affectée par l’utilisateur , puis affecter cette identité à vos ressources avec les rôles appropriés.

Le rôle suivant est suggéré pour une application de production :

Nom du rôle Id
Lecteur de données d’index de recherche 1407120a-92aa-4202-b7e9-c0e197c71c8f

Authentification pour les charges opérationnelles de production

Utilisez le modèle Bicep de recherche Azure AI suivant pour créer la ressource et définir l’authentification pour le identityId. Bicep nécessite l’ID de rôle. Le name figurant dans l’extrait de code Bicep n’est pas le rôle Azure ; il est spécifique au déploiement Bicep.

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

Le main.bicep fichier appelle le code Bicep générique suivant pour créer n’importe quel rôle. Vous avez la possibilité de créer plusieurs rôles RBAC, tels qu’un pour l’utilisateur et un autre pour la production. Cela vous permet d’activer les environnements de développement et de production au sein du même déploiement Bicep.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

Configurer des variables d’environnement pour les charges de travail de production

Pour vous connecter à Azure AI Search, votre code doit connaître votre point de terminaison de ressource et l’ID de l’identité managée.

Créez des variables d’environnement pour votre ressource Azure AI Search déployée et sans clé :

  • AZURE_SEARCH_ENDPOINT: cette URL est le point d’accès de votre ressource Recherche d’IA Azure. Cette URL a généralement le format https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: Il s'agit de l'identité à utiliser pour s'authentifier.

Résoudre les erreurs courantes

Erreur La cause Solution
AuthenticationFailedException Informations d’identification manquantes ou non valides Vérifiez que vous êtes connecté avec az login (CLI) ou Connect-AzAccount (PowerShell). Vérifiez que votre compte Azure a accès à l’abonnement.
403 Forbidden L'identité manque d'un rôle requis. Attribuez le rôle approprié (Lecteur de données d’index de recherche pour les requêtes, Contributeur aux données d’index de recherche pour l’indexation). Les attributions de rôle peuvent prendre jusqu’à 10 minutes pour se propager.
401 Unauthorized RBAC non activé sur le service de recherche Activez l’accès en fonction du rôle dans le portail Azure sous Paramètres>clés>d’accès en fonction du rôle.
ResourceNotFoundException Nom du point de terminaison ou de l’index non valide Vérifiez que la variable d’environnement correspond à l’URL AZURE_SEARCH_ENDPOINT de votre service de recherche (format : https://<service-name>.search.windows.net).
CredentialUnavailableException Aucune information d’identification valide trouvée DefaultAzureCredential tente plusieurs méthodes d’authentification. Vérifiez qu’au moins un est configuré (Azure CLI, Visual Studio, variables d’environnement).

Contenu connexe

  • Last updated on