Compartir a través de

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

En el código de la aplicación, puede configurar una conexión sin claves a Azure AI Search que use el identificador y los roles de Microsoft Entra para la autenticación y autorización. Las solicitudes de aplicación a la mayoría de los servicios de Azure deben autenticarse 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.

En este artículo se explica cómo usar DefaultAzureCredential en el código de la aplicación.

Para implementar conexiones sin claves en el código, siga estos pasos:

  • Habilitación del acceso basado en roles en el servicio de búsqueda
  • 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 Azure AI Search.

Prerrequisitos

  • Azure AI Search, cualquier región, pero debe ser un nivel facturable (básico o superior).

  • Acceso basado en rol habilitado en el servicio de búsqueda.

  • Asignaciones de roles en Azure AI Search. Asigne estos roles a su identidad:

    • Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda para el desarrollo local (acceso completo)
    • Lector de datos de índice de búsqueda para consultas de producción de solo lectura

    Para obtener instrucciones paso a paso, consulte Asignación de roles para el desarrollo.

Instalación de la biblioteca cliente de identidades de Azure

Para usar un enfoque sin claves, actualice el código habilitado para AI Search con la biblioteca cliente de Identidad de Azure.

Instale la biblioteca cliente de Azure Identity para .NET y la biblioteca cliente de documentos de Azure Search:

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

Actualización del código fuente para usar DefaultAzureCredential

La biblioteca de identidades de DefaultAzureCredential 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, consulte la Biblioteca cliente de Identidad de Azure 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);

Reference:SearchClient, SearchIndexClient, DefaultAzureCredential

Comprobación de la conexión

Después de configurar el cliente, compruebe la conexión ejecutando una operación sencilla. En el ejemplo siguiente se enumeran los índices del servicio de búsqueda:

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

Una conexión correcta imprime los nombres de los índices (o una lista vacía si no existe ningún índice). Si recibe un error de autenticación, compruebe que el acceso basado en roles está habilitado y la identidad tiene las asignaciones de roles necesarias.

La entidad predeterminada es la nube pública de Azure. Los valores personalizados audience para nubes soberanas o especializadas incluyen:

  • https://search.azure.us para Azure Government
  • https://search.azure.cn para Azure operado por 21Vianet
  • https://search.microsoftazure.de para Azure Alemania

Desarrollo local

El desarrollo local mediante los roles incluye estos pasos:

  • Asigne su identidad personal a roles de 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, su identidad de Azure necesita tener un control total sobre las operaciones del plano de datos. Estos son los roles sugeridos:

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

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

Reemplace los marcadores de posición <role-name>, <identity-id>, <subscription-id>, y <resource-group-name> por los valores reales en los siguientes comandos.

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

    az login

    Se abre una ventana del explorador para la autenticación. Después de iniciar sesión correctamente, el terminal muestra la información de la suscripción.

  2. Obtenga su identidad personal.

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

    El comando devuelve el identificador de objeto de usuario (un GUID). Guarde este valor para el siguiente paso.

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

    Una asignación correcta devuelve un objeto JSON con los detalles de asignación de roles.

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 autenticado, la DefaultAzureCredential instancia del código fuente busca y usa la identidad con fines de 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 Azure AI Search, el código debe conocer el punto de conexión del recurso.

Cree una variable de entorno denominada AZURE_SEARCH_ENDPOINT para el punto de conexión de Azure AI Search. 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 RBAC a la identidad de producción en el recurso específico.
  • Configure 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 y, a continuación, asignar esa identidad a los recursos con los roles correctos.

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

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

Autenticación para cargas de trabajo en entornos de producción

Utilice la siguiente plantilla de Bicep de Azure AI Search para crear el recurso y establecer la autenticación para el 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 un rol. Tiene la opción de crear varios roles 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 Azure AI Search, el código debe conocer el punto de conexión del recurso y el identificador de la identidad administrada.

Cree variables de entorno para el recurso de Azure AI Search implementado y sin claves:

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

Solución de errores comunes

Error Causa Solución
AuthenticationFailedException Falta o credenciales no válidas Asegúrese de que ha iniciado sesión con az login (CLI) o Connect-AzAccount (PowerShell). Compruebe que la cuenta de Azure tiene acceso a la suscripción.
403 Forbidden La identidad carece de rol necesario Asigne el rol adecuado (Lector de datos de índice de búsqueda para consultas, Colaborador de datos de índice de búsqueda para la indexación). Las asignaciones de roles pueden tardar hasta 10 minutos en propagarse.
401 Unauthorized RBAC no habilitado en el servicio de búsqueda Active el acceso basado en roles en el portal de Azure en Configuración>Claves>Control de acceso basado en roles.
ResourceNotFoundException Nombre de índice o punto de conexión no válido Compruebe que la variable de entorno coincide con la AZURE_SEARCH_ENDPOINT dirección URL del servicio de búsqueda (formato: https://<service-name>.search.windows.net).
CredentialUnavailableException No se encontró ninguna credencial válida DefaultAzureCredential intenta varios métodos de autenticación. Asegúrese de que se ha configurado al menos uno (CLI de Azure, Visual Studio, variables de entorno).

Contenido relacionado

  • Last updated on