Compartir a través de

Conexión de la aplicación a Azure AI Search mediante identidades

  • Artículo

En el código de la aplicación, puede configurar una conexión sin claves a Búsqueda de Azure AI que use Microsoft Entra ID y roles para la autenticación y la autorización. Las solicitudes de aplicación a la mayoría de los servicios de Azure se deben autenticar con claves o conexiones sin claves. Los desarrolladores deben ser diligentes para no exponer nunca las claves en una ubicación que no sea segura. Cualquiera que obtenga acceso a la clave se puede autenticar en el servicio. La autenticación sin claves ofrece ventajas mejoradas de administración y seguridad con respecto a la clave de cuenta porque no hay ninguna clave (ni cadena de conexión) que almacenar.

Las conexiones sin claves se habilitan con los pasos siguientes:

  • Configure la autenticación.
  • Establezca variables de entorno, según sea necesario.
  • Use un tipo de credencial de biblioteca de identidades de Azure para crear un objeto de cliente de Búsqueda de Azure AI.

Requisitos previos

Es necesario completar los pasos siguientes para cargas de trabajo de desarrollo y producción locales:

Creación de un recurso de Búsqueda de Azure AI

Antes de continuar con este artículo, necesita un recurso de Búsqueda de Azure AI con el que trabajar. Si no lo tiene, cree el recurso ahora. Habilite el control de acceso basado en roles (RBAC) para el recurso.

Instalación de la biblioteca cliente de identidades de Azure

Para usar un enfoque sin claves, actualice el código habilitado para Búsqueda de Azure AI con la biblioteca cliente de identidades de Azure.

Instale la biblioteca cliente de Azure Identity para .NET:

dotnet add package Azure.Identity

Actualización del código fuente para usar DefaultAzureCredential

DefaultAzureCredential de la biblioteca de identidades de Azure permite ejecutar el mismo código en el entorno de desarrollo local y en la nube de Azure. Cree una sola credencial y reutilice la instancia de credencial según sea necesario para aprovechar el almacenamiento en caché de tokens.

Para más información sobre DefaultAzureCredential para .NET, vea Biblioteca cliente de Azure Identity para .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);

Desarrollo local

El desarrollo local mediante roles incluye estos pasos:

  • Asigne la identidad personal a roles RBAC en el recurso específico.
  • Use una herramienta como la CLI de Azure o Azure PowerShell para autenticarse con Azure.
  • Establezca variables de entorno para el recurso.

Roles para el desarrollo local

Como desarrollador local, la identidad de Azure necesita un control total sobre las operaciones del plano de datos. Estos son los roles sugeridos:

  • Colaborador del servicio Search, creación y administración de objetos
  • Colaborador de datos de índice de búsqueda, carga y consulta de un índice

Busque la identidad personal con una de las herramientas siguientes. Use esa identidad como valor de <identity-id>.

  1. Inicie sesión en la CLI de Azure.

    az login

  2. Obtenga la identidad personal.

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

  3. Asigne el rol de control de acceso basado en roles (RBAC) a la identidad del grupo de recursos.

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

Si procede, reemplace <identity-id>, <subscription-id> y <resource-group-name> por los valores reales.

Autenticación para el desarrollo local

Use una herramienta en el entorno de desarrollo local para la autenticación en la identidad de Azure. Una vez que se haya autenticado, la instancia de DefaultAzureCredential del código fuente busca y usa la autenticación.

Seleccione una herramienta para la autenticación durante el desarrollo local.

Configuración de variables de entorno para el desarrollo local

Para conectarse a Búsqueda de Azure AI, el código debe conocer el punto de conexión del recurso.

Cree una variable de entorno con el nombre AZURE_SEARCH_ENDPOINT para el punto de conexión de Búsqueda de Azure AI. Esta dirección URL generalmente tiene el formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Cargas de trabajo de producción

La implementación de cargas de trabajo de producción incluye estos pasos:

  • Elija roles de RBAC que cumplan el principio de privilegios mínimos.
  • Asigne roles de RBAC a la identidad de producción en el recurso específico.
  • Establezca las variables de entorno para el recurso.

Roles para cargas de trabajo de producción

Para crear los recursos de producción, debe crear una identidad administrada asignada por el usuario asignar esa identidad a los recursos con los roles correctos.

Se recomienda el siguiente rol para una aplicación de producción:

Nombre de rol Identificador
Lector de datos de índice de búsqueda 1407120a-92aa-4202-b7e9-c0e197c71c8f

Autenticación para cargas de trabajo de producción

Use la siguiente plantilla de Bicep de Búsqueda de Azure AI para crear el recurso y establecer la autenticación para identityId. Bicep necesita el identificador de rol. La instancia de name que se muestra en este fragmento de código de Bicep no es el rol de Azure; es específica de la implementación de 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
    }
}

El archivo main.bicep llama al siguiente código genérico de Bicep para crear cualquier rol. Tiene la opción de crear varios roles de RBAC, como uno para el usuario y otro para producción. Esto le permite habilitar entornos de desarrollo y producción dentro de la misma implementación de 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)
    }
}

Configuración de variables de entorno para cargas de trabajo de producción

Para conectarse a Búsqueda de Azure AI, el código debe conocer el punto de conexión del recurso y el id. de la identidad administrada.

Cree variables de entorno para el recurso de Búsqueda de Azure AI implementado y sin claves:

  • AZURE_SEARCH_ENDPOINT: esta dirección URL es el punto de acceso del recurso de Búsqueda de Azure AI. Esta dirección URL generalmente tiene el formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: es la identidad con la que se va a autenticar.

Contenido relacionado