Conectar-se ao Azure Cosmos DB usando uma identidade gerenciada (Pesquisa de IA do Azure)

Artigo
01/16/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 colocar as credenciais na cadeia de conexão.

Você pode usar a identidade gerenciada atribuída pelo sistema ou a 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. Para o Cosmos DB for NoSQL, é possível optar por 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 for NoSQL.

Pré-requisitos

Criar uma identidade gerenciada para o serviço Pesquisa.

Abordagens com suporte para autenticação de identidade gerenciada

A Pesquisa de IA do Azure 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 do Azure Cosmos DB de destino. A Pesquisa de IA do Azure 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 dados e controle da conta do Azure Cosmos DB de destino. A Pesquisa de IA do Azure solicitará um token de acesso para acessar os dados na conta do Cosmos DB. Essa abordagem funcionará mesmo se a conta do Cosmos DB tiver "disableLocalAuth": true.

Os indexadores que se conectam ao Azure Cosmos DB for NoSQL dão suporte tanto à abordagem herdada quanto à moderna – a abordagem moderna é altamente recomendada.

Limitações

Os indexadores que se conectam ao Azure Cosmos DB para Gremlin e MongoDB (atualmente em versão prévia) só dão suporte à abordagem herdada.

Conectar-se ao Azure Cosmos DB for NoSQL

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

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

Entre no portal do Microsoft Azure e encontre sua conta do Cosmos DB for NoSQL.
Selecione IAM (Controle de acesso) .
Selecione Adicionar e, em seguida, Atribuição de função.
Na lista de funções de trabalho, selecione Leitor de Conta do Cosmos DB.
Selecione Avançar.
Selecione Identidade gerenciada e, em seguida, Membros.
Filtrar por identidades gerenciadas atribuídas pelo sistema ou identidades gerenciadas atribuídas pelo usuário. Você deve ver a identidade gerenciada que você criou anteriormente para seu serviço de pesquisa. Se você não tiver uma, consulte Configurar a busca para usar uma identidade gerenciada. Se você já configurou uma, mas ela não está disponível, aguarde alguns minutos.
Selecione a identidade e salve a atribuição de função.

Para mais informações, confira Usar o controle de acesso baseado em função do painel de controle com o Azure Cosmos DB for NoSQL.

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

A identidade gerenciada precisa atribuir uma função para ler do plano de dados da conta do Cosmos DB. A ID do objeto (entidade de segurança) da identidade atribuída pelo sistema/usuário do serviço de pesquisa pode ser encontrada na guia "Identidade" do serviço de pesquisa. Essa 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 pelo sistema:

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

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

Configurar a definição da fonte de dados

Depois de configurar ambas as atribuições de função do painel de controle e do plano de dados na conta do Azure Cosmos DB for NoSQL, você pode configurar uma conexão com ela que opera 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 cadeias de conexão no artigo sobre identidade gerenciada.

Dica

Você pode criar uma conexão de fonte de dados com o Cosmos DB no portal do Microsoft 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 dão suporte ao uso de uma identidade gerenciada atribuída pelo usuário ou pelo sistema.

Conectar-se por meio da identidade atribuída pelo sistema

Quando você está se conectando com uma identidade gerenciada atribuída pelo sistema, a única alteração na definição da fonte de dados é o formato da propriedade "credentials". Forneça um nome de banco de dados e uma ResourceId que não tenha nenhuma chave de conta ou senha. A ResourceId precisa incluir a ID da 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 Criar fonte de dados que utiliza 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]" }
}

Observação

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

Conectar-se por meio da identidade atribuída pelo usuário

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

Veja 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 (versão prévia)

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

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

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

Definir a cadeia de conexão

Para coleções do MongoDB, adicione “ApiKind=MongoDb” à cadeia de conexão e usa uma API REST de visualização.
Para grafos do Gremlin, adicione "ApiKind = Gremlin" à cadeia de conexão e use uma API REST de visualização.
Para qualquer um dos tipos, há suporte apenas para a abordagem herdada, ou seja, IdentityAuthType=AccountKey ou omiti-la inteiramente é a única cadeia de conexão válida.

Veja um exemplo para se conectar às 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
}

Veja um exemplo para se conectar aos grafos do 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]" 
    }
}

Executar o indexador para verificar permissões

As informações da conexão e as permissões no serviço remoto são validadas no tempo de execução durante a execução do indexador. Se o indexador for bem-sucedido, a sintaxe de 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.

Solucionar problemas de conexões

Para o Azure Cosmos DB for NoSQL, verifique se a conta tem seu acesso restrito a redes selecionadas. Você pode eliminar qualquer problema de firewall experimentando a conexão sem restrições em vigor. Para obter mais informações, confira Acesso do indexador ao conteúdo protegido pela segurança da rede do Azure
Para o Azure Cosmos DB for NoSQL, se o indexador falhar devido a problemas de autenticação, verifique se as atribuições de função foram feitas em ambos o painel de controle e o plano de dados da conta do Cosmos DB.
Para Gremlin ou MongoDB, se você rotacionou recentemente as chaves da sua conta do Azure Cosmos DB, será necessário aguardar até 15 minutos para que a cadeia de conexão de identidade gerenciada funcione.

Compartilhar via

Conectar-se ao Azure Cosmos DB usando uma identidade gerenciada (Pesquisa de IA do Azure)

Pré-requisitos

Abordagens com suporte para autenticação de identidade gerenciada

Limitações

Conectar-se ao Azure Cosmos DB for NoSQL

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

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

Configurar a definição da fonte de dados

Conectar-se por meio da identidade atribuída pelo sistema

Conectar-se por meio da identidade atribuída pelo usuário

Conectar-se ao Azure Cosmos DB para Gremlin/MongoDB (versão prévia)

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

Definir a cadeia de conexão

Executar o indexador para verificar permissões

Solucionar problemas de conexões

Confira também

Comentários

Recursos adicionais