Usar identidades gerenciadas atribuídas pelo sistema para acessar dados do Azure Cosmos DB

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.

• Uma conta existente da API do Azure Cosmos DB para NoSQL. Criar uma API do Azure Cosmos DB para conta NoSQL

• Um aplicativo de função existente do Azure Functions. Create your first function in the Azure portal (Criar a sua primeira função no portal do Azure)

  • Uma identidade gerenciada atribuída ao sistema para o aplicativo de função. Adicionar uma identidade atribuída ao sistema

• Azure Functions Core Tools

• Para executar as etapas neste artigo, instale a CLI do Azure e entre no Azure.

  Verificação de pré-requisitos

  1. Em uma janela de terminal ou comando, armazene os nomes do seu aplicativo de função do Azure Functions, da conta do Azure Cosmos DB e do grupo de recursos como variáveis de shell denominadas functionName, cosmosNamee resourceGroupName.

     # Variable for function app name
     functionName="msdocs-function-app"
     
     # Variable for Azure Cosmos DB account name
     cosmosName="msdocs-cosmos-app"
     
     # Variable for resource group name
     resourceGroupName="msdocs-cosmos-functions-dotnet-identity"
     

     Nota

     Essas variáveis são reutilizadas em etapas posteriores. Este exemplo pressupõe que o nome da conta do Azure Cosmos DB é msdocs-cosmos-app, o nome do aplicativo de função é msdocs-function-app e o nome do grupo de recursos é msdocs-cosmos-functions-dotnet-identity.

  2. Exiba as propriedades do aplicativo de função usando o az functionapp show comando.

     az functionapp show \
         --resource-group $resourceGroupName \
         --name $functionName
     

  3. Exiba as propriedades da identidade gerenciada atribuída ao sistema para seu aplicativo de função usando az webapp identity showo .

     az webapp identity show \
         --resource-group $resourceGroupName \
         --name $functionName
     

  4. Exiba as propriedades da conta do Azure Cosmos DB usando az cosmosdb showo .

     az cosmosdb show \
         --resource-group $resourceGroupName \
         --name $cosmosName
     

Nesta etapa, você cria dois bancos de dados.

1. Em um terminal ou janela de comando, crie um novo products banco de dados usando az cosmosdb sql database createo .

   az cosmosdb sql database create \
       --resource-group $resourceGroupName \
       --name products \
       --account-name $cosmosName
   

2. Crie um novo customers banco de dados.

   az cosmosdb sql database create \
       --resource-group $resourceGroupName \
       --name customers \
       --account-name $cosmosName
   

Nesta etapa, você consulta o ponto de extremidade do documento para a API para conta NoSQL.

1. Use az cosmosdb show com o parâmetro de consulta definido como documentEndpoint. Registe o resultado. Você usará esse valor em uma etapa posterior.

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $cosmosName \
       --query documentEndpoint
   
   cosmosEndpoint=$(
       az cosmosdb show \
           --resource-group $resourceGroupName \
           --name $cosmosName \
           --query documentEndpoint \
           --output tsv
   )
   
   echo $cosmosEndpoint
   

   Nota

   Essa variável é reutilizada em uma etapa posterior.

Nesta etapa, você atribui uma função à identidade gerenciada atribuída ao sistema do aplicativo de função. O Azure Cosmos DB tem várias funções internas que você pode atribuir à identidade gerenciada para acesso ao plano de controle. Para acesso ao plano de dados, você cria uma nova função personalizada com acesso para ler metadados.

1. Use az cosmosdb show com o parâmetro de consulta definido como id. Armazene o resultado em uma variável de shell chamada scope.

   scope=$(
       az cosmosdb show \
           --resource-group $resourceGroupName \
           --name $cosmosName \
           --query id \
           --output tsv
   )
   
   echo $scope
   

   Nota

   Essa variável é reutilizada em uma etapa posterior.

2. Use az webapp identity show com o parâmetro de consulta definido como principalId. Armazene o resultado em uma variável de shell chamada principal.

   principal=$(
       az webapp identity show \
           --resource-group $resourceGroupName \
           --name $functionName \
           --query principalId \
           --output tsv
   )
   
   echo $principal
   

3. Crie um novo arquivo JSON com a configuração da nova função personalizada.

   {
       "RoleName": "Read Azure Cosmos DB Metadata",
       "Type": "CustomRole",
       "AssignableScopes": ["/"],
       "Permissions": [{
           "DataActions": [
               "Microsoft.DocumentDB/databaseAccounts/readMetadata"
           ]
       }]
   }
   

   Gorjeta

   Você pode criar um arquivo no Azure Cloud Shell usando um ou touch <filename> o editor interno (code .). Para obter mais informações, consulte Editor do Azure Cloud Shell

4. Use az cosmosdb sql role definition create para criar uma nova definição de função nomeada Read Azure Cosmos DB Metadata usando o objeto JSON personalizado.

   az cosmosdb sql role definition create \
       --resource-group $resourceGroupName \
       --account-name $cosmosName \
       --body @definition.json
   

   Nota

   Neste exemplo, a definição de função é definida em um arquivo chamado definition.json.

5. Use az role assignment create para atribuir a Read Azure Cosmos DB Metadata função à identidade gerenciada atribuída ao sistema.

   az cosmosdb sql role assignment create \
       --resource-group $resourceGroupName \
       --account-name $cosmosName \
       --role-definition-name "Read Azure Cosmos DB Metadata" \
       --principal-id $principal \
       --scope $scope
   

Agora temos um aplicativo de função que tem uma identidade gerenciada atribuída ao sistema com a função personalizada. O aplicativo de função a seguir consultará a conta do Azure Cosmos DB para obter uma lista de bancos de dados.

1. Crie um projeto de função local com o --dotnet parâmetro em uma pasta chamada csmsfunc. Alterar o diretório do shell

   func init csmsfunc --dotnet
   
   cd csmsfunc
   

2. Crie uma nova função com o parâmetro de modelo definido como httptrigger e o nome definido como readdatabases.

   func new --template httptrigger --name readdatabases
   

3. Adicione o pacote e Microsoft.Azure.Cosmos NuGet Azure.Identity ao projeto .NET. Crie o projeto usando dotnet buildo .

   dotnet add package Azure.Identity
   
   dotnet add package Microsoft.Azure.Cosmos
   
   dotnet build
   

4. Abra o código da função em um ambiente de desenvolvedor integrado (IDE).

   Gorjeta

   Se você estiver usando a CLI do Azure localmente ou no Azure Cloud Shell, poderá abrir o Visual Studio Code.

   code .
   

5. Substitua o código no arquivo readdatabases.cs por esta implementação de função de exemplo. Guarde o ficheiro atualizado.

   using System;
   using System.Collections.Generic;
   using System.Threading.Tasks;
   using Azure.Identity;
   using Microsoft.AspNetCore.Mvc;
   using Microsoft.Azure.Cosmos;
   using Microsoft.Azure.WebJobs;
   using Microsoft.Azure.WebJobs.Extensions.Http;
   using Microsoft.AspNetCore.Http;
   using Microsoft.Extensions.Logging;
   
   namespace csmsfunc
   {
       public static class readdatabases
       {
           [FunctionName("readdatabases")]
           public static async Task<IActionResult> Run(
               [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req,
               ILogger log)
           {
               log.LogTrace("Start function");
   
               CosmosClient client = new CosmosClient(
                   accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT", EnvironmentVariableTarget.Process),
                   new DefaultAzureCredential()
               );
   
               using FeedIterator<DatabaseProperties> iterator = client.GetDatabaseQueryIterator<DatabaseProperties>();
   
               List<(string name, string uri)> databases = new();
               while(iterator.HasMoreResults)
               {
                   foreach(DatabaseProperties database in await iterator.ReadNextAsync())
                   {
                       log.LogTrace($"[Database Found]\t{database.Id}");
                       databases.Add((database.Id, database.SelfLink));
                   }
               }
   
               return new OkObjectResult(databases);
           }
       }
   }
   

Em um ambiente local, a DefaultAzureCredential classe usa várias credenciais locais para determinar a identidade atual. Embora a execução local não seja necessária para o procedimento, você pode desenvolver localmente usando sua própria identidade ou uma entidade de serviço.

1. Obtenha o identificador principal da sua conta local usando az ad signed-in-user showo .

   az ad signed-in-user show --query "id"
   

2. Atribua o acesso de controle de acesso baseado em função da sua conta local à conta do Azure Cosmos DB usando az cosmosdb sql role assignment create o comando. Use a função interna "Colaborador de dados do Cosmos DB" com uma id de 00000000-0000-0000-0000-000000000002.

   az cosmosdb sql role assignment create \
       --resource-group $resourceGroupName \
       --account-name $cosmosName \
       --role-definition-id "00000000-0000-0000-0000-000000000002" \
       --principal-id "<your-principal-id>" \
       --scope "/"
   

3. No arquivo local.settings.json, adicione uma nova configuração nomeada COSMOS_ENDPOINT no objeto Values. O valor da configuração deve ser o ponto de extremidade do documento que você registrou anteriormente neste guia de instruções.

   ...
   "Values": {
       ...
       "COSMOS_ENDPOINT": "https://msdocs-cosmos-app.documents.azure.com:443/",
       ...
   }
   ...
   

   Nota

   Este objeto JSON foi encurtado para brevidade. Este objeto JSON também inclui um valor de exemplo que assume que o nome da sua conta é msdocs-cosmos-app.

4. Execute o aplicativo de função

   func start
   

Uma vez publicada, a DefaultAzureCredential classe usa credenciais do ambiente ou uma identidade gerenciada. Para este guia, a identidade gerenciada atribuída ao sistema será usada como uma credencial para o CosmosClient construtor.

1. Defina a COSMOS_ENDPOINT configuração no aplicativo de função já implantado no Azure.

   az functionapp config appsettings set \
       --resource-group $resourceGroupName \
       --name $functionName \
       --settings "COSMOS_ENDPOINT=$cosmosEndpoint"
   

2. Implante seu aplicativo de função no Azure reutilizando a functionName variável shell:

   func azure functionapp publish $functionName
   

3. Teste sua função no portal do Azure.