Usar un indexador de blobs o un origen de conocimiento para incorporar metadatos de ámbitos de RBAC (versión preliminar)

Azure Storage permite el acceso basado en roles a los contenedores de almacenamiento en blob, donde roles como Storage Blob Data Reader o Storage Blob Data Contributor determinan si alguien tiene acceso al contenido. Búsqueda de Azure AI admite la ingesta de permisos de usuario (versión preliminar) junto con la ingesta de documentos para poder usar esos permisos para controlar el acceso a los resultados de búsqueda. Si un usuario carece de permisos en un directorio o archivo específico en Azure Storage, ese usuario no tiene acceso a los documentos correspondientes en los resultados de Búsqueda de Azure AI, incluso si tiene personalmente una asignación de Search Index Data Readeren el índice.

• A partir de 2025-05-01-preview y en versiones posteriores, es posible ingerir los metadatos de los ámbitos de RBAC mediante el indexador de blobs.
• 2025-11-01-preview y versiones posteriores proporcionan compatibilidad equivalente para fuentes de conocimiento de blobs en Azure Storage.

El ámbito de RBAC se establece en el nivel de contenedor y fluye a todos los blobs (documentos) mediante la herencia de permisos. El ámbito de RBAC se captura durante la indexación como metadatos de permiso. Puede usar las API de inserción para cargar y indexar el contenido y los metadatos de permisos manualmente (consulte Indexación de permisos mediante la API REST de inserción) o puede usar un indexador o un origen de conocimiento para automatizar la ingesta de datos. Este artículo se centra en la automatización de la indexación.

En el momento de la consulta, la identidad del autor de la llamada se incluye en el encabezado de solicitud a través del x-ms-query-source-authorization parámetro . La identidad debe coincidir con los metadatos de permiso en los documentos si el usuario va a ver los resultados de la búsqueda.

Este artículo se centra en los enfoques de automatización de la indexación, basados en esta base:

• Blobs de Azure Storage protegidos mediante el control de acceso basado en roles (RBAC de Azure). No hay compatibilidad con el control de acceso basado en atributos (Azure ABAC).

• Indexador de Blobs de Azure o una fuente de conocimiento de Blob que recupera e ingiere datos y metadatos, incluidos los filtros de permisos. Para obtener compatibilidad con filtros de permisos, use la API REST de versión preliminar más reciente o un paquete de versión preliminar de un SDK de Azure que admita la característica.

• Índice en Búsqueda de Azure AI que contiene los documentos ingeridos y los permisos correspondientes. Los metadatos de permiso se almacenan como campos en el índice.

• Consulta que usa filtros de permisos. Para configurar consultas que respeten los filtros de permisos, use la API REST de versión preliminar más reciente o un paquete de versión preliminar de un SDK de Azure que admita la característica.

Requisitos previos

• Microsoft Entra ID autenticación y autorización. Los servicios y las aplicaciones deben estar en el mismo entorno. Los usuarios pueden estar en inquilinos diferentes siempre que todos los inquilinos sean de Microsoft Entra ID. Las asignaciones de roles se usan para cada conexión autenticada.

• Búsqueda de Azure AI, cualquier región, pero debe tener un nivel facturable (básico o superior) para admitir identidades administradas. El servicio de búsqueda debe configurarse para el acceso basado en roles y debe tener una identidad administrada (sistema o usuario).

• Azure Storage, rendimiento estándar (uso general v2), en niveles de acceso caliente, templado y frío, con contenedores o blobs protegidos por RBAC.

• Debe comprender cómo funcionan los indexadores y los orígenes de conocimiento y cómo crear un índice. En este artículo se explican las opciones de configuración para el origen de datos y el indexador, pero no se proporcionan pasos para crear el índice. Para obtener más información sobre los índices diseñados para los filtros de permisos, consulte Creación de un índice con campos de filtro de permisos.

Limitaciones

• El portal de Azure no admite esta característica.

• Las siguientes características del indexador no admiten la herencia de permisos en documentos indexados procedentes de ADLS Gen2. Si usa cualquiera de estas características en un conjunto de aptitudes o indexador, los permisos de nivel de documento no se incluyen en el contenido indizado.

  • Aptitud de API web personalizada

  • Almacén de conocimiento

  • Caché de enriquecimiento del indexador

  • Sesiones de depuración

Configuración de Blob Storage

Compruebe que el contenedor de blobs usa el acceso basado en roles.

1. Inicie sesión en el portal de Azure y busque la cuenta de almacenamiento.

2. Expanda contenedores y seleccione el contenedor que tiene los blobs que desea indexar.

3. Seleccione Access Control (IAM) para comprobar las asignaciones de roles. Los usuarios y grupos con lector de datos de Storage Blob o colaborador de datos de Storage Blob tienen acceso a los documentos de búsqueda en el índice después de indexar el contenedor.

Autorización

Para la ejecución del indexador, la identidad del servicio de búsqueda debe tener el permiso Lector de datos de Blob de almacenamiento . Para obtener más información, consulte Connect to Azure Storage using a managed identity.

Configuración de Búsqueda de Azure AI

Recuerde que el servicio de búsqueda debe tener:

• Acceso habilitado por roles
• Identidad administrada configurada

Autorización

Para la ejecución del indexador, el cliente que emite la llamada API debe tener Search Service Contributor permiso para crear objetos, Search Index Data Contributor permiso para realizar la importación de datos y Search Index Data Reader para consultar un índice, consulte Connect to Búsqueda de Azure AI using roles.

Configuración de un origen de conocimiento

Si usa un origen de conocimiento, las definiciones del origen de conocimiento se usan para generar una canalización de indexación completa (indexador, origen de datos e índice). El ámbito de RBAC se detecta y se incluye automáticamente en el índice generado. No es necesario modificar ninguno de los objetos generados si desea la herencia de permisos en el contenido indizado.

Puntos clave sobre la configuración que hacen que funcione en este escenario:

• isADLSGen2 se establece en false, lo que significa que el origen de datos es Azure Blob Storage.
• ingestionPermissionOptions especifica rbacScope.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": false,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
            "ingestionPermissionOptions": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Reference:Create or Update Knowledge Source (API REST)

Configuración de la indexación basada en indexadores

Si está utilizando un indexador, configure el indexador, el origen de datos y el índice para extraer los metadatos de permisos de los blobs.

Creación del origen de datos

• El tipo de origen de datos debe ser azureblob.

• El modo de análisis del origen de datos debe ser el valor predeterminado.

• El origen de datos debe tener indexerPermissionOptions con rbacScope.

  • Para rbacScope, configure la cadena de conexión con el formato de identidad administrada.

  • Para las cadenas de conexión que usan una identidad administrada asignada por el usuario, también debe especificar la identity propiedad .

Ejemplo de JSON con la identidad administrada del sistema y indexerPermissionOptions:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
        "name": "<your-container-name>",
        "query": "<optional-query-used-for-selecting-specific-blobs>"
    }
}

Ejemplo de esquema JSON con una identidad administrada por el usuario en el cadena de conexión:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
        "name": "<your-container-name>",
        "query": "<optional-query-used-for-selecting-specific-blobs>"
    },
    "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Creación de campos de permisos en el índice

En Búsqueda de Azure AI, asegúrese de que el índice contiene definiciones de campo para los metadatos de permiso. Los metadatos de permisos se pueden indexar cuando indexerPermissionOptions se especifican en la definición del origen de datos.

Atributos de esquema recomendados para el ámbito de RBAC:

• Campo de ámbito RBAC con el valor permissionFilter de rbacScope.
• Propiedad permissionFilterOption para habilitar el filtrado en tiempo de consulta.
• Uso de campos de cadena para metadatos de permisos
• Establezca filterable en verdadero en todos los campos.

Observe que retrievable es false. Puede establecerlo en true durante el desarrollo para comprobar que los permisos están presentes, pero recuerde volver a establecerlo en false antes de realizar la implementación en un entorno de producción para que las identidades de entidad de seguridad no sean visibles en los resultados.

Ejemplo de esquema JSON:

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

Configuración del indexador

Las asignaciones de campos dentro de un indexador establecen la ruta de acceso de datos a los campos de un índice. Los campos objetivo y de destino que varían por nombre o tipo de datos requieren una asignación explícita de campos. Los siguientes campos de metadatos de Azure Blob Storage pueden necesitar asignaciones de campos si cambia el nombre del campo:

• metadata_rbac_scope (Edm.String): el ámbito RBAC del contenedor.

Especifique fieldMappings en el indexador para enrutar los metadatos de permiso a los campos de destino durante la indexación.

Ejemplo de esquema JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Ejecución del indexador

Una vez configurado el indexador, el origen de datos y el índice, ejecute el indexador para establecer el proceso en movimiento. Si hay un problema con la configuración o los permisos, estos problemas se muestran en este paso.

De forma predeterminada, un indexador se ejecuta tan pronto como lo publique en un servicio de búsqueda, pero si la configuración del indexador incluye disabled establecida en true, el indexador se publica en un estado deshabilitado para que pueda ejecutar el indexador manualmente.

Se recomienda ejecutar el indexador desde el portal de Azure para que pueda supervisar el estado y los mensajes.

Suponiendo que no hay errores, el índice se rellena ahora y puede avanzar con consultas y pruebas.

Seguimiento de eliminación

Para administrar eficazmente la eliminación de blobs, asegúrese de que ha habilitado el seguimiento de eliminación antes de que el indexador se ejecute por primera vez. Esta función permite al sistema detectar blobs eliminados de su origen y eliminar el contenido correspondiente del índice.

Consulte también

• Conéctate a Búsqueda de Azure AI utilizando roles

• Aplicación de ACL y RBAC durante la consulta
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API

• Buscar en contenido de Azure Blob Storage
• Configuración de un indexador de blobs