Configuración de un servicio de búsqueda para conectarse mediante una identidad administrada

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Puede utilizar los principios de seguridad de Microsoft Entra ID y las asignaciones de roles para las conexiones salientes desde Búsqueda de Azure AI hacia otros recursos de Azure que proporcionen datos, inteligencia artificial aplicada o vectorización durante la indexación o las consultas.

Para usar roles en una conexión saliente, primero configure el servicio de búsqueda para que use una identidad administrada asignada por el sistema o por el usuario como entidad de seguridad para su servicio de búsqueda en un inquilino de Microsoft Entra. Después de tener una identidad administrada, puede asignar roles para el acceso autorizado. Las identidades administradas y las asignaciones de roles eliminan la necesidad de pasar secretos y credenciales en una cadena de conexión o código.

Requisitos previos

Un servicio Búsqueda de Azure AI en cualquier región de la categoría Basic o superior.
Un recurso de Azure que acepta las solicitudes entrantes de una entidad de seguridad de Microsoft Entra que tiene una asignación de roles válida.
Para crear una identidad administrada, debe ser propietario o administrador de acceso de usuario. Para asignar roles, debe ser propietario, administrador de acceso de usuarios, administrador de control de acceso basado en roles o miembro de un rol personalizado con permisos Microsoft.Authorization/roleAssignments/write.

Escenarios admitidos

Puede usar identidades administradas para los escenarios siguientes.

Escenario	Sistema asignado	Usuario asignado
Conexión a orígenes de datos del indexador¹	Sí	Sí
Conexión a modelos de inserción y finalización de chat en Azure OpenAI, Microsoft Foundry y Azure Functions a través de skills/vectorizers ²	Sí	Sí
Conectarse a Azure Key Vault para claves administradas por el cliente	Sí	Sí
Conectar a sesiones de depuración (alojadas en Azure Storage)¹	Sí	No
Conexión a una caché de enriquecimiento hospedada en Azure Storage (versión preliminar)^1,3	Sí	Sí ⁴
Connect to a Knowledge Store (hospedado en Azure Storage)¹	Sí	Sí

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

² Conexiones a Azure OpenAI, Foundry y Azure Functions a través de habilidades/vectorizadores incluyen: Habilidad personalizada, Vectorizador personalizado, Habilidad de incrustación de Azure OpenAI, OpenAI vectorizador de Azure, Habilidad de aprendizaje automático de Azure (AML) y vectorizador de catálogo de modelos de Microsoft Foundry.

³ El servicio de búsqueda de IA no puede conectarse actualmente a tablas en una cuenta de almacenamiento que tenga desactivado el acceso a claves compartidas.

⁴ La identidad administrada asignada por el usuario para las conexiones de caché de enriquecimiento requiere una API REST en versión preliminar (2025-11-01-preview o posterior) o un paquete sdk de versión preliminar. Todos los demás escenarios de identidad administrada asignadas por el usuario de esta tabla se admiten en la API REST versión 2026-04-01 y versiones posteriores.

Creación de una identidad administrada por el sistema

Una identidad administrada asignada por el sistema es un principal de seguridad de Microsoft Entra ID que se crea automáticamente y se vincula a un recurso de Azure, como un servicio de Búsqueda de Azure AI.

Puede tener una identidad administrada asignada por el sistema para cada servicio de búsqueda. Es único para el servicio de búsqueda y está enlazado al servicio durante su vigencia.

Al habilitar una identidad administrada asignada por el sistema, Microsoft Entra ID crea una entidad de seguridad para el servicio de búsqueda que se usa para autenticarse en otros recursos de Azure. A continuación, puede usar esta identidad en asignaciones de roles para el acceso autorizado a los datos y las operaciones.

Vaya al servicio de búsqueda en el portal Azure.
En el panel izquierdo, seleccione Configuración>Identidad.
En la pestaña Asignado por el sistema , en Estado, seleccione Activado.
Seleccione Guardar.

Después de guardar la configuración, la página se actualiza para mostrar un identificador de objeto asignado al servicio de búsqueda.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Para obtener más información, consulte Crear un servicio de búsqueda con una identidad administrada asignada por el sistema (Azure PowerShell.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Para obtener más información, consulte Crear un servicio de búsqueda con una identidad administrada asignada por el sistema (CLI de Azure).

Usar servicios: crear o actualizar (API REST) para formular la solicitud.

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

La respuesta incluye una confirmación y un identificador de objeto para la identidad administrada asignada por el sistema.

Creación de una identidad administrada asignada por el usuario

Una identidad administrada asignada por el usuario es un recurso de Azure que se puede limitar a suscripciones, grupos de recursos o tipos de recursos.

Puede crear varias identidades administradas asignadas por el usuario para mayor granularidad en las asignaciones de roles. Por ejemplo, es posible que desee identidades independientes para diferentes aplicaciones y escenarios. Como recurso administrado y creado de forma independiente, no está enlazado al propio servicio.

Los pasos para configurar una identidad administrada asignada por el usuario son los siguientes:

En la suscripción de Azure, cree una identidad administrada asignada por el usuario.
En el servicio de búsqueda, asocie la identidad administrada asignada por el usuario con el servicio de búsqueda.
En otros servicios Azure a los que quiere conectarse, cree una asignación de roles para la identidad.

La asociación de una identidad administrada asignada por el usuario con un servicio Búsqueda de Azure AI se admite en el portal de Azure, las API rest de administración de búsqueda y los paquetes del SDK que proporcionan la característica.

portal de Azure
API DE REST

Inicie sesión en el portal Azure.
En la esquina superior izquierda del panel, seleccione Crear un recurso.
Use el cuadro de búsqueda para buscar identidad administrada asignada por el usuario y, a continuación, 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 finalice la implementación.

Tarda varios minutos antes de poder usar la identidad.
En la página del servicio de búsqueda, seleccione Ajustes>Identidad.
En la pestaña Usuario asignado , seleccione Agregar.
Seleccione la suscripción y la identidad administrada asignada por el usuario que haya creado anteriormente.

En lugar del portal de Azure, puede usar las API REST de administración de búsqueda para asignar una identidad administrada asignada por el usuario.

Utilice Servicios - Actualización (API REST) para formular la solicitud.

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

Establezca identity.type en el tipo de identidad.
- Los valores válidos son SystemAssigned, UserAssignedo SystemAssigned, UserAssigned para ambos.
- Un valor de None borra las identidades asignadas previamente del servicio de búsqueda.
Actualice identity.userAssignedIdentities para incluir los detalles de la identidad administrada asignada por el usuario. Esta identidad ya debe existir para poder especificarla en la solicitud.

Asignación de un rol

Después de tener una identidad administrada, asigne roles que determinen los permisos del servicio de búsqueda en el recurso de Azure.

Los permisos de lectura son necesarios 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 escritura para las características de enriquecimiento de IA que utilizan Azure Storage para alojar datos de sesiones de depuración, realizar el almacenamiento en caché relacionado con el enriquecimiento y guardar contenido a largo plazo en un almacén de conocimientos.

Los pasos siguientes muestran el flujo de trabajo de asignación de roles. Este ejemplo es para Azure OpenAI. Para ver otros recursos de Azure, consulte Connect to Azure Storage, Connect to Azure Cosmos DB o Connect to Azure SQL.

Vaya al recurso Azure OpenAI en el portal Azure.
Seleccione Control de acceso en el menú de la izquierda.
Seleccione Agregar y, después, Agregar asignación de roles.
En Roles de funciones laborales, seleccione Usuario de OpenAI de Cognitive Services y, a continuación, seleccione Siguiente.
En Miembros, seleccione Identidad administrada y, a continuación, seleccione Miembros.
Filtre por suscripción y tipo de recurso (Servicios de búsqueda) y seleccione la identidad administrada del servicio de búsqueda.
Seleccione Revisar y asignar.

Ejemplos de cadenas de conexión

Recuerde que, según la descripción de los escenarios, puede utilizar identidades administradas en las cadenas de conexión a otros recursos de Azure. En esta sección se proporcionan ejemplos.

Las conexiones de identidad administrada asignadas por el sistema usan versiones de API REST disponibles con carácter general. Las conexiones de identidad administrada asignadas por el usuario usan la API REST versión 2026-04-01 o posterior, excepto para las conexiones de caché de enriquecimiento, que todavía requieren una versión preliminar de la API.

Sugerencia

Puede crear la mayoría de estos objetos en el portal de Azure, especificar una identidad administrada asignada por el usuario o un sistema y, a continuación, ver la definición JSON para obtener el cadena de conexión.

Fuente de datos Blob (identidad administrada por el sistema):

Un origen de datos de indexador incluye una credentials propiedad que determina cómo se realiza la conexión al origen de datos. En el ejemplo siguiente se muestra un cadena de conexión especificando el identificador de recurso único de una cuenta de almacenamiento.

Se indica una identidad administrada del sistema cuando un 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 a través de una identity propiedad .

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

Fuente de datos Blob (identidad administrada por el usuario):

Se admite una identidad administrada asignada por el usuario a través de la propiedad identity con la API REST versión 2026-04-01 o posterior.

"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 (identidad administrada por el sistema):

Una definición del almacén de conocimiento incluye una cadena de conexión para Azure Storage. El 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. Se definen en la definición de proyección incrustada, no en el cadena de conexión.

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

Almacén de conocimiento (identidad administrada por el usuario):

Se admite una identidad administrada asignada por el usuario a través de la identity propiedad en SearchIndexerKnowledgeStore con la API REST versión 2026-04-01 o posterior.

"knowledgeStore": {
  "storageConnectionString": "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}"
  }
}

Caché de enriquecimiento (versión preliminar):

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

"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 de Azure y toma una cadena de conexión cuando inicias la sesión. Puede pegar una cadena similar al 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.

uri es el punto de conexión de la función o la aplicación.
authResourceId indica al servicio de búsqueda que se conecte mediante una identidad administrada, pasando el identificador de aplicación de la función de destino o la aplicación 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": [ ...]
}

Ejemplos de conexión para modelos

En el caso de las conexiones realizadas mediante identidades administradas, en esta sección se muestran ejemplos de información de conexión usada por un servicio de búsqueda para conectarse a un modelo en otro recurso. Una conexión a través de una identidad gestionada por el sistema es transparente; la identidad y las funciones están establecidas, y la conexión se realiza correctamente si están configuradas adecuadamente. Por el contrario, una identidad administrada por el usuario requiere propiedades de conexión adicionales.

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

Una habilidad de incrustación de Azure OpenAI y una vectorización en AI Search están dirigidas al punto de conexión de un Azure OpenAI que aloja un modelo de incrustación. El punto de conexión se especifica en la definición de la habilidad de inserción de Azure OpenAI y/o en la definición del vectorizador de Azure OpenAI.

La identidad administrada por el sistema se usa automáticamente si "apikey" y "authIdentity" están vacías, como se muestra en el ejemplo siguiente. La "authIdentity" propiedad solo se usa para la identidad administrada asignada por el usuario.

Ejemplo de identidad administrada por el sistema:

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

Este es un ejemplo de vectorizador configurado para una identidad administrada asignada por el sistema. Se especifica un vectorizador en un índice de búsqueda.

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

Ejemplo de identidad administrada asignada por el usuario:

Se usa una identidad administrada asignada por el usuario si "apiKey" está vacía y se proporciona un valor válido "authIdentity" .

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

Este es un ejemplo de vectorizador configurado para una identidad administrada asignada por el usuario. Se especifica un vectorizador en un índice de búsqueda.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Comprobación del acceso al firewall

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

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

Consulte también

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-12