Compartir a través de

Conexión a Azure Cosmos DB mediante una identidad administrada (Azure AI Search)

  • Artículo

En este artículo se explica cómo configurar una conexión de indexador a una base de datos de Azure Cosmos DB mediante una identidad administrada en lugar de proporcionar credenciales en la cadena de conexión.

Puede usar una identidad administrada asignada por el sistema o asignada por el usuario. Las identidades administradas son inicios de sesión de Microsoft Entra y requieren asignaciones de roles de Azure para acceder a los datos de Azure Cosmos DB. Opcionalmente, puede aplicar el acceso basado en roles como único método de autenticación para las conexiones de datos estableciendo disableLocalAuth en true para su cuenta de Azure Cosmos DB for NoSQL.

Requisitos previos

Enfoques admitidos para la autenticación de identidad administrada

Búsqueda de Azure AI es compatible con dos mecanismos para conectarse a Azure Cosmos DB usando la identidad administrada.

  • El enfoque heredado requiere configurar la identidad administrada para que tenga permisos de lectura en el plano de control de la cuenta de Azure Cosmos DB de destino. Búsqueda de Azure AI utiliza esa identidad para obtener las claves de la cuenta de Cosmos DB en segundo plano para acceder a los datos. Este método no funcionará si la cuenta de Cosmos DB tiene "disableLocalAuth": true.

  • El enfoque moderno requiere configurar los roles adecuados de la identidad administrada en el plano de control y de datos de la cuenta de Azure Cosmos DB de destino. Búsqueda de Azure AI solicitará después un token de acceso para acceder a los datos de la cuenta de Cosmos DB. Este enfoque funciona incluso si la cuenta de Cosmos DB tiene "disableLocalAuth": true.

Los indizadores que se conectan a Azure Cosmos DB for NoSQL son compatibles tanto con el enfoque heredado como con el moderno, se recomienda encarecidamente el enfoque moderno.

Limitaciones

  • Los indizadores que se conectan a Azure Cosmos DB for Gremlin y MongoDB (actualmente en versión preliminar) solo son compatibles con el enfoque heredado.

Conexión de Azure Cosmos DB for NoSQL

Esta sección describe los pasos para configurar la conexión a Azure Cosmos DB for NoSQL mediante el enfoque moderno.

Configuración de asignaciones de roles del plano de control

  1. Inicie sesión en Azure Portal y busque la cuenta de Cosmos DB para NoSQL.

  2. Seleccione Control de acceso (IAM).

  3. Seleccione Agregar y, a continuación, seleccione asignación de roles.

  4. En la lista de roles de función de trabajo, seleccione Lector de cuentas de Cosmos DB.

  5. Seleccione Siguiente.

  6. Seleccione Identidad administrada y, después, seleccione Miembros.

  7. Filtre por identidades administradas asignadas por el sistema o identidades administradas asignadas por el usuario. Debería ver la identidad administrada que creó anteriormente para el servicio de búsqueda. Si no tiene una, consulte Configuración de la búsqueda para usar una identidad administrada. Si ya ha configurado una pero no está disponible, espere unos minutos.

  8. Seleccione la identidad y guarde la asignación de roles.

Para más información, consulte Uso del control de acceso basado en roles del plano de control con Azure Cosmos DB for NoSQL.

Configuración de la asignación de roles en el plano de datos

La identidad administrada necesita que se le asigne un rol para leer del plano de datos de la cuenta de Cosmos DB. El id. del objeto (entidad de seguridad) para la identidad asignada por el sistema/usuario del servicio de búsqueda se puede encontrar en la pestaña "Identidad" del servicio de búsqueda. Este paso solo se puede realizar a través de la CLI de Azure en este momento.

Establecer variables:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Defina una asignación de roles para la identidad asignada por el sistema:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

Para más información, vea Uso del control de acceso basado en rol del plano de datos con Azure Cosmos DB for NoSQL

Configuración de la definición del origen de datos

Una vez que haya configurado tanto la asignación de roles del plano de control como del plano de datos en la cuenta Azure Cosmos DB for NoSQL, podrá establecer una conexión con ella que opere bajo ese rol.

Los indexadores usan un objeto de origen de datos para las conexiones a un origen de datos externo. En esta sección se explica cómo especificar una identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario en una cadena de conexión del origen de datos. Puede encontrar más ejemplos de cadenas de conexión en el artículo sobre la identidad administrada.

Sugerencia

Puede crear una conexión de origen de datos a CosmosDB en Azure Portal, especificar una identidad administrada asignada por el usuario o un sistema y, a continuación, ver la definición JSON para ver cómo se formula la cadena de conexión.

La API de REST, Azure Portal y el SDK de .NET son compatibles usando una identidad administrada asignada por el sistema o por el usuario.

Conexión a través de la identidad asignada por el sistema

Cuando se conecte con una identidad administrada asignada por el sistema, el único cambio en la definición del origen de datos será el formato de la propiedad "credentials". Proporcione un nombre de base de datos y un ResourceId que no tenga ninguna clave de cuenta ni contraseña. ResourceId debe incluir el identificador de suscripción de Azure Cosmos DB, el grupo de recursos y el nombre de cuenta de Azure Cosmos DB.

Este es un ejemplo usando la API de REST Crear origen de datos que usa el enfoque moderno.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Nota:

Si la propiedad IdentityAuthType no forma parte de la cadena de conexión, Búsqueda de Azure AI adoptará de manera predeterminada el enfoque heredado para garantizar la compatibilidad con versiones anteriores.

Conexión a través de la identidad administrada por el usuario

Es necesario agregar una propiedad de "identidad" a la definición del origen de datos, en la que se especifique la identidad concreta (de entre varias que pueden asignarse al servicio de búsqueda), que se utilizará para conectarse a la cuenta de Azure Cosmos DB.

Este es un ejemplo usando la identidad administrada por el usuario a través del enfoque moderno.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Conexión a Azure Cosmos DB for Gremlin/MongoDB (versión preliminar)

En esta sección se describen los pasos para configurar la conexión a Azure Cosmos DB para Gremlin/Mongo mediante el enfoque heredado.

Configuración de asignaciones de roles del plano de control

Siga los mismos pasos que antes para asignar los roles adecuados en el plano de control de Azure Cosmos DB for Gremlin/MongoDB.

Establecimiento de la cadena de conexión

  • Para las colecciones de MongoDB, agregue "ApiKind=MongoDb" a la cadena de conexión y use una API de REST en versión preliminar.
  • Para los gráficos de Gremlin, agregue "ApiKind=Gremlin" a la cadena de conexión y use una API de REST en versión preliminar.
  • Para ambos tipos, solo es compatible el enfoque heredado, es decir, IdentityAuthType=AccountKey u omitirlo por completo es la única cadena de conexión válida.

Este es un ejemplo para conectarse a las colecciones de MongoDB usando la identidad asignada por el sistema a través de la API de REST

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Este es un ejemplo para conectarse a grafos de Gremlin mediante la identidad asignada por el usuario.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Ejecución del indexador para comprobar los permisos

La información de conexión y los permisos en el servicio remoto se validan en tiempo de ejecución durante la ejecución del indexador. Si el indexador se realizó correctamente, la sintaxis de conexión y las asignaciones de roles son válidas. Para más información, consulte Ejecución o restablecimiento de indexadores, aptitudes o documentos.

Solución de problemas de conexiones

  • Para Azure Cosmos DB para NoSQL, compruebe si la cuenta tiene su acceso restringido para seleccionar redes. Para descartar cualquier problema relacionado con el firewall, pruebe la conexión sin restricciones. Consulte Acceso del indizador al contenido protegido por la seguridad de red de Azure para más información

  • En el caso de Azure Cosmos DB for NoSQL, si el indizador falla debido a problemas de autenticación, asegúrese de que las asignaciones de roles se han realizado tanto en el plano de control como en el plano de datos de la cuenta de Cosmos DB.

  • Para Gremlin o MongoDB, si ha girado recientemente las claves de cuenta de Azure Cosmos DB, debe esperar hasta 15 minutos para que funcione la cadena de conexión de identidad administrada.

Consulte también