Conexión de un servicio de búsqueda a otros recursos de Azure mediante una identidad administrada

Artículo
04/11/2024

Puede configurar un servicio de Azure AI Search para conectarse a otros recursos de Azure mediante una identidad administrada asignada por el sistema o por el usuario y una asignación de roles de Azure. Las identidades administradas y las asignaciones de roles eliminan la necesidad de pasar secretos y credenciales en una cadena de conexión o el código.

Requisitos previos

Un servicio de búsqueda en el nivel de servicio Básico o superior.
Un recurso de Azure que acepta solicitudes entrantes de un inicio de sesión en Microsoft Entra con una asignación de roles válida.

Escenarios admitidos

Azure AI Search puede usar una identidad administrada asignada por el sistema o asignada por el usuario en conexiones salientes a recursos de Azure. Se indica una identidad administrada del sistema cuando una cadena de conexión es el identificador de recurso único de un servicio o aplicación compatible con Microsoft Entra ID. Una identidad administrada asignada por el usuario se especifica mediante una propiedad "identity".

Un servicio de búsqueda usa Azure Storage como origen de datos de indizador y como receptor de datos para sesiones de depuración, almacenamiento en caché de enriquecimiento y almacén de conocimiento. Para las características de búsqueda que se reescribieron en el almacenamiento, la identidad administrada necesita una asignación de roles de colaborador, tal como se describe en la sección "Asignar un rol".

Escenario	Identidad administrada por el sistema	Identidad administrada asignada por el usuario (versión preliminar)
Conexiones del indizador a orígenes de datos de Azure compatibles¹³	Sí	Sí
Azure Key Vault para claves administradas por el cliente	Sí	Sí
Sesiones de depuración (hospedadas en Azure Storage)¹	Sí	No
Caché de enriquecimiento (hospedada en Azure Storage)¹²	Sí	Sí
Almacén de conocimiento (hospedado en Azure Storage)¹	Sí	Sí
Aptitudes personalizadas (hospedadas en Azure Functions o equivalente)	Sí	Sí
Aptitud de inserción de Azure OpenAI	Sí	Sí
Vectorizador de Azure OpenAI	Sí	Sí

¹ Para la conectividad entre la búsqueda y el almacenamiento, la configuración de seguridad de red impone restricciones en el tipo de identidad administrada que puede usar. Solo se puede usar una identidad administrada del sistema para una conexión de la misma región al almacenamiento a través de la regla de instancia de recurso o excepción de servicio de confianza. Ver Acceso a una cuenta de almacenamiento protegida por red para obtener más información.

² Un método para especificar una caché de enriquecimiento está en el Asistente para importar datos. Actualmente, el asistente no acepta una cadena de conexión de identidad administrada para la caché de enriquecimiento. Sin embargo, una vez completado el asistente, puede actualizar la cadena de conexión en la definición JSON del indizador para especificar una identidad administrada asignada por el sistema o por el usuario y, a continuación, volver a ejecutar el indizador.

³ Tenga en cuenta que deshabilitar claves en la cuenta de almacenamiento de Azure no se admite actualmente en la tabla de Azure que se usa como origen de datos. Aunque la identidad administrada se usa para no proporcionar las claves de almacenamiento explícitamente, el servicio de búsqueda de IA sigue usando las claves para esta implementación.

Creación de una identidad administrada por el sistema

Cuando se habilita una identidad administrada asignada por el sistema, Azure crea una identidad para el servicio de búsqueda que se puede usar para autenticarse en otros servicios de Azure como parte del mismo inquilino y la misma suscripción. Después, puede usar esta identidad en las asignaciones de control de acceso basado en rol de Azure (RBAC de Azure) que permiten el acceso a los datos durante la indexación.

Una identidad administrada asignada por el sistema es única para el servicio de búsqueda y está enlazada al servicio durante su vigencia.

Inicie sesión en Azure Portal y encuentre su servicio de búsqueda.
En Configuración, seleccione Identidad.
En la pestaña Asignado por el sistema, en Estado, seleccione Activado.
Seleccione Guardar.

Después de guardar, verá que se ha asignado un identificador de objeto al servicio de búsqueda.

Consulte Operación Create or Update para crear o actualizar un servicio (API REST de administración).

Puede usar la API REST de administración en lugar del portal para asignar una identidad administrada por el usuario asignado.

Formule una solicitud a fin de aplicar la operación Create or Update para crear o actualizar un servicio de búsqueda.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

En la respuesta se devuelve la confirmación y un identificador de objeto para la identidad administrada por el sistema.

Cree una identidad administrada asignada por el usuario (UAMI) (versión preliminar)

Una identidad administrada asignada por el usuario es un recurso en Azure. Resulta útil si necesita una mayor granularidad en las asignaciones de roles, ya que puede crear identidades independientes para diferentes aplicaciones y escenarios.

Importante

Esta característica se encuentra en versión preliminar pública en los Términos de uso complementarios. Las identidades administradas asignadas por el usuario no se admiten actualmente para las conexiones a una cuenta de almacenamiento protegida por red. La solicitud de búsqueda actualmente requiere una dirección IP pública.

Azure Portal
REST API

Inicie sesión en el Portal de Azure
Seleccione + Crear un recurso.
En la barra de búsqueda "Servicios de búsqueda y Marketplace", busque "Identidad administrada asignada por el usuario" y, después, seleccione Crear.
Seleccione la suscripción, el grupo de recursos y la región. Asigne un nombre descriptivo a la identidad.
Seleccione Crear y espere a que el recurso termine de implementarse.

En los siguientes pasos, asignará la identidad administrada por el usuario asignado al servicio de búsqueda.
En la página del servicio de búsqueda, en Configuración, seleccione Identidad.
En la pestaña Usuario asignado, seleccione Agregar.
Elija la suscripción y, a continuación, seleccione el recurso administrado asignado por el usuario que creó en el paso anterior.

Puede usar la API REST de administración en lugar del portal para asignar una identidad administrada por el usuario asignado. Asegúrese de usar la versión 2021-04-01-preview para esta tarea.

Formule una solicitud a fin de aplicar la operación Create or Update para crear o actualizar un servicio de búsqueda.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2021-04-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Establezca la propiedad "identity" para especificar una identidad administrada completa:
- El parámetro "type" es el tipo de identidad. Los valores válidos son "SystemAssigned", "UserAssigned" o "SystemAssigned, UserAssigned" para ambos. Un valor de "None" borrará del servicio de búsqueda las identidades asignadas previamente.
- El parámetro "userAssignedIdentities" incluye los detalles de la identidad administrada asignada por el usuario. Esta identidad ya debe existir para poder especificarla en la solicitud de la operación Create or Update para crear o actualizar un servicio.

Permiso de acceso al firewall

Si el recurso de Azure está detrás de un firewall, asegúrese de que hay una regla de entrada que admite solicitudes del servicio de búsqueda.

Para las conexiones de la misma región a Azure Blob Storage o Azure Data Lake Storage Gen2, use una identidad administrada de sistema y la excepción de servicio de confianza. Opcionalmente, puede configurar una regla de instancia de recurso para admitir solicitudes.
Para todos los demás recursos y conexiones, configure una regla de firewall de IP que admita solicitudes de búsqueda. Consulte Acceso del indizador a orígenes de datos mediante las características de seguridad de red de Azure para obtener información.

Asignar un rol

Una identidad administrada debe emparejarse con un rol de Azure que determine los permisos en el recurso de Azure.

Se necesitan permisos de lector de datos para las conexiones de datos del indexador y para acceder a una clave administrada por el cliente en Azure Key Vault.
Se necesitan permisos de colaborador (escritura) para las características de enriquecimiento con IA que usan Azure Storage para hospedar datos de sesión de depuración, almacenamiento en caché enriquecido y almacenamiento de contenido a largo plazo en un almacén de conocimiento.

A continuación, se incluyen los pasos para Azure Storage. Si el recurso es Azure Cosmos DB o Azure SQL, los pasos son similares.

Inicie sesión en Azure Portal y busque el recurso de Azure, al que debe tener acceso el servicio de búsqueda.
En Azure Storage, seleccione Control de acceso (IAM) en el panel de navegación izquierdo.
Seleccione Agregar asignación de roles.

En la página Rol, seleccione los roles necesarios para el servicio de búsqueda:

Tarea	Asignación de roles
Indexación de blobs mediante un indexador	Agregar Lector de datos de Storage Blob
Indexación de ADLS Gen2 mediante un indexador	Agregar Lector de datos de Storage Blob
Indexación de tablas mediante un indexador	Agregar Lector y acceso a datos
Indexación de archivos mediante un indexador	Agregar Lector y acceso a datos
Escribir en un almacén de conocimiento	Agregar Colaborador de datos de Storage Blob para proyecciones de objetos y archivos, y Lector y acceso a datos para proyecciones de tablas.
Escribir en una caché de enriquecimiento	Agregar Colaborador de datos de Storage Blob
Guardar el estado de la sesión de depuración	Agregar Colaborador de datos de Storage Blob
Inserción de datos (vectorización) mediante modelos de inserción de Azure OpenAI	Adición de usuarios de OpenAI de Cognitive Services

En la página Miembros, seleccione Identidad administrada.
Seleccionar miembros. En la página Seleccionar identidad administrada, elija la suscripción, filtre por tipo de servicio y, a continuación, seleccione el servicio. Solo se podrán seleccionar los servicios que tengan una identidad administrada.
Seleccione Revisar y asignar.

Ejemplos de cadena de conexión

Una vez definida una identidad administrada para el servicio de búsqueda y dada una asignación de roles, las conexiones salientes se pueden modificar para usar el identificador de recurso único del otro recurso de Azure. A continuación, se incluyen algunos ejemplos de cadenas de conexión para varios escenarios.

Origen de datos de blob (sistema):

Un origen de datos del indexador incluye una propiedad "credentials" que determina cómo se realiza la conexión con el origen de datos. En el ejemplo siguiente se muestra una cadena de conexión que especifica el identificador de recurso único de una cuenta de almacenamiento. Microsoft Entra ID autenticará la solicitud mediante la identidad administrada del sistema del servicio de búsqueda. Observe que la cadena de conexión no incluye un contenedor. En la definición de un origen de datos, se especifica un nombre de contenedor en la propiedad "container" (no se muestra), no en la cadena de conexión.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Origen de datos de blob (usuario):

También se puede realizar una solicitud de búsqueda para Azure Storage en una identidad administrada asignada por el usuario, actualmente en versión preliminar. La identidad de usuario del servicio de búsqueda se especifica en la propiedad "identity". Puede usar el portal o la versión preliminar de la API REST 2021-04-30-Preview para establecer la identidad.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Almacén de conocimiento:

Una definición de almacén de conocimiento incluye una cadena de conexión a Azure Storage. En Azure Storage, un almacén de conocimiento creará proyecciones como blobs y tablas. La cadena de conexión es el identificador de recurso único de la cuenta de almacenamiento. Observe que la cadena no incluye contenedores ni tablas en la ruta de acceso. Estos elementos se definen en la definición de proyección insertada, no en la cadena de conexión.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Caché de enriquecimiento:

Un indexador crea, usa y recuerda el contenedor usado para los enriquecimientos en caché. No es necesario incluir el contenedor en la cadena de conexión de la caché. Puede encontrar el identificador de objeto en la página Identidad del servicio de búsqueda en el portal.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Sesión de depuración:

Una sesión de depuración se ejecuta en el portal y toma una cadena de conexión al iniciar la sesión. Puede pegar una cadena de conexión es similar a la del ejemplo siguiente.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Aptitud personalizada:

Una aptitud personalizada tiene como destino el punto de conexión de una función de Azure o una aplicación que hospeda código personalizado. El punto de conexión se especifica en la definición de aptitud personalizada. La presencia de "authResourceId" indica al servicio de búsqueda que se conecte mediante una identidad administrada, pasando el identificador de aplicación de la función o la aplicación de destino en la propiedad.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Aptitud de inserción de Azure OpenAI y vectorizador de Azure OpenAI:

Una aptitud y un vectorizador de inserción de Azure OpenAI en la Búsqueda de AI tienen como destino el punto de conexión de un servicio de OpenAI de Azure que hospeda un modelo de inserción. El punto de conexión se especifica en la definición de aptitud de inserción de Azure OpenAI o en la definición de vectorizador de Azure OpenAI. La identidad administrada por el sistema se usa si está configurada y si "apikey" y "authIdentity" están vacías. La propiedad "authIdentity" solo se usa para la identidad administrada asignada por el usuario.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002"
      }
    }
  ]