Utiliser Recherche Azure AI sans clé

  • Article

Dans votre code d’application, vous pouvez configurer une connexion sans clé à Recherche Azure AI qui utilise Microsoft Entra ID et les rôles 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.

Les connexions sans clé sont activées via les étapes suivantes :

  • Configurez votre authentification.
  • 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 Recherche Azure AI.

Prérequis

Les étapes suivantes doivent être effectuées pour les charges de travail de développement et de production locales :

Créer une ressource Recherche AI

Avant de continuer avec cet article, vous avez besoin d’une ressource Recherche Azure AI. Si vous n’avez pas de ressource, créez en une maintenant. Activez le contrôle d’accès en fonction du rôle (RBAC) pour la ressource.

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 :

dotnet add package Azure.Identity

Mettre à jour le code source pour utiliser DefaultAzureCredential

Le DefaultAzureCredential de la bibliothèque d’identité Azure vous permet d’exécuter le même code dans l’environnement 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 pour .NET, consultez 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);

Développement local

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

  • Attribuez votre identité personnelle avec des 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, chargez un index
  • Lecteur de données d’index de recherche, demande un index

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

  1. Connectez-vous à Azure CLI.

    az login

  2. Obtenez votre identité personnelle.

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

  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>"

Le cas échéant, remplacez <identity-id>, <subscription-id> et <resource-group-name> par vos valeurs réelles.

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 l’authentification.

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

Pour vous connecter à Recherche Azure AI, 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 privilège minimum.
  • 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 attribuée par l’utilisateur, puis attribuer cette identité à vos ressources avec les rôles appropriés.

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

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

Authentification pour les charges de travail de production

Utilisez le modèle Bicep 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 fichier main.bicep 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 à Recherche Azure AI, 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 Recherche Azure AI déployée et sans clé :

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

Contenu connexe