Compartilhar via

Autenticar aplicativos C++ nos serviços do Azure durante o desenvolvimento local usando entidades de serviço

Durante o desenvolvimento local, os aplicativos precisam se autenticar no Azure para acessar vários serviços do Azure. Duas abordagens comuns para a autenticação local são usar uma conta de desenvolvedor ou uma entidade de serviço. Este artigo explica como usar uma entidade de serviço de aplicativo. Nas seções a seguir, você aprenderá:

  • Como registrar um aplicativo no Microsoft Entra a fim de criar uma entidade de serviço
  • Como usar grupos do Microsoft Entra para gerenciar permissões com eficiência
  • Como atribuir as funções às permissões de escopo
  • Como autenticar-se usando uma entidade de serviço direto do código do seu aplicativo

O uso de entidades de serviço de aplicativo dedicadas permite que você adere ao princípio do privilégio mínimo ao acessar recursos do Azure. As permissões são limitadas aos requisitos específicos do aplicativo durante o desenvolvimento, impedindo o acesso acidental aos recursos do Azure destinados a outros aplicativos ou serviços. Essa abordagem também ajuda a evitar problemas quando o aplicativo é movido para produção, garantindo que ele não seja super privilegiado no ambiente de desenvolvimento.

Um diagrama mostrando como um aplicativo C++ local usa uma entidade de serviço para se conectar aos recursos do Azure.

Quando o aplicativo é registrado no Azure, é criada uma entidade de serviço de aplicativo. Para desenvolvimento local:

  • Crie um registro de aplicativo separado para cada desenvolvedor que trabalha no aplicativo para garantir que cada desenvolvedor tenha sua própria entidade de serviço de aplicativo, evitando a necessidade de compartilhar credenciais.
  • Crie um registro de aplicativo separado para cada aplicativo para limitar as permissões do aplicativo apenas ao que é necessário.

Durante o desenvolvimento local, as variáveis de ambiente são definidas com a identidade da entidade de serviço de aplicativo. A biblioteca de Identidades do Azure lê essas variáveis de ambiente para autenticar o aplicativo nos recursos necessários do Azure.

Registrar o aplicativo no Azure

Os objetos "principal de serviço" do aplicativo são criados por meio de um registro de aplicativo no Azure, usando o portal do Azure ou a CLI do Azure.

  1. No portal do Azure, use a barra de pesquisa para navegar até a página Registros de aplicativo.

  2. Na página Registros de aplicativo, selecione + Novo registro.

  3. Na página Registrar um aplicativo:

    • Para o campo Nome, insira um valor descritivo que inclui o nome do aplicativo e o ambiente de destino.
    • Para os Tipos de conta com suporte, selecione Contas somente neste diretório organizacional (somente cliente da Microsoft – Locatário único) ou qualquer opção que melhor atenda às suas necessidades.

  4. Selecione Registrar para registrar seu aplicativo e criar a entidade de serviço.

    Uma captura de tela mostrando como criar um registro de aplicativo no portal do Azure.

  5. Na página Registro do aplicativo , copie a ID do aplicativo (cliente) e a ID do diretório (locatário) e cole-as em um local temporário para uso posterior nas configurações do código do aplicativo.

  6. Selecione Adicionar um certificado ou um secreto para configurar credenciais para seu aplicativo.

  7. Na página Certificados e segredos, selecione + Novo segredo do cliente.

  8. No painel de submenu Adicionar um segredo do cliente que se abre:

    • Para a Descrição, insira um valor para Atual.
    • Para o valor de expiração , deixe o valor padrão recomendado de 180 dias.
    • Selecione Adicionar para adicionar o segredo.

  9. Na página Certificados e segredos, copie a propriedade Value do segredo do cliente para uso em uma etapa futura.

    Observação

    O valor do segredo do cliente só é exibido uma vez depois que o registro do aplicativo é criado. Você pode adicionar mais segredos do cliente sem invalidar esse segredo do cliente, mas não há como exibir esse valor novamente.

Criar um grupo do Microsoft Entra para desenvolvimento local

Crie um grupo do Microsoft Entra para encapsular as funções (permissões) que o aplicativo precisa durante o desenvolvimento local, em vez de atribuir as funções a objetos principais de serviço individuais. Essa abordagem oferece as seguintes vantagens:

  • Cada desenvolvedor tem as mesmas funções atribuídas no nível do grupo.
  • Se uma nova função for necessária para o aplicativo, ela só precisará ser adicionada ao grupo do aplicativo.
  • Se um novo desenvolvedor ingressar na equipe, um novo principal de serviço de aplicativo será criado para o desenvolvedor e adicionado ao grupo, garantindo que o desenvolvedor tenha as permissões corretas para trabalhar no aplicativo.

  1. Navegue até a página de visão geral do Microsoft Entra ID no portal do Azure.

  2. Selecione Todos os grupos no menu à esquerda.

  3. Na página Grupos , selecione Novo grupo.

  4. Na página Novo grupo , preencha os seguintes campos de formulário:

    • Tipo de grupo: selecione Segurança.
    • Nome do grupo: insira um nome para o grupo que inclui uma referência ao nome do aplicativo ou do ambiente.
    • Descrição do grupo: insira uma descrição que explique a finalidade do grupo.

    Uma captura de tela mostrando como criar um grupo no portal do Azure.

  5. Selecione o link Nenhum membro selecionado em Membros para adicionar membros ao grupo.

  6. No painel de submenu que é aberto, procure a entidade de serviço que você criou anteriormente e selecione-a nos resultados filtrados. Escolha o botão Selecionar na parte inferior do painel para confirmar sua seleção.

  7. Selecione Criar na parte inferior da página Novo grupo para criar o grupo e retornar à página Todos os grupos . Se você não vir o novo grupo listado, aguarde um momento e atualize a página.

Atribuir funções ao grupo

Em seguida, determine quais funções (permissões) seu aplicativo precisa em quais recursos e atribua essas funções ao grupo Microsoft Entra que você criou. Os grupos podem ser atribuídos a uma função no nível do recurso, do grupo de recursos ou da assinatura. Este exemplo mostra como atribuir funções no escopo do grupo de recursos, já que a maioria dos aplicativos agrupa todos os recursos do Azure em um único grupo de recursos.

  1. No portal do Azure, navegue até a página Visão geral do grupo de recursos que contém seu aplicativo.

  2. Selecione Controle de acesso (IAM) na navegação à esquerda.

  3. Na página controle de acesso (IAM), selecione + Adicionar e escolha Adicionar atribuição de função no menu suspenso. A página Adicionar atribuição de função fornece várias guias para configurar e atribuir funções.

  4. Na guia Função , use a caixa de pesquisa para localizar a função que você deseja atribuir. Selecione a função e escolha Avançar.

  5. Na guia Membros :

    • Para atribuir acesso ao valor, selecione Usuário, grupo ou entidade de serviço .
    • Para o valor Membros, escolha + Selecionar membros para abrir o painel de seleção Selecionar membros.
    • Pesquise o grupo do Microsoft Entra criado anteriormente e selecione-o nos resultados filtrados. Escolha Selecionar para escolher o grupo e fechar o painel de menu.
    • Selecione Examinar + atribuir na parte inferior da guia Membros .

    Uma captura de tela mostrando como atribuir uma função ao grupo Microsoft Entra.

  6. Na guia Revisão + atribuição , selecione Examinar + atribuir na parte inferior da página.

Definir as variáveis de ambiente do aplicativo

Em tempo de execução, determinadas credenciais da biblioteca de Identidade do Azure, como DefaultAzureCredential, EnvironmentCredential, e ClientSecretCredential, pesquisam informações da entidade de serviço por convenção nas variáveis de ambiente. Há várias maneiras de configurar variáveis de ambiente dependendo de suas ferramentas e ambiente. Você pode criar um .env arquivo ou usar variáveis de ambiente do sistema para armazenar essas credenciais localmente durante o desenvolvimento.

Independentemente da abordagem escolhida, defina as seguintes variáveis de ambiente para um principal de serviço:

  • AZURE_CLIENT_ID: usado para identificar o aplicativo registrado no Azure.
  • AZURE_TENANT_ID: a ID do locatário do Microsoft Entra.
  • AZURE_CLIENT_SECRET: a credencial secreta que foi gerada para o aplicativo.

Para aplicativos C++, você pode definir essas variáveis de ambiente de várias maneiras. Você pode carregá-los de um .env arquivo em seu código ou defini-los no ambiente do sistema. Os exemplos a seguir mostram como definir as variáveis de ambiente em shells diferentes:

export AZURE_CLIENT_ID=<your-client-id>
export AZURE_TENANT_ID=<your-tenant-id>
export AZURE_CLIENT_SECRET=<your-client-secret>

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. Use a ClientSecretCredential classe ao trabalhar com entidades de serviço localmente e em produção. Nesse cenário, ClientSecretCredential, AZURE_CLIENT_ID, AZURE_TENANT_ID lêem as variáveis de ambiente e AZURE_CLIENT_SECRET obtém as informações do principal de serviço do aplicativo para se conectar ao Azure.

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

    vcpkg add port azure-identity-cpp

  2. Adicione as seguintes linhas ao arquivo CMake:

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

  3. Para qualquer código C++ que crie um objeto cliente do SDK do Azure em seu aplicativo:

    1. Inclua o azure/identity.hpp cabeçalho.
    2. Criar uma instância de ClientSecretCredential.
    3. Passe a instância de ClientSecretCredential para o construtor do cliente do SDK do Azure.

    Um exemplo é mostrado no seguinte segmento de código:

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

// The following environment variables must be set before running the sample.
// * AZURE_TENANT_ID: Tenant ID for the Azure account.
// * AZURE_CLIENT_ID: The Client ID to authenticate the request.
// * AZURE_CLIENT_SECRET: The client secret.
std::string GetTenantId() { return std::getenv("AZURE_TENANT_ID"); }
std::string GetClientId() { return std::getenv("AZURE_CLIENT_ID"); }
std::string GetClientSecret() { return std::getenv("AZURE_CLIENT_SECRET"); }

int main() {
    try {
        // Create a credential - this will automatically read the environment variables
        // AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET
        auto credential = std::make_shared<Azure::Identity::ClientSecretCredential>(GetTenantId(), GetClientId(), GetClientSecret());

        // 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 and created Azure clients." << std::endl;

    } catch (const std::exception& ex) {
        std::cout << "Exception: " << ex.what() << std::endl;
        return 1;
    }

    return 0;
}
  • Last updated on