Conectar-se ao Azure Cosmos DB usando uma identidade gerenciada (Azure AI Search)

Artigo
01/14/2025

Este artigo explica como configurar uma conexão de indexador com um banco de dados do Azure Cosmos DB usando uma identidade gerenciada em vez de fornecer credenciais na cadeia de conexão.'

Você pode usar uma identidade gerenciada atribuída ao sistema ou uma identidade gerenciada atribuída pelo usuário. As identidades gerenciadas são logons do Microsoft Entra e exigem atribuições de função do Azure para acessar dados no Azure Cosmos DB. Opcionalmente, você pode impor o acesso baseado em função como o único método de autenticação para conexões de dados definindo disableLocalAuth como true para sua conta do Azure Cosmos DB para NoSQL.

Pré-requisitos

Crie uma identidade gerenciada para seu serviço de pesquisa.

Abordagens suportadas para autenticação de identidade gerenciada

O Azure AI Search dá suporte a dois mecanismos para se conectar ao Azure Cosmos DB usando a identidade gerenciada.

A abordagem herdada requer a configuração da identidade gerenciada para ter permissões de leitor no plano de controle da conta de destino do Azure Cosmos DB. O Azure AI Search utiliza essa identidade para buscar as chaves de conta da conta do Cosmos DB em segundo plano para acessar os dados. Essa abordagem não funcionará se a conta do Cosmos DB tiver "disableLocalAuth": true.
A abordagem moderna requer a configuração das funções apropriadas de identidade gerenciada no plano de controle e de dados da conta de destino do Azure Cosmos DB. O Azure AI Search solicitará um token de acesso para acessar os dados na conta do Cosmos DB. Essa abordagem funciona mesmo se a conta do Cosmos DB tiver "disableLocalAuth": true.

Os indexadores que se conectam ao Azure Cosmos DB para NoSQL oferecem suporte à abordagem herdada e à abordagem moderna - a abordagem moderna é altamente recomendada.

Limitações

Os indexadores que se conectam ao Azure Cosmos DB para Gremlin e MongoDB (atualmente em visualização) dão suporte apenas à abordagem herdada .

Conectar-se ao Azure Cosmos DB para NoSQL

Esta seção descreve as etapas para configurar a conexão com o Azure Cosmos DB para NoSQL por meio da abordagem moderna .

Configurar atribuições de função do plano de controle

Entre no portal do Azure e encontre sua conta do Cosmos DB para NoSQL.
Selecione Controlo de acesso (IAM) .
Selecione Adicionar e, em seguida, selecione Atribuição de função.
Na lista de funções de função, selecione Leitor de Conta do Cosmos DB.
Selecione Seguinte.
Selecione Identidade gerenciada e, em seguida, selecione Membros.
Filtre por identidades gerenciadas atribuídas pelo sistema ou identidades gerenciadas atribuídas pelo usuário. Deverá ver a identidade gerida que criou anteriormente para o seu serviço de pesquisa. Se você não tiver uma, consulte Configurar a pesquisa para usar uma identidade gerenciada. Se você já configurou um, mas ele não está disponível, dê-lhe alguns minutos.
Selecione a identidade e salve a atribuição de função.

Para obter mais informações, consulte Usar controle de acesso baseado em função do plano de controle com o Azure Cosmos DB para NoSQL.

Configurar atribuições de função de plano de dados

A identidade gerenciada precisa atribuir uma função para ler o plano de dados da conta do Cosmos DB. O ID do objeto (principal) para a identidade atribuída ao sistema/usuário do serviço de pesquisa pode ser encontrado na guia "Identidade" do serviço de pesquisa. Esta etapa só pode ser executada por meio da CLI do Azure no momento.

Definir variáveis:

$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 uma atribuição de função para a identidade atribuída ao sistema:

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

Para obter mais informações, consulte Usar controle de acesso baseado em função do plano de dados com o Azure Cosmos DB para NoSQL

Configurar a definição da fonte de dados

Depois de configurar as atribuições de função do plano de controle e do plano de dados na conta do Azure Cosmos DB para NoSQL, você pode configurar uma conexão com ela que opere sob essa função.

Os indexadores usam um objeto de fonte de dados para conexões com uma fonte de dados externa. Esta seção explica como especificar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário em uma cadeia de conexão de fonte de dados. Você pode encontrar mais exemplos de cadeia de conexão no artigo de identidade gerenciada.

Gorjeta

Você pode criar uma conexão de fonte de dados com o Cosmos DB no portal do Azure, especificando uma identidade gerenciada atribuída pelo sistema ou pelo usuário e, em seguida, exibir a definição JSON para ver como a cadeia de conexão é formulada.

A API REST, o portal do Azure e o SDK do .NET suportam o uso de uma identidade gerenciada atribuída pelo sistema ou pelo usuário.

Conecte-se por meio de identidade atribuída ao sistema

Quando você está se conectando com uma identidade gerenciada atribuída ao sistema, a única alteração na definição da fonte de dados é o formato da propriedade "credenciais". Forneça um nome de banco de dados e um ResourceId que não tenha chave de conta ou senha. O ResourceId deve incluir a ID de assinatura do Azure Cosmos DB, o grupo de recursos e o nome da conta do Azure Cosmos DB.

Aqui está um exemplo usando a API REST Create Data Source que exerce a abordagem moderna .

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

Se a IdentityAuthType propriedade não fizer parte da cadeia de conexão, o Azure AI Search assumirá como padrão a abordagem herdada para garantir a compatibilidade com versões anteriores.

Conectar-se através da identidade atribuída pelo usuário

Você precisa adicionar uma propriedade "identity" à definição da fonte de dados, onde especifica a identidade específica (entre várias que podem ser atribuídas ao serviço de pesquisa), que será usada para se conectar à conta do Azure Cosmos DB.

Aqui está um exemplo usando a identidade atribuída pelo usuário por meio da abordagem moderna .

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

Conectar-se ao Azure Cosmos DB para Gremlin/MongoDB (visualização)

Esta seção descreve as etapas para configurar a conexão com o Azure Cosmos DB para Gremlin/Mongo por meio da abordagem herdada .

Configurar atribuições de função do plano de controle

Siga as mesmas etapas anteriores para atribuir as funções apropriadas no plano de controle do Azure Cosmos DB para Gremlin/MongoDB.

Definir a cadeia de ligação

Para coleções MongoDB, adicione "ApiKind=MongoDb" à cadeia de conexão e use uma API REST de visualização.
Para gráficos Gremlin, adicione "ApiKind=Gremlin" à cadeia de conexão e use uma API REST de visualização.
Para ambos os tipos, apenas a abordagem herdada é suportada - ou seja, IdentityAuthType=AccountKey omiti-la totalmente é a única cadeia de conexão válida.

Aqui está um exemplo para se conectar a coleções do MongoDB usando a identidade atribuída pelo sistema por meio da API 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
}

Aqui está um exemplo para se conectar a gráficos Gremlin usando a identidade atribuída pelo usuário.

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

Execute o indexador para verificar as permissões

As informações de conexão e as permissões no serviço remoto são validadas em tempo de execução durante a execução do indexador. Se o indexador for bem-sucedido, a sintaxe da conexão e as atribuições de função serão válidas. Para obter mais informações, consulte Executar ou redefinir indexadores, habilidades ou documentos.

Resolver problemas relacionados com ligações

Para o Azure Cosmos DB para NoSQL, verifique se a conta tem seu acesso restrito a redes selecionadas. Você pode descartar quaisquer problemas de firewall tentando a conexão sem restrições em vigor. Consulte Acesso do indexador ao conteúdo protegido pela segurança de rede do Azure para obter mais informações
Para o Azure Cosmos DB para NoSQL, se o indexador falhar devido a problemas de autenticação, verifique se as atribuições de função foram feitas no plano de controle e no plano de dados da conta do Cosmos DB.
Para Gremlin ou MongoDB, se você girou recentemente suas chaves de conta do Azure Cosmos DB, precisará aguardar até 15 minutos para que a cadeia de conexão de identidade gerenciada funcione.

Partilhar via

Conectar-se ao Azure Cosmos DB usando uma identidade gerenciada (Azure AI Search)

Pré-requisitos

Abordagens suportadas para autenticação de identidade gerenciada

Limitações

Conectar-se ao Azure Cosmos DB para NoSQL

Configurar atribuições de função do plano de controle

Configurar atribuições de função de plano de dados

Configurar a definição da fonte de dados

Conecte-se por meio de identidade atribuída ao sistema

Conectar-se através da identidade atribuída pelo usuário

Conectar-se ao Azure Cosmos DB para Gremlin/MongoDB (visualização)

Configurar atribuições de função do plano de controle

Definir a cadeia de ligação

Execute o indexador para verificar as permissões

Resolver problemas relacionados com ligações

Consulte também

Comentários

Recursos adicionais