Autenticar em recursos do Azure a partir de aplicativos .NET hospedados localmente
Artigo
Os aplicativos hospedados fora do Azure (por exemplo, no local ou em um data center de terceiros) devem usar uma entidade de serviço de aplicativo para autenticar no Azure ao acessar recursos do Azure. Os objetos da entidade de serviço de aplicativo são criados com um processo de registro de aplicativo no Azure. Quando uma entidade de serviço de aplicativo for criada, uma ID do cliente e um segredo do cliente serão gerados para seu aplicativo. A ID do cliente, o segredo do cliente e a sua ID do locatário são armazenados em variáveis de ambiente para que possam ser usadas pela biblioteca do Azure Identity a fim de autenticar seu aplicativo no Azure em runtime.
Um registro de aplicativo diferente deve ser criado para cada ambiente em que o aplicativo está hospedado. Isso permite que as permissões de recurso específicas do ambiente sejam configuradas para cada entidade de serviço e verifica se um aplicativo implantado em outro ambiente não fala com recursos do Azure que fazem parte de outro ambiente.
1 – Registrar o aplicativo no Azure
Um aplicativo pode ser registrado no Azure usando o portal do Azure ou a CLI do Azure.
Insira registros de aplicativos na caixa de pesquisa na parte superior do portal do Azure.
Selecione o item rotulado Registros de aplicativo sob o título Serviços no menu que aparece abaixo da barra de pesquisa.
Na páginaRegistros de aplicativo, selecione + Novo registro.
Na página Registrar um aplicativo, preencha o formulário da seguinte maneira:
Nome → Insira um nome para o registro de aplicativo no Azure. É recomendável que esse nome inclua o nome do aplicativo e o ambiente (teste, prod) referente ao registro do aplicativo.
Tipos de conta compatíveis → Contas somente neste diretório organizacional.
Selecione Registrar para registrar seu aplicativo e criar a entidade de serviço de aplicativo.
Na página Registro de aplicativo do seu aplicativo:
ID do aplicativo (cliente) → Essa é a ID de 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 de diretório (locatário) → Esse valor também será necessário para seu aplicativo quando ele for autenticado no Azure. Copie esse valor para um local temporário em um editor de texto, pois ele 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 e segredos, selecione + Novo segredo do cliente.
A caixa de diálogo Adicionar um segredo de cliente será exibida do lado direito da página. Nesta caixa de diálogo:
Descrição → Inserir um valor de Atual.
Expira → Selecione um valor de 24 meses.
Selecione Adicionar para adicionar o segredo.
IMPORTANTE: defina um lembrete em seu calendário antes da data de validade do segredo. Dessa forma, você pode adicionar um novo segredo antes e atualizar seus aplicativos antes da expiração desse segredo e evitar uma interrupção de serviço em seu aplicativo.
Na página Certificados e segredos, será mostrado 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 do cliente extra sem invalidar esse segredo do cliente, mas não verá esse valor novamente.
az ad sp create-for-rbac --name <app-name>
A saída do comando deve ser semelhante à seguinte. Anote esses valores ou mantenha essa janela aberta, pois você precisará deles na próxima etapa e não poderá exibir a senha (segredo do cliente) novamente.
2 – Atribuir funções à entidade de serviço de aplicativo
Em seguida, você precisa determinar as funções (permissões) de que seu aplicativo precisa em quais recursos e atribuir essas funções ao seu aplicativo. As funções podem ser atribuídas a uma função em um recurso, grupo de recursos ou escopo de assinatura. Este exemplo mostra como atribuir funções para a entidade de serviço no escopo do grupo de recursos, uma vez que a maioria dos aplicativos agrupa todos os seus recursos do Azure em um único grupo de recursos.
Localize o grupo de recursos no 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 no 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 a guia Atribuições de função.
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 ao grupo de recursos.
Use a caixa de pesquisa para filtrar a lista para obter um tamanho mais gerenciável. Este exemplo mostra como filtrar as funções do Blob de Armazenamento.
Selecione a função que você deseja 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 emAtribuir acesso a.
Selecione + Selecionar membros em Membros.
Uma caixa de diálogo será 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 da entidade de serviço que você criou para o aplicativo para filtrar a lista.
Selecione a entidade de serviço associada ao aplicativo.
Para continuar, selecione Selecionar na parte inferior da caixa de diálogo.
Agora, a entidade de serviço será exibida como selecionado na tela Adicionar atribuição de função.
Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.
az role assignment create --assignee "{appId}" \
--role "{roleName}" \
--resource-group "{resourceGroupName}"
Para obter os nomes da 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 com appId de 00000000-0000-0000-0000-000000000000 leitura, gravação e exclusão de acesso aos contêineres e dados do blob de Armazenamento do Microsoft Azure a todas as contas de armazenamento no grupo de recursos msdocs-dotnet-sdk-auth-example, atribua a entidade de serviço do aplicativo à função Colaborador de dados de blob de armazenamento usando o comando a seguir:
az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
--role "Storage Blob Data Contributor" \
--resource-group "msdocs-dotnet-sdk-auth-example"
3 – Configurar variáveis de ambiente para o aplicativo
O objeto DefaultAzureCredential procurará as credenciais da entidade de serviço em um conjunto de variáveis de ambiente em runtime. Há várias maneiras de configurar variáveis de ambiente ao trabalhar com o .NET, dependendo de suas ferramentas e ambiente.
Independentemente da abordagem escolhida, configure as variáveis de ambiente a seguir ao trabalhar com uma entidade de serviço:
AZURE_CLIENT_ID → O valor da ID do aplicativo.
AZURE_TENANT_ID → O valor da ID do locatário.
AZURE_CLIENT_SECRET → A senha/credencial gerada para o aplicativo.
Se o aplicativo estiver hospedado no IIS, recomendamos definir variáveis de ambiente por pool de aplicativos para isolar as configurações entre aplicativos.
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='ASPNETCORE_ENVIRONMENT',value='Production']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_ID',value='00000000-0000-0000-0000-000000000000']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_TENANT_ID',value='11111111-1111-1111-1111-111111111111']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_SECRET',value='=abcdefghijklmnopqrstuvwxyz']" /commit:apphost
Você também pode definir essas configurações diretamente usando o elemento applicationPools dentro do arquivo applicationHost.config:
Você pode definir variáveis de ambiente para Windows na linha de comando. No entanto, quando se usa essa abordagem, os valores são acessíveis a todos os aplicativos em execução nesse sistema operacional e poderão causar conflitos se você não tomar 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
Também é possível usar o PowerShell para definir variáveis de ambiente no nível do usuário ou do computador:
# 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")
4 – Implementar DefaultAzureCredential no 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 runtime, 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 para cada ambiente.
A ordem e os locais em que DefaultAzureCredential procura credenciais são encontrados em DefaultAzureCredential.
Clique com o botão direito do mouse no seu projeto na janela Gerenciador de Soluções do Visual Studio e selecione Gerenciar Pacotes NuGet. Pesquise Azure.Identity e instale o pacote correspondente. Repita esse processo no pacote Microsoft.Extensions.Azure.
Os serviços do Azure são acessados usando classes de cliente especializadas das várias bibliotecas de clientes do SDK do Azure. Essas classes e seus próprios serviços personalizados devem ser registrados para que possam ser acessados pela injeção de dependência no aplicativo. Em Program.cs, conclua as etapas a seguir para registrar uma classe de cliente e DefaultAzureCredential:
Inclua os namespaces Azure.Identity e Microsoft.Extensions.Azure pelas diretivas using.
Registre o cliente de serviço do Azure usando o método de extensão com prefixo Add correspondente.
Passe uma instância do DefaultAzureCredential para o método UseCredential.
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 para UseCredential é criar uma instância 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 é executar na sua estação de trabalho de desenvolvimento local, ele procura nas variáveis de ambiente uma entidade de serviço de aplicativo ou nas ferramentas de desenvolvedor instaladas localmente, como Visual Studio, para um conjunto de credenciais de desenvolvedor. Qualquer abordagem 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-se em outros serviços automaticamente.
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.