Tutorial: Usar uma identidade gerenciada para conectar o Key Vault a um aplicativo Web do Azure no .NET

O Azure Key Vault fornece uma forma de armazenar credenciais e outros segredos com maior segurança. Mas o seu código precisa se autenticar ao Key Vault para recuperá-las. As identidades gerenciadas para recursos do Azure ajudam a solucionar esse problema fornecendo aos serviços do Azure uma identidade gerenciada automaticamente no Microsoft Entra ID. Use essa identidade para autenticar em qualquer serviço que dá suporte à autenticação do Microsoft Entra, incluindo o Key Vault, sem precisar exibir credenciais no código.

Neste tutorial, você criará e implantará o aplicativo Web do Azure para o Serviço de Aplicativo do Azure. Você usará uma identidade gerenciada para autenticar seu aplicativo Web do Azure com um cofre de chaves do Azure usando a biblioteca de clientes de segredo do Azure Key Vault para .NET e a CLI do Azure. Os mesmos princípios básicos se aplicam quando você usa a linguagem de desenvolvimento de sua escolha, o Azure PowerShell e/ou o portal do Azure.

Para saber mais sobre os aplicativos Web e a implantação do Serviço de Aplicativo do Azure apresentados neste tutorial, confira:

• Visão geral do Serviço de Aplicativo
• Criar um aplicativo Web ASP.NET Core no Serviço de Aplicativo do Azure
• Implantação do Git local no Serviço de Aplicativo do Azure

Pré-requisitos

Para concluir este tutorial, você precisará:

• Uma assinatura do Azure. Crie uma gratuitamente.
• O SDK do .NET Core 3.1 (ou posterior).
• Uma instalação do Git da versão 2.28.0 ou posterior.
• A CLI do Azure ou o Azure PowerShell.
• Azure Key Vault. Você pode criar um cofre de chaves usando o portal do Azure, a CLI do Azure ou o Azure PowerShell.
• Um segredo do Key Vault. Você pode criar um segredo usando o portal do Azure, o PowerShell ou a CLI do Azure.

Se já tiver seu aplicativo Web implantado no Serviço de Aplicativo do Azure, você poderá ir diretamente para as seções configurar o acesso do aplicativo Web a um cofre de chaves e modificar o código do aplicativo Web.

Criar um aplicativo .NET Core

Nesta etapa, configure o projeto do .NET Core local.

Em uma janela de terminal no computador, crie um diretório chamado akvwebapp e torne ele o diretório atual:

mkdir akvwebapp
cd akvwebapp

Crie um aplicativo .NET Core usando o comando dotnet new web:

dotnet new web

Execute o aplicativo localmente para saber como ele deve ficar quando implantá-lo no Azure:

dotnet run

Em um navegador da Web, acesse o aplicativo em http://localhost:5000.

Você verá a mensagem "Olá, Mundo" no aplicativo de exemplo exibido na página.

Para saber mais sobre como criar aplicativos Web para o Azure, confira Criar um aplicativo Web ASP.NET Core no Serviço de Aplicativo do Azure

Implantar o aplicativo no Azure

Nesta etapa, você implantará o seu aplicativo .NET Core no Serviço de Aplicativo do Azure usando o Git local. Para obter mais informações sobre como criar e implantar aplicativos, confira Criar um aplicativo Web ASP.NET Core no Azure.

Configurar a implantação do Git local

Na janela do terminal, selecione Ctrl+C para fechar o servidor Web. Inicialize um repositório Git para o projeto do .NET Core:

git init --initial-branch=main
git add .
git commit -m "first commit"

Você pode usar o FTP e o Git local para implantar um aplicativo Web do Azure usando um usuário de implantação. Após configurar o usuário de implantação, use-o em todas as implantações do Azure. O nome de usuário e a senha da implantação no nível da conta são diferentes das credenciais de assinatura do Azure.

Para configurar o usuário de implantação, execute o comando az webapp deployment user set. Escolha um nome de usuário e senha que sigam estas diretrizes:

• O nome do usuário deve ser exclusivo no Azure. Para pushes de Git locais, ele não pode conter o símbolo de arroba (@).
• A senha precisa ter pelo menos oito caracteres e conter dois destes três elementos: letras, números, símbolos.

az webapp deployment user set --user-name "<username>" --password "<password>"

A saída JSON mostra a senha como null. Se receber o erro 'Conflict'. Details: 409, altere o nome de usuário. Se receber um erro 'Bad Request'. Details: 400, use uma senha mais forte.

Registre o seu nome de usuário e senha para usá-los na implantação de aplicativos Web.

Criar um grupo de recursos

Um grupo de recursos é um contêiner lógico no qual você implanta recursos do Azure e os gerencia. Crie um grupo de recursos para conter o cofre de chaves e o seu aplicativo Web usando o comando az group create:

az group create --name "myResourceGroup" -l "EastUS"

Criar um plano de Serviço de Aplicativo

Crie um Plano do Serviço de Aplicativo usando o comando az appservice plan create da CLI do Azure. O seguinte exemplo cria um plano do Serviço de Aplicativo denominado myAppServicePlan usando o tipo de preço FREE:

az appservice plan create --name myAppServicePlan --resource-group myResourceGroup --sku FREE

Quando o Plano do Serviço de Aplicativo é criado, a CLI do Azure exibe informações semelhantes ao seguinte exemplo:

{ 
  "adminSiteName": null,
  "appServicePlanName": "myAppServicePlan",
  "geoRegion": "West Europe",
  "hostingEnvironmentProfile": null,
  "id": "/subscriptions/0000-0000/resourceGroups/myResourceGroup/providers/Microsoft.Web/serverfarms/myAppServicePlan",
  "kind": "app",
  "location": "West Europe",
  "maximumNumberOfWorkers": 1,
  "name": "myAppServicePlan",
  < JSON data removed for brevity. >
  "targetWorkerSizeId": 0,
  "type": "Microsoft.Web/serverfarms",
  "workerTierName": null
} 

Para obter mais informações, confira Gerenciar um plano do Serviço de Aplicativo no Azure.

Criar um aplicativo Web

Crie um Aplicativo Web do Azure no plano do serviço de aplicativo myAppServicePlan.

Importante

Semelhante ao cofre de chaves, um aplicativo Web do Azure precisa ter um nome exclusivo. Substitua <your-webapp-name> pelo nome do aplicativo Web como nos exemplos a seguir.

az webapp create --resource-group "myResourceGroup" --plan "myAppServicePlan" --name "<your-webapp-name>" --deployment-local-git

Quando o aplicativo Web é criado, a CLI do Azure mostra um resultado semelhante ao seguinte exemplo:

Local git is configured with url of 'https://<username>@<your-webapp-name>.scm.azurewebsites.net/<ayour-webapp-name>.git'
{
  "availabilityState": "Normal",
  "clientAffinityEnabled": true,
  "clientCertEnabled": false,
  "clientCertExclusionPaths": null,
  "cloningInfo": null,
  "containerSize": 0,
  "dailyMemoryTimeQuota": 0,
  "defaultHostName": "<your-webapp-name>.azurewebsites.net",
  "deploymentLocalGitUrl": "https://<username>@<your-webapp-name>.scm.azurewebsites.net/<your-webapp-name>.git",
  "enabled": true,
  < JSON data removed for brevity. >
}

A URL do Git remoto é mostrada na propriedade deploymentLocalGitUrl no formato https://<username>@<your-webapp-name>.scm.azurewebsites.net/<your-webapp-name>.git. Salve essa URL. Você precisará dela mais tarde.

Agora configure seu aplicativo Web para implantação por meio do branch main:

 az webapp config appsettings set -g MyResourceGroup --name "<your-webapp-name>" --settings deployment_branch=main

Acesse o seu novo aplicativo usando o comando a seguir. Substitua <your-webapp-name> pelo nome do aplicativo.

https://<your-webapp-name>.azurewebsites.net

Você verá a página da Web padrão de um novo aplicativo Web do Azure.

Implantar seu aplicativo local

De volta na janela do terminal local, adicione um remoto do Azure ao repositório Git local. No comando a seguir, substitua <deploymentLocalGitUrl-from-create-step> pela URL do Git remoto que você salvou na seção Criar um aplicativo Web.

git remote add azure <deploymentLocalGitUrl-from-create-step>

Use o comando a seguir para enviar por push para o Azure remoto para implantar o seu aplicativo. Quando o Gerenciador de Credenciais do Git solicitar as credenciais, use as credenciais criadas na seção Configurar uma implantação do Git local.

git push azure main

Esse comando pode levar alguns minutos para ser executado. Enquanto ele é executado, ele exibe informações semelhantes às que você vê aqui:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 285 bytes | 95.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Deploy Async
remote: Updating branch 'main'.
remote: Updating submodules.
remote: Preparing deployment for commit id 'd6b54472f7'.
remote: Repository path is /home/site/repository
remote: Running oryx build...
remote: Build orchestrated by Microsoft Oryx, https://github.com/Microsoft/Oryx
remote: You can report issues at https://github.com/Microsoft/Oryx/issues
remote:
remote: Oryx Version      : 0.2.20200114.13, Commit: 204922f30f8e8d41f5241b8c218425ef89106d1d, ReleaseTagName: 20200114.13
remote: Build Operation ID: |imoMY2y77/s=.40ca2a87_
remote: Repository Commit : d6b54472f7e8e9fd885ffafaa64522e74cf370e1
.
.
.
remote: Deployment successful.
remote: Deployment Logs : 'https://<your-webapp-name>.scm.azurewebsites.net/newui/jsonviewer?view_url=/api/deployments/d6b54472f7e8e9fd885ffafaa64522e74cf370e1/log'
To https://<your-webapp-name>.scm.azurewebsites.net:443/<your-webapp-name>.git
   d87e6ca..d6b5447  main -> main

Acesse (ou atualize) o aplicativo implantado usando o navegador da Web:

http://<your-webapp-name>.azurewebsites.net

Você verá a mensagem "Olá Mundo!" que você viu anteriormente quando visitou http://localhost:5000.

Para saber mais sobre como implantar o aplicativo Web usando o Git, confira Implantação do Git local no Serviço de Aplicativo do Azure

Configurar o aplicativo Web para se conectar ao Key Vault

Nesta seção, você vai configurar o acesso à Web ao Key Vault e atualizar o seu código do aplicativo para recuperar o segredo do Key Vault.

Criar e atribuir acesso a uma identidade gerenciada

Neste tutorial, usaremos a identidade gerenciada para autenticar no Key Vault. A identidade gerenciada gerencia automaticamente as credenciais do aplicativo.

Na CLI do Azure, para criar a identidade do aplicativo, execute o comando az webapp-identity assign:

az webapp identity assign --name "<your-webapp-name>" --resource-group "myResourceGroup"

O comando retornará este snippet de código de JSON:

{
  "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "SystemAssigned"
}

CLI do Azure

Para conceder permissões de aplicativo ao cofre de chaves por meio do controle de acesso baseado em função (RBAC), atribua uma função usando o comando az role assignment create da CLI do Azure.

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

PowerShell do Azure

Para conceder permissões de aplicativo ao cofre de chaves por meio do Controle de Acesso Baseado em Função (RBAC), atribua uma função usando o cmdlet New-AzRoleAssignment do Azure PowerShell.

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Substitua <app-id>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> pelos valores reais. <app-id> é a ID do Aplicativo (cliente) do aplicativo registrado no Microsoft Entra.

Modificar o aplicativo para acessar o cofre de chaves

Neste tutorial, você usará a biblioteca de clientes do segredo do Azure Key Vault para fins de demonstração. Você também pode usar a biblioteca de clientes do certificado do Azure Key Vault ou a biblioteca de clientes da chave do Azure Key Vault.

Instalar os pacotes

Na janela do terminal, instale a biblioteca de clientes do segredo do Azure Key Vault para .NET e os pacotes da biblioteca de clientes do cliente da Identidade do Azure:

dotnet add package Azure.Identity
dotnet add package Azure.Security.KeyVault.Secrets

Atualizar o código

Localize e abra o arquivo Startup.cs para .NET 5.0 ou anterior ou o arquivo Program.cs para .NET 6.0 no projeto akvwebapp.

Adicione estas linhas ao cabeçalho:

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Azure.Core;

Adicione as linhas a seguir antes da chamada app.UseEndpoints (.NET 5.0 ou anterior) ou app.MapGet (.NET 6.0), atualizando o URI para refletir o vaultUri do cofre de chaves. Esse código usa DefaultAzureCredential() para autenticar-se ao Key Vault, que usa um token da identidade gerenciada para se autenticar. Para obter mais informações sobre como se autenticar ao Key Vault, confira o Guia do desenvolvedor. O código também usa a retirada exponencial para novas tentativas, caso o Key Vault esteja sendo limitado. Para obter mais informações sobre os limites de transações do Key Vault, confira Diretrizes de limitação do Azure Key Vault.

SecretClientOptions options = new SecretClientOptions()
    {
        Retry =
        {
            Delay= TimeSpan.FromSeconds(2),
            MaxDelay = TimeSpan.FromSeconds(16),
            MaxRetries = 5,
            Mode = RetryMode.Exponential
         }
    };
var client = new SecretClient(new Uri("https://<your-unique-key-vault-name>.vault.azure.net/"), new DefaultAzureCredential(),options);

KeyVaultSecret secret = client.GetSecret("<mySecret>");

string secretValue = secret.Value;

.NET 5.0 ou anterior

Atualize a linha await context.Response.WriteAsync("Hello World!"); para que ela se pareça com esta:

await context.Response.WriteAsync(secretValue);

.NET 6.0

Atualize a linha app.MapGet("/", () => "Hello World!"); para que ela se pareça com esta:

app.MapGet("/", () => secretValue);

Salve as suas alterações antes de prosseguir para a próxima etapa.

Reimplantar seu aplicativo Web

Agora que você atualizou o seu código, você pode reimplantá-lo no Azure usando seguintes comandos do Git:

git add .
git commit -m "Updated web app to access my key vault"
git push azure main

Acesse o seu aplicativo Web concluído

http://<your-webapp-name>.azurewebsites.net

No qual, antes de ver “Olá, Mundo!”, agora você deverá ver o valor do seu segredo exibido.

Próximas etapas

• Usar o Azure Key Vault com os aplicativos implantados em uma máquina virtual no .NET
• Aprenda sobre identidades gerenciadas para recursos do Azure
• Exibir o Guia do desenvolvedor
• Proteger o acesso a um cofre de chaves