Autenticar recursos do Azure a partir de aplicativos .NET hospedados no local

2025-03-29

Os aplicativos hospedados fora do Azure, como no local ou em um data center de terceiros, devem usar uma entidade de serviço de aplicativo por meio de de ID do Microsoft Entra para autenticar nos serviços do Azure. Nas seções a seguir, você aprende:

Como registar uma aplicação no Microsoft Entra para criar um principal de serviço
Como atribuir funções a permissões de escopo
Como autenticar usando uma entidade de serviço a partir do código do seu aplicativo

O uso de entidades de serviço de aplicativo dedicadas permite que você siga o princípio de menor privilégio 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 excessivamente privilegiado no ambiente de desenvolvimento.

Um registro de aplicativo diferente deve ser criado para cada ambiente em que o aplicativo está hospedado. Isso permite que permissões de recursos específicos do ambiente sejam configuradas para cada entidade de serviço e certifique-se de que um aplicativo implantado em um ambiente não converse com os recursos do Azure que fazem parte de outro ambiente.

Registrar o aplicativo no Azure

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

Portal do Azure
CLI do Azure

No portal do Azure, use a barra de pesquisa para navegar para a página Registros de Aplicativos.
Na página Registos de Aplicações, selecione + Novo registo.
Na página de registo de candidatura
- Para o campo Nome, insira um valor descritivo que inclua o nome do aplicativo e o ambiente de destino.
- Para os Tipos de conta suportados, selecione Contas apenas neste diretório organizacional (Microsoft Customer Led apenas - Locatário único)ou a opção que melhor atenda às suas necessidades.
Selecione Registrar para registar o seu aplicativo e criar o principal de serviço.
Na página de registo da aplicação para a sua aplicação, copie o ID da aplicação (cliente) e o ID do diretório (locatário) e cole-os num local temporário para uso posterior nas configurações de código da aplicação.
Selecione Adicionar um certificado ou secreto para configurar credenciais para seu aplicativo.
Na página Certificados & segredos, selecione + Novo segredo do cliente.
No painel suspenso Adicionar um segredo do cliente que se abre:
- Para a Descrição, insira um valor de Atual.
- Para o valor de Expira, deixe o valor recomendado padrão de 180 dias.
- Selecione Adicionar para acrescentar o segredo.
Na página Certificados & segredos, copie a propriedade Valor do segredo do cliente para uso numa etapa futura.

Observação

O valor secreto do cliente só é exibido uma vez após a criação do registro do aplicativo. Você pode adicionar mais segredos de cliente sem invalidar esse segredo de cliente, mas não há como exibir esse valor novamente.

Os comandos da CLI do Azure podem ser executados no do Azure Cloud Shell ou em uma estação de trabalho com a CLI do Azure instalada.

Use o comando az ad sp create-for-rbac para criar um novo registo de aplicação e entidade de serviço para a aplicação.

az ad sp create-for-rbac --name <service-principal-name>

A saída deste comando é semelhante ao seguinte JSON:

{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "<service-principal-name>",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "11111111-1111-1111-1111-111111111111"
}

Copie essa saída para um arquivo temporário em um editor de texto, pois você precisará desses valores em uma etapa futura.

Observação

O valor secreto do cliente só é exibido uma vez após a criação do registro do aplicativo. Você pode adicionar mais segredos de cliente sem invalidar esse segredo de cliente, mas não há como exibir esse valor novamente.

Atribuir funções à entidade de serviço do aplicativo

Em seguida, determine quais funções (permissões) seu aplicativo precisa em quais recursos e atribua essas funções à entidade de serviço que você criou. As funções podem ser atribuídas no recurso, grupo de recursos ou escopo de assinatura. Este exemplo mostra como atribuir funções no escopo do grupo de recursos, já que a maioria dos aplicativos agrupa todos os seus recursos do Azure em um único grupo de recursos.

Portal do Azure
CLI do Azure

No portal do Azure, navegue até a página Visão Geral do grupo de recursos que contém a sua aplicação.
Selecione controle de acesso (IAM) na navegação à esquerda.
Na página Controle de Acesso (IAM), selecione + Adicionar e depois 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.
Na guia Função , use a caixa de pesquisa para localizar a função que deseja atribuir. Selecione a função e, em seguida, escolha Avançar.
No separador Membros:
- Para a Atribuir acesso a valor, selecione Usuário, grupo ou entidade de serviço .
- Para o valor de Membros, escolha + Selecionar membros para abrir o painel deslizante Selecionar membros.
- Pesquise o principal de serviço que criou anteriormente e selecione-o nos resultados filtrados. Escolha Selecionar para selecionar o grupo e fechar o painel suspenso.
- Selecione Rever + atribuir na parte inferior do separador Membros.
No separador Rever + atribuir, selecione Rever + atribuir na parte de baixo da página.

Use o comando az role definition list para obter os nomes das funções às quais um principal de serviço pode ser atribuído:

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

Use o comando az role assignment create para atribuir uma função a um principal de serviço da aplicação:
```
az role assignment create \
    --assignee "<app-Id>" \
    --role "<role-name>" \
    --resource-group "<resource-group-name>"
```
Para obter informações sobre como atribuir permissões no nível de recurso ou assinatura usando a CLI do Azure, consulte Atribuir funções do Azure usando a CLI.

Definir as variáveis de ambiente do aplicativo

Durante a execução, certas credenciais da biblioteca de Identidade do Azure, como DefaultAzureCredential, EnvironmentCredentiale ClientSecretCredential, pesquisam, por convenção, informações da entidade de serviço nas variáveis de ambiente. Há várias maneiras de configurar variáveis de ambiente ao trabalhar com .NET, dependendo de suas ferramentas e ambiente.

Independentemente da abordagem escolhida, configure 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: O ID do tenant do Microsoft Entra.
AZURE_CLIENT_SECRET: A credencial secreta que foi gerada para o aplicativo.

Visual Studio
de código do Visual Studio
Windows

No Visual Studio, as variáveis de ambiente podem ser definidas no arquivo launchsettings.json na pasta Properties do seu projeto. Esses valores são carregados automaticamente quando a aplicação é iniciada. No entanto, essas configurações não viajam com seu aplicativo durante a implantação, portanto, você precisa configurar variáveis de ambiente em seu ambiente de hospedagem de destino.

"profiles": {
    "SampleProject": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7177;http://localhost:5177",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "<your-client-id>",
        "AZURE_TENANT_ID":"<your-tenant-id>",
        "AZURE_CLIENT_SECRET": "<your-client-secret>"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "<your-client-id>",
        "AZURE_TENANT_ID":"<your-tenant-id>",
        "AZURE_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }

No Visual Studio Code, as variáveis de ambiente podem ser definidas no arquivo de launch.json do seu projeto. Estes valores são carregados automaticamente quando a aplicação é iniciada. No entanto, essas configurações não viajam com seu aplicativo durante a implantação, portanto, você precisa configurar variáveis de ambiente em seu ambiente de hospedagem de destino.

"configurations": [
{
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "<your-client-id>",
        "AZURE_TENANT_ID":"<your-tenant-id>",
        "AZURE_CLIENT_SECRET": "<your-client-secret>"
    }
}

Você pode definir variáveis de ambiente para o Windows a partir da linha de comando. No entanto, os valores são acessíveis a todos os aplicativos em execução nesse sistema operacional e podem causar conflitos, portanto, tenha cuidado com essa abordagem. As variáveis de ambiente podem ser definidas no nível do usuário ou do sistema.

# Set user environment variables
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "<your-client-id>"
setx AZURE_TENANT_ID "<your-tenant-id>"
setx AZURE_CLIENT_SECRET "<your-client-secret>"

# Set system environment variables - requires running as admin
setx ASPNETCORE_ENVIRONMENT "Development" /m
setx AZURE_CLIENT_ID "<your-client-id>" /m
setx AZURE_TENANT_ID "<your-tenant-id>" /m
setx AZURE_CLIENT_SECRET "<your-client-secret>" /m

O PowerShell também pode ser usado para definir variáveis de ambiente no nível do usuário ou do sistema:

# Set user environment variables
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "Machine")

Autenticar nos serviços do Azure a partir da sua aplicação

O da biblioteca de Identidade do Azure fornece várias credenciais — implementações de TokenCredential adaptadas para suportar diferentes cenários e fluxos de autenticação do Microsoft Entra. As etapas a seguir demonstram como usar ClientSecretCredential ao trabalhar com entidades de serviço localmente e em produção.

Implementar o código

Adicione o pacote Azure.Identity. Em um projeto ASP.NET Core, instale também o pacote de Microsoft.Extensions.Azure:

Linha de Comandos
Gestor de Pacotes do NuGet

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

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Azure

Os serviços do Azure são acessados usando classes de cliente especializadas das várias bibliotecas de cliente do SDK do Azure. Essas classes e seus próprios serviços personalizados devem ser registrados para injeção de dependência para que possam ser usados em todo o aplicativo. No Program.cs, conclua as seguintes etapas para configurar uma classe de cliente para injeção de dependência e autenticação baseada em token:

Inclua os namespaces Azure.Identity e Microsoft.Extensions.Azure por meio de diretivas using.
Registe o cliente de serviço do Azure utilizando o método de extensão correspondente com o prefixo Add.
Configure o ClientSecretCredential com tenantId, clientIde clientSecret.
Passe a instância ClientSecretCredential para o método UseCredential.

builder.Services.AddAzureClients(clientBuilder =>
{
    var tenantId = Environment.GetEnvironmentVariable("AZURE_TENANT_ID");
    var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID");
    var clientSecret = Environment.GetEnvironmentVariable("AZURE_CLIENT_SECRET");

    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));

    clientBuilder.UseCredential(new ClientSecretCredential(tenantId, clientId, clientSecret));
});

Uma alternativa ao método UseCredential é fornecer a credencial diretamente ao cliente de serviço:

var tenantId = Environment.GetEnvironmentVariable("AZURE_TENANT_ID");
var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID");
var clientSecret = Environment.GetEnvironmentVariable("AZURE_CLIENT_SECRET");

builder.Services.AddSingleton<BlobServiceClient>(_ =>
    new BlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"),
        new ClientSecretCredential(tenantId, clientId, clientSecret)));

Comentários

Esta página foi útil?