Autenticar aplicativos .NET nos serviços do Azure durante o desenvolvimento local usando entidades de serviço

Artigo
08/05/2024

Os desenvolvedores precisam depurar e testar aplicativos na nuvem em suas estações de trabalho locais. Quando um aplicativo é executado na estação de trabalho de um desenvolvedor durante o desenvolvimento local, ele ainda deve se autenticar em quaisquer serviços do Azure usados pelo aplicativo. Este artigo aborda como configurar objetos principais de serviço de aplicativo dedicados a serem usados durante o desenvolvimento local.

Um diagrama mostrando como um aplicativo .NET local usa as credenciais do desenvolvedor para se conectar ao Azure usando ferramentas de desenvolvimento instaladas localmente.

Entidades de serviço de aplicativo dedicadas para desenvolvimento local permitem que você siga o princípio de menor privilégio durante o desenvolvimento de aplicativos. Como as permissões têm como escopo exatamente o que é necessário para o aplicativo durante o desenvolvimento, o código do aplicativo é impedido de acessar acidentalmente um recurso do Azure destinado ao uso por um aplicativo diferente. Isso também evita que bugs ocorram quando o aplicativo é movido para produção porque o aplicativo era superprivilegiado no ambiente de desenvolvimento.

Uma entidade de serviço de aplicativo é configurada para o aplicativo quando o aplicativo é registrado no Azure. Ao registrar um aplicativo para desenvolvimento local, recomenda-se:

Crie um registro de aplicativo separado para cada desenvolvedor que trabalha no aplicativo. Isso criará entidades de serviço de aplicativo separadas para cada desenvolvedor usar durante o desenvolvimento local e evitará a necessidade de os desenvolvedores compartilharem credenciais para uma única entidade de serviço de aplicativo.
Crie um registro de aplicativo separado por aplicativo. Isso define o escopo das permissões do aplicativo apenas para o que é necessário para o aplicativo.

Durante o desenvolvimento local, as variáveis de ambiente são definidas com a identidade da entidade de serviço do aplicativo. A biblioteca de Identidade do Azure lê essas variáveis de ambiente e usa essas informações para autenticar o aplicativo nos recursos do Azure de que ele precisa.

1 - Registar a aplicação no Azure

Os objetos principais do serviço de aplicativo são criados com um registro de aplicativo no Azure. Isso pode ser feito usando o portal do Azure ou a CLI do Azure.

Portal do Azure
CLI do Azure

Entre no portal do Azure e siga estas etapas.

Instruções	Captura de ecrã
No portal do Azure: Insira registros de aplicativos na barra de pesquisa na parte superior do portal do Azure. Selecione o item rotulado Registros de aplicativos sob o título Serviços no menu que aparece abaixo da barra de pesquisa.
Na página Registos da aplicação, selecione + Novo registo.
Na página Registar uma candidatura, preencha o formulário da seguinte forma. Nome → Insira um nome para o registro do aplicativo no Azure. Recomenda-se que esse nome inclua o nome do aplicativo, o usuário para o qual o registro do aplicativo é feito e um identificador como 'dev' para indicar que esse registro de aplicativo é para uso no desenvolvimento local. Tipos de conta suportados → Contas somente neste diretório organizacional. Selecione Registrar para registrar seu aplicativo e criar a entidade de serviço do aplicativo.
Na página Registo da aplicação para a sua aplicação: ID do aplicativo (cliente) → Esta é a ID do aplicativo que o aplicativo usará para acessar o Azure durante o desenvolvimento local. Copie esse valor para um local temporário em um editor de texto, pois você precisará dele em uma etapa futura. ID do diretório (locatário) → Esse valor também será necessário para seu aplicativo quando ele se autenticar no Azure. Copie esse valor para um local temporário em um editor de texto, pois ele também será necessário em uma etapa futura. Credenciais do cliente → Você deve definir as credenciais do cliente para o aplicativo antes que seu aplicativo possa se autenticar no Azure e usar os serviços do Azure. Selecione Adicionar um certificado ou segredo para adicionar credenciais ao seu aplicativo.
Na página Certificados & segredos, selecione + Novo segredo do cliente.
A caixa de diálogo Adicionar um segredo do cliente aparecerá no lado direito da página. Nesta caixa de diálogo: Descrição → Insira um valor de Atual. Expira → Selecione um valor de 24 meses. Selecione Adicionar para adicionar o segredo.
Na página Certificados & segredos, você verá o valor do segredo do cliente. Copie esse valor para um local temporário em um editor de texto, pois você precisará dele em uma etapa futura. IMPORTANTE: Esta é a única vez que você verá esse valor. Depois de sair ou atualizar esta página, você não poderá ver esse valor novamente. Você pode adicionar um segredo de cliente adicional sem invalidar esse segredo de cliente, mas não verá esse valor novamente.

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

Primeiro, use o comando az ad sp create-for-rbac para criar uma nova entidade de serviço para o aplicativo. Isso também criará o registro do aplicativo ao mesmo tempo.

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. Este é o único lugar onde você vê o segredo do cliente (senha) para a entidade de serviço. No entanto, você pode adicionar uma nova senha mais tarde sem invalidar a entidade de serviço ou as senhas existentes, se necessário.

2 - Criar grupo Microsoft Entra para desenvolvimento local

Como normalmente há vários desenvolvedores que trabalham em um aplicativo, é recomendável criar um grupo do Microsoft Entra para encapsular as funções (permissões) de que o aplicativo precisa no desenvolvimento local, em vez de atribuir as funções a objetos de entidade de serviço individuais. Esta abordagem oferece as seguintes vantagens:

Todos os desenvolvedores têm a garantia de ter as mesmas funções atribuídas, uma vez que as funções são 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, uma nova entidade de serviço de aplicativo será criada para o desenvolvedor e adicionada ao grupo, garantindo que o desenvolvedor tenha as permissões certas para trabalhar no aplicativo.

Portal do Azure
CLI do Azure

Instruções	Captura de ecrã
Navegue até a página ID do Microsoft Entra no portal do Azure digitando ID do Microsoft Entra na caixa de pesquisa na parte superior da página. Selecione Microsoft Entra ID na seção Serviços .
Na página ID do Microsoft Entra , selecione Grupos no menu à esquerda.
Na página Todos os grupos, selecione Novo grupo.
Na página Novo Grupo: Tipo de grupo → Segurança Nome do grupo → Um nome para o grupo de segurança, normalmente criado a partir do nome do aplicativo. Também é útil incluir uma cadeia de caracteres como local-dev no nome do grupo para indicar a finalidade do grupo. Descrição do grupo → Uma descrição do objetivo do grupo. Selecione o link Sem membros selecionados em Membros para adicionar membros ao grupo.
Na caixa de diálogo Adicionar membros : Use a caixa de pesquisa para filtrar a lista de nomes principais na lista. Selecione as entidades de serviço de aplicativo para desenvolvimento local para este aplicativo. À medida que os objetos são selecionados, eles ficam acinzentados e são movidos para a lista Itens selecionados na parte inferior da caixa de diálogo. Quando terminar, selecione o botão Selecionar .
De volta à página Novo grupo , selecione Criar para criar o grupo. O grupo será criado e você será levado de volta para a página Todos os grupos . Pode levar até 30 segundos para que o grupo apareça. Talvez seja necessário atualizar a página devido ao cache no portal do Azure.

O comando az ad group create é usado para criar grupos no Microsoft Entra ID. Os parâmetros --display-name e --mail-nickname são necessários. O nome dado ao grupo deve ser baseado no nome do aplicativo. Também é útil incluir uma frase como 'local-dev' no nome do grupo para indicar o propósito do grupo.

az ad group create \
    --display-name MyDisplay \
    --mail-nickname MyDisplay \
    --description {group-description}

Para adicionar membros ao grupo, você precisa da ID do objeto da entidade de serviço do aplicativo, que é diferente da ID do aplicativo. Use o comando az ad sp list para listar as entidades de serviço disponíveis. O --filter comando parameter aceita filtros no estilo OData e pode ser usado para filtrar a lista conforme mostrado. O --query parâmetro limita as colunas apenas às de interesse.

az ad sp list \
    --filter "startswith(displayName, 'msdocs')" \
    --query "[].{objectId:objectId, displayName:displayName}" \
    --output table

O comando az ad group member add pode ser usado para adicionar membros ao grupo:

az ad group member add \
    --group {group-name} \
    --member-id {object-id}

3 - Atribuir funções à aplicação

Em seguida, determine quais funções (permissões) seu aplicativo precisa em quais recursos e atribua essas funções ao seu aplicativo. Neste exemplo, as funções serão atribuídas ao grupo Microsoft Entra criado na etapa 2. Os grupos podem receber uma função em um 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

Instruções	Captura de ecrã
Localize o grupo de recursos para seu aplicativo pesquisando o nome do grupo de recursos usando a caixa de pesquisa na parte superior do portal do Azure. Navegue até o grupo de recursos selecionando o nome do grupo de recursos sob o título Grupos de Recursos na caixa de diálogo.
Na página do grupo de recursos, selecione Controle de acesso (IAM) no menu à esquerda.
Na página Controle de acesso (IAM): Selecione o separador Atribuição de funções. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.
A página Adicionar atribuição de função lista todas as funções que podem ser atribuídas para o grupo de recursos. Use a caixa de pesquisa para filtrar a lista para um tamanho mais gerenciável. Este exemplo mostra como filtrar funções de Blob de Armazenamento. Selecione a função que pretende atribuir. Selecione Avançar para ir para a próxima tela.
A próxima página Adicionar atribuição de função permite especificar a qual usuário atribuir a função. Selecione Usuário, grupo ou entidade de serviço em Atribuir acesso a. Selecione + Selecionar membros em Membros. Uma caixa de diálogo é aberta no lado direito do portal do Azure.
Na caixa de diálogo Selecionar membros: A caixa de texto Selecionar pode ser usada para filtrar a lista de usuários e grupos em sua assinatura. Se necessário, digite os primeiros caracteres do grupo de desenvolvimento local do Microsoft Entra que você criou para o aplicativo. Selecione o grupo de desenvolvimento local do Microsoft Entra associado ao seu aplicativo. Selecione Selecionar na parte inferior da caixa de diálogo para continuar.
O grupo Microsoft Entra é exibido como selecionado na tela Adicionar atribuição de função. Selecione Rever + atribuir para ir para a página final e, em seguida, Rever + atribuir novamente para concluir o processo.

Uma entidade de serviço de aplicativo recebe uma função no Azure usando o comando az role assignment create :

az role assignment create --assignee "{appId}" \
    --role "{roleName}" \
    --resource-group "{resourceGroupName}"

Para obter os nomes de função aos quais uma entidade de serviço pode ser atribuída, use o comando az role definition list :

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

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

az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-dotnet-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 Atribuir funções do Azure usando a CLI do Azure.

4 - Definir variáveis de ambiente de aplicação

No tempo de execução, DefaultAzureCredential procura as informações da entidade de serviço em uma coleção de 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 ao trabalhar com uma entidade de serviço:

AZURE_CLIENT_ID → O valor da ID do aplicativo.
AZURE_TENANT_ID → O valor de ID do locatário.
AZURE_CLIENT_SECRET → A senha/credencial gerada para o aplicativo.

Ao trabalhar localmente com o Properties Visual Studio, as launchsettings.json variáveis de ambiente podem ser definidas no arquivo na pasta do seu projeto. Quando o aplicativo é iniciado, esses valores são puxados automaticamente. Lembre-se de que essas configurações não acompanham seu aplicativo quando ele é implantado, 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": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID": "11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    }
  }

Ao trabalhar localmente com o Visual Studio Code, as launch.json variáveis de ambiente podem ser definidas no arquivo do seu projeto. Quando o aplicativo for iniciado, esses valores serão puxados automaticamente. Lembre-se de que essas configurações não acompanham seu aplicativo quando ele é implantado, portanto, você precisa configurar variáveis de ambiente em seu ambiente de hospedagem de destino.

"configurations": [
{
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
    }
}

Você pode definir variáveis de ambiente para o Windows a partir da linha de comando. No entanto, ao usar essa abordagem, os valores são acessíveis a todos os aplicativos em execução nesse sistema operacional e podem causar conflitos se você não tiver cuidado. 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 "00000000-0000-0000-0000-000000000000"
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111"
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz"

# Set system environment variables - requires running as admin
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000" /m
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111" /m
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz" /m

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

# Set user environment variables
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "Machine")

5 - Implementar DefaultAzureCredential em seu aplicativo

DefaultAzureCredential é uma sequência opinativa e ordenada de mecanismos para autenticação no Microsoft Entra. Cada mecanismo de autenticação é uma classe derivada da classe TokenCredential e é conhecida como uma credencial. No tempo de execução, DefaultAzureCredential tenta autenticar usando a primeira credencial. Se essa credencial não conseguir adquirir um token de acesso, a próxima credencial na sequência será tentada, e assim por diante, até que um token de acesso seja obtido com êxito. Dessa forma, seu aplicativo pode usar credenciais diferentes em ambientes diferentes sem escrever código específico do ambiente.

A ordem e os locais em que DefaultAzureCredential procura credenciais são encontrados em DefaultAzureCredential.

Para usar DefaultAzureCredentialo , adicione o Azure.Identity e, opcionalmente, os pacotes Microsoft.Extensions.Azure ao seu aplicativo:

Linha de Comandos
Gestor de Pacotes 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 que possam ser acessados por meio de injeção de dependência em todo o aplicativo. No Program.cs, conclua as seguintes etapas para registrar uma classe de cliente e DefaultAzureCredential:

Inclua os namespaces e Microsoft.Extensions.Azure por Azure.Identity meio using de diretivas.
Registre o cliente de serviço do Azure usando o método de extensão -prefixed correspondente Add.
Passe uma instância de DefaultAzureCredential para o UseCredential método.

Por exemplo:

using Microsoft.Extensions.Azure;
using Azure.Identity;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Uma alternativa é UseCredential instanciar DefaultAzureCredential diretamente:

using Azure.Identity;

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

Quando o código anterior é executado em sua estação de trabalho de desenvolvimento local, ele procura nas variáveis de ambiente uma entidade de serviço de aplicativo ou em ferramentas de desenvolvedor instaladas localmente, como o Visual Studio, para um conjunto de credenciais de desenvolvedor. Qualquer uma das abordagens pode ser usada para autenticar o aplicativo nos recursos do Azure durante o desenvolvimento local.

Quando implantado no Azure, esse mesmo código também pode autenticar seu aplicativo em outros recursos do Azure. DefaultAzureCredential Pode recuperar configurações de ambiente e configurações de identidade gerenciada para autenticar em outros serviços automaticamente.

Partilhar via