Autenticar aplicativos C++ hospedados no Azure em recursos do Azure usando uma identidade gerenciada atribuída pelo usuário

A abordagem recomendada para autenticar um aplicativo hospedado no Azure em outros recursos do Azure é usar uma identidade gerenciada . Essa abordagem é compatível com a maioria dos serviços do Azure, incluindo aplicativos hospedados no Serviço de Aplicativo do Azure, aplicativos de contêiner do Azure e máquinas virtuais do Azure. Descubra mais sobre diferentes técnicas e abordagens de autenticação na página de visão geral da autenticação . Nas seções a seguir, você aprenderá:

• Conceitos essenciais de identidade gerenciada
• Como criar uma identidade gerenciada atribuída pelo usuário para seu aplicativo
• Como atribuir funções à identidade gerenciada atribuída pelo usuário
• Como autenticar usando a identidade gerenciada atribuída pelo usuário a partir do seu código de aplicativo

Conceitos essenciais de identidade gerenciada

Uma identidade gerenciada permite que seu aplicativo se conecte com segurança a outros recursos do Azure sem o uso de chaves secretas ou outros segredos do aplicativo. Internamente, o Azure rastreia a identidade e os recursos aos quais tem permissão para se conectar. O Azure usa essas informações para obter automaticamente tokens do Microsoft Entra para o aplicativo para permitir que ele se conecte a outros recursos do Azure.

Há dois tipos de identidades gerenciadas a serem consideradas ao configurar seu aplicativo hospedado:

• identidades gerenciadas atribuídas pelo sistema são habilitadas diretamente em um recurso do Azure e estão vinculadas ao ciclo de vida. Quando o recurso é excluído, o Azure exclui automaticamente a identidade para você. As identidades atribuídas pelo sistema fornecem uma abordagem minimalista para o uso de identidades gerenciadas.
• identidades gerenciadas atribuídas pelo usuário são criadas como recursos autônomos do Azure e oferecem maior flexibilidade e funcionalidades. Elas são ideais para soluções que envolvem vários recursos do Azure que precisam compartilhar a mesma identidade e permissões. Por exemplo, se várias máquinas virtuais precisarem acessar o mesmo conjunto de recursos do Azure, uma identidade gerenciada atribuída pelo usuário fornecerá reutilização e gerenciamento otimizado.

Dica

Saiba mais sobre como selecionar e gerenciar identidades gerenciadas atribuídas pelo sistema e atribuídas pelo usuário no artigo de recomendações de melhores práticas de identidade gerenciada .

As seções a seguir descrevem as etapas para habilitar e usar uma identidade gerenciada atribuída pelo usuário para um aplicativo hospedado no Azure. Se você precisar usar uma identidade gerenciada atribuída pelo sistema, visite o artigo de identidades gerenciadas atribuídas pelo sistema para obter mais informações.

Criar uma identidade gerenciada atribuída ao usuário

As identidades gerenciadas atribuídas pelo usuário são criadas como recursos autônomos em sua assinatura do Azure usando o portal do Azure ou a CLI do Azure. É possível executar os comandos da CLI do Azure no Azure Cloud Shell ou em uma estação de trabalho com a CLI do Azure instalada.

Portal do Azure

1. No portal do Azure, insira identidades gerenciadas na barra de pesquisa principal e selecione o resultado correspondente na seção Serviços .

2. Na página Identidades gerenciadas, selecione + Criar.

   

3. Na página Criar Identidade Gerenciada Atribuída ao Usuário , selecione uma assinatura, um grupo de recursos e uma região para a identidade gerenciada atribuída pelo usuário e forneça um nome.

4. Selecione Examinar + criar para examinar e validar suas entradas.

   

5. Selecione Criar para criar a identidade gerenciada atribuída pelo usuário.

6. Depois que a identidade for criada, selecione Ir para o recurso.

7. Na página Visão geral da nova identidade, copie o valor da ID do cliente a ser usado posteriormente quando você configurar o código do aplicativo.

Azure CLI

Use o comando az identity create da CLI do Azure para criar uma identidade gerenciada:

az identity create \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId' \
    --output json

A saída do comando exibe a ID do cliente da identidade gerenciada criada atribuída pelo usuário. A ID do cliente é usada para configurar o código do aplicativo que depende da identidade.

Você sempre pode exibir as propriedades de identidade gerenciada novamente usando o az identity show comando:

az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json

Atribuir a identidade gerenciada ao seu aplicativo

Uma identidade gerenciada atribuída pelo usuário pode ser associada a um ou mais recursos do Azure. Todos os recursos que usam essa identidade obtêm as permissões aplicadas por meio das funções da identidade.

Portal do Azure

1. No portal do Azure, navegue até o recurso que hospeda o código do aplicativo, como um Serviço de Aplicativo do Azure ou uma instância do Aplicativo de Contêiner do Azure.

2. Na página Visão geral do recurso, expanda Configurações e selecione Identidade na navegação.

3. Na página Identidade, alterne para a aba Atribuída ao usuário.

4. Selecione + Adicionar para abrir o painel Adicionar identidade gerenciada atribuída pelo usuário .

5. No painel Adicionar identidade gerenciada atribuída pelo usuário, use a lista suspensa de assinatura para filtrar os resultados da pesquisa de suas identidades. Use a caixa de pesquisa identidades gerenciadas atribuídas pelo usuário para localizar a identidade gerenciada atribuída pelo usuário que você habilitou para o recurso do Azure que hospeda seu aplicativo.

6. Selecione a identidade e escolha Adicionar na parte inferior do painel para continuar.

   

Azure CLI

A CLI do Azure fornece comandos diferentes para atribuir uma identidade gerenciada atribuída pelo usuário a diferentes tipos de serviços de hospedagem.

1. Para atribuir uma identidade gerenciada pelo usuário a um recurso como um aplicativo Web do Serviço de Aplicativo do Azure usando a CLI do Azure, você precisará da ID do recurso da identidade. Use o az identity show comando para recuperar a ID do recurso:

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query id
   

2. Depois de ter a ID do recurso, use o comando de comando az <resourceType> identity assign da CLI do Azure para associar a identidade gerenciada atribuída pelo usuário a recursos diferentes, como o seguinte:

   Para o Serviço de Aplicativo do Azure, use o comando az webapp identity assignda CLI do Azure:

   az webapp identity assign \
       --resource-group <resource-group-name> \
       --name <webapp-name> \
       --identities <user-assigned-identity-resource-id>
   

   Para aplicativos de contêiner do Azure, use o comando az containerapp identity assignda CLI do Azure:

   az containerapp identity assign \
       --resource-group <resource-group-name> \
       --name <containerapp-name> \
       --identities <user-assigned-identity-resource-id>
   

   Para máquinas virtuais do Azure, use o comando az vm identity assignda CLI do Azure:

   az vm identity assign \
       --resource-group <resource-group-name> \
       --name <vm-name> \
       --identities <user-assigned-identity-resource-id>
   

Atribuir funções à identidade gerenciada

Em seguida, determine quais funções seu aplicativo precisa e atribua essas funções à identidade gerenciada. Você pode atribuir funções a uma identidade gerenciada nos seguintes escopos:

• Resource: as funções atribuídas se aplicam somente a esse recurso específico.
• grupo de recursos: as funções atribuídas se aplicam a todos os recursos contidos no grupo de recursos.
• Assinatura: As funções designadas se aplicam a todos os recursos contidos na assinatura.

O exemplo a seguir mostra como atribuir funções no escopo do grupo de recursos, já que muitos aplicativos gerenciam todos os recursos relacionados do Azure usando um único grupo de recursos.

Portal do Azure

1. Navegue até a página Visão geral do grupo de recursos que contém o aplicativo com a identidade gerenciada atribuída pelo usuário.

2. Selecione Controle de Acesso (IAM) no menu de navegação à esquerda.

3. Na página Controle de Acesso (IAM), selecione + Adicionar no menu superior e escolha Adicionar atribuição de função para navegar até a página Adicionar atribuição de função.

   

4. A página Adicionar atribuição de função apresenta um fluxo de trabalho multi-etapas com abas para atribuir funções a identidades. Na guia inicial de Função, use o campo de busca na parte superior para localizar a função que você deseja atribuir à identidade.

5. Selecione a função nos resultados e escolha Próximo para acessar a guia Membros.

6. Para a opção Atribuir acesso a, selecione Identidade gerenciada.

7. Para a opção Membros, selecione + Selecionar membros para abrir o painel Selecionar identidades gerenciadas.

8. No painel Selecionar identidades gerenciadas, use as listas suspensas de Assinatura e Identidade gerenciada para filtrar os resultados da pesquisa para suas identidades. Use a caixa de seleção para localizar a identidade gerenciada atribuída pelo usuário que você habilitou para o recurso do Azure que hospeda o seu aplicativo.

   

9. Selecione a identidade e escolha Selecione na parte inferior do painel para continuar.

10. Selecione Revisar + atribuir na parte inferior da página.

11. Na guia Revisar + atribuir final, selecione Revisar + atribuir para concluir o fluxo de trabalho.

Azure CLI

1. Para atribuir uma função a uma identidade gerenciada atribuída pelo usuário usando a CLI do Azure, você precisará da ID principal da identidade. Use o comando az identity show para recuperar a ID principal.

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query principalId
   

2. Use o comando az role definition list para explorar quais funções uma identidade gerenciada pode ser atribuída:

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

3. Atribua uma função a uma identidade gerenciada usando o comando az role assignment create :

   az role assignment create \
       --assignee <your-principal-id> \
       --role <role-name> \
       --scope <scope>
   

   Por exemplo, para permitir a identidade gerenciada com a ID de acesso de 99999999-9999-9999-9999-999999999999 leitura, gravação e exclusão a contêineres de blob do Armazenamento do Azure e dados a todas as contas de armazenamento no grupo de recursos msdocs-sdk-auth-example, atribua a entidade de serviço de aplicativo à função Colaborador de Dados de Blob de Armazenamento usando o seguinte comando:

   az role assignment create \
       --assignee 99999999-9999-9999-9999-999999999999 \
       --role "Storage Blob Data Contributor" \
       --scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-sdk-auth-example"
   

Para obter informações sobre como atribuir permissões no nível de recurso ou assinatura usando a CLI do Azure, consulte o artigo Atribuir funções do Azure usando a CLI do Azure.

Autenticar nos serviços do Azure em seu aplicativo

A biblioteca de identidades do Azure fornece várias credenciais — implementações de TokenCredential adaptadas para dar suporte a diferentes cenários e fluxos de autenticação do Microsoft Entra. Como a identidade gerenciada não está disponível ao ser executada localmente, as etapas à frente demonstram qual credencial usar em qual cenário:

• Ambiente de desenvolvimento local: somente durante o desenvolvimento local, use uma classe chamada DefaultAzureCredential para uma cadeia de credenciais opinativa e pré-configurada. DefaultAzureCredential descobre as credenciais do usuário de suas ferramentas locais ou IDE, como a CLI do Azure ou o Visual Studio. Ele também oferece flexibilidade e conveniência para novas tentativas, tempos de espera para respostas e suporte para várias opções de autenticação. Visite o artigo Autenticar nos serviços do Azure durante o desenvolvimento local para saber mais.
• Aplicativos hospedados no Azure: quando seu aplicativo estiver em execução no Azure, use ManagedIdentityCredential para descobrir com segurança a identidade gerenciada configurada para seu aplicativo. Especificar esse tipo exato de credencial impede que outras credenciais disponíveis sejam coletadas inesperadamente.

Implementar o código

1. Adicione o pacote azure-identity-cpp ao seu aplicativo usando vcpkg.

   Em um terminal de sua escolha, navegue até o diretório do projeto de aplicativo e execute o seguinte comando:

   vcpkg add port azure-identity-cpp
   

2. Adicione o seguinte no arquivo CMake:

   find_package(azure-identity-cpp CONFIG REQUIRED)
   target_link_libraries(<your project name> PRIVATE Azure::azure-identity)
   

3. Os serviços do Azure são acessados usando clientes especializados das várias bibliotecas de clientes do SDK do Azure. Para qualquer código C++ que instancie um cliente do SDK do Azure em seu aplicativo, você precisa:

   1. Inclua o azure/identity.hpp cabeçalho.
   2. Criar uma instância de DefaultAzureCredential.
   3. Passe a instância de DefaultAzureCredential para o construtor do cliente do SDK do Azure.
   4. Defina a variável de ambiente AZURE_CLIENT_ID para o ID do cliente da sua identidade gerenciada atribuída pelo usuário.
   5. Defina a variável de ambiente AZURE_TOKEN_CREDENTIALS para ManagedIdentityCredential para garantir que DefaultAzureCredential use a credencial de identidade gerenciada. Essa prática torna a autenticação mais previsível e mais fácil de depurar quando implantada no Azure. Para obter mais informações, consulte Usar uma credencial específica.

   Um exemplo dessas etapas é mostrado no segmento de código a seguir com um cliente de Blob de Armazenamento do Azure.

   #include <azure/identity.hpp>
   #include <azure/storage/blobs.hpp>
   #include <iostream>
   #include <memory>
   #include <cstdlib>
   
   int main() {
       try {
           // Set the AZURE_CLIENT_ID environment variable to your user-assigned managed identity client ID
           // This can be done in your deployment environment or in code (shown below for demonstration)
           // std::putenv("AZURE_CLIENT_ID=your-user-assigned-identity-client-id");
   
           // Create a credential - DefaultAzureCredential will use the AZURE_CLIENT_ID environment variable
           // Create a credential - DefaultAzureCredential will use the AZURE_CLIENT_ID and AZURE_TOKEN_CREDENTIALS environment variables
           auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);
   
           // Create a client for the specified storage account
           std::string accountUrl = "https://<replace_with_your_storage_account_name>.blob.core.windows.net/";
           Azure::Storage::Blobs::BlobServiceClient blobServiceClient(accountUrl, credential);
   
           // Get a reference to a container
           std::string containerName = "sample-container";
           auto containerClient = blobServiceClient.GetBlobContainerClient(containerName);
   
           // Get a reference to a blob
           std::string blobName = "sample-blob";
           auto blobClient = containerClient.GetBlobClient(blobName);
   
           // TODO: perform some action with the blob client
           // auto downloadResult = blobClient.DownloadTo("path/to/local/file");
   
           std::cout << "Successfully authenticated using user-assigned managed identity." << std::endl;
   
       } catch (const std::exception& ex) {
           std::cout << "Exception: " << ex.what() << std::endl;
           return 1;
       }
   
       return 0;
   }
   

Conforme discutido no artigo de visão geral da autenticação do SDK do Azure para C++ , DefaultAzureCredential dá suporte a vários métodos de autenticação e determina o método de autenticação que está sendo usado em runtime. O benefício dessa abordagem é que seu aplicativo pode usar diferentes métodos de autenticação em ambientes diferentes sem implementar código específico do ambiente. Quando o código anterior é executado em sua estação de trabalho durante o desenvolvimento local, DefaultAzureCredential usa um principal de serviço de aplicativo, conforme determinado por configurações de ambiente, ou credenciais de ferramenta de desenvolvedor para se autenticar junto a outros recursos do Azure. Portanto, o mesmo código pode ser usado para autenticar seu aplicativo nos recursos do Azure durante o desenvolvimento local e quando implantado no Azure.

Importante

DefaultAzureCredential simplifica a autenticação ao desenvolver aplicativos que são implantados no Azure combinando credenciais usadas em ambientes de hospedagem do Azure e credenciais usadas no desenvolvimento local. Em produção, é melhor usar um tipo de credencial específico para que a autenticação seja mais previsível e mais fácil de depurar.

Uma alternativa para DefaultAzureCredential é usar ManagedIdentityCredential. As etapas para usar ManagedIdentityCredential são as mesmas para usar o DefaultAzureCredential tipo.

Um exemplo dessas etapas é mostrado no segmento de código a seguir com um cliente de Blob de Armazenamento do Azure.

#include <azure/identity.hpp>
#include <azure/storage/blobs.hpp>
#include <iostream>
#include <memory>

int main() {
    try {
        // Create a user-assigned managed identity credential with the client ID
        Azure::Identity::ManagedIdentityCredentialOptions options;
        options.ClientId = "abcd1234-..."; // Replace with your user-assigned managed identity client ID
        auto credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>(options);
        
        // Create a client for the specified storage account
        std::string accountUrl = "https://<replace_with_your_storage_account_name>.blob.core.windows.net/";
        Azure::Storage::Blobs::BlobServiceClient blobServiceClient(accountUrl, credential);
        
        // Get a reference to a container
        std::string containerName = "sample-container";
        auto containerClient = blobServiceClient.GetBlobContainerClient(containerName);
        
        // Get a reference to a blob
        std::string blobName = "sample-blob";
        auto blobClient = containerClient.GetBlobClient(blobName);
        
        // TODO: perform some action with the blob client
        // auto downloadResult = blobClient.DownloadTo("path/to/local/file");
        
        std::cout << "Successfully authenticated using user-assigned managed identity." << std::endl;
        
    } catch (const std::exception& ex) {
        std::cout << "Exception: " << ex.what() << std::endl;
        return 1;
    }
    
    return 0;
}