Tutorial: Conexão segura do Serviço Cognitivo do Serviço de Aplicativo JavaScript usando Key Vault

O Serviço de Aplicativo do Azure pode usar identidades gerenciadas para se conectar a serviços de back-end sem uma cadeia de conexão. Essa abordagem elimina os segredos de conexão para gerenciar e mantém sua conectividade de back-end segura em um ambiente de produção. Quando terminar, você terá um aplicativo que faz chamadas de API para o Foundry Tools sem armazenar segredos de conexão no App Service.

Para serviços de back-end que não dão suporte a identidades gerenciadas e ainda exigem segredos de conexão, você pode usar o Azure Key Vault para gerenciar segredos de conexão. Este tutorial usa o Foundry Tools como exemplo. Quando terminar, você terá um aplicativo que faz chamadas de programação para as Ferramentas Foundry sem armazenar segredos de conexão dentro do App Service.

• Aplicativo de exemplo

Dica

O Foundry Tools dá suporte à autenticação por meio de identidades gerenciadas. Este tutorial usa a autenticação de chave de assinatura para demonstrar como você pode se conectar a um serviço do Azure que não dá suporte a identidades gerenciadas do Serviço de Aplicativo.

Nessa arquitetura:

• As identidades gerenciadas garantem a segurança da conectividade com o Key Vault.
• O App Service acessa os segredos usando referências do Key Vault nas configurações de aplicativo.
• O acesso ao cofre de chaves fica restrito ao aplicativo. Colaboradores de aplicativos, como administradores, podem ter controle total dos recursos do Serviço de Aplicativo e, ao mesmo tempo, não têm acesso aos segredos do Key Vault.
• Se o código do aplicativo já acessar segredos de conexão com as configurações do aplicativo, nenhuma alteração será necessária.

Neste tutorial, você aprenderá:

• Habilitar identidades gerenciadas
• Usar identidades gerenciadas para se conectar ao Key Vault
• Usar referências do Key Vault
• Ferramentas do Access Foundry

Pré-requisitos

Prepare seu ambiente para o Azure CLI.

• Use o ambiente bash em Azure Cloud Shell. Para obter mais informações, consulte Get iniciado com Azure Cloud Shell.

  

• Se você preferir executar comandos de referência da CLI localmente, instalar o Azure CLI. Se você estiver executando em Windows ou macOS, considere executar Azure CLI em um contêiner do Docker. Para obter mais informações, consulte Como executar o Azure CLI em um contêiner do Docker.

  • Se você estiver usando uma instalação local, entre no Azure CLI usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para obter outras opções de entrada, consulte Authenticate para Azure usando Azure CLI.

  • Quando for solicitado, instale a extensão Azure CLI no primeiro uso. Para obter mais informações sobre extensões, consulte Use e gerencie extensões com o Azure CLI.

  • Execute o comando az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

Criar um aplicativo com conectividade com o Foundry Tools

1. Crie um grupo de recursos para conter todos os seus recursos:

   # Save the resource group name as a variable for convenience
   groupName=myKVResourceGroup
   region=canadacentral
   
   az group create --name $groupName --location $region
   

2. Criar um recurso de Ferramentas de Fundição. Substitua <cs-resource-name> por um nome exclusivo.

   # Save the resource name as a variable for convenience. 
   csResourceName=<cs-resource-name>
   
   az cognitiveservices account create --resource-group $groupName --name $csResourceName --location $region --kind TextAnalytics --sku F0 --custom-domain $csResourceName
   

   Observação

   --sku F0 cria um recurso de Ferramentas do Foundry do nível gratuito. Cada assinatura é limitada a uma cota de um recurso de camada gratuita TextAnalytics. Se você já tiver usado sua cota, use --sku S em vez disso.

Configurar o aplicativo JavaScript

Clone o repositório de exemplo localmente e implante o aplicativo de exemplo no Serviço de Aplicativo. Substitua <app-name> por um nome exclusivo do aplicativo.

# Clone and prepare sample application
git clone https://github.com/Azure-Samples/app-service-language-detector.git
cd app-service-language-detector/javascript
zip -r default.zip .

# Save app name as variable for convenience
appName=<app-name>

az appservice plan create --resource-group $groupName --name $appName --sku FREE --location $region --is-linux
az webapp create --resource-group $groupName --plan $appName --name $appName --runtime "node:24-lts"
az webapp config appsettings set --resource-group $groupName --name $appName --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true
az webapp deploy --resource-group $groupName --name $appName --src-path ./default.zip

Os comandos anteriores:

• Criar um plano do Serviço de Aplicativo do Linux
• Criar um aplicativo Web para Node.js 24 LTS
• Configurar o aplicativo Web para instalar os pacotes NPM na implantação
• Carregar o arquivo zip e instalar os pacotes NPM

Configurar segredos como configurações de aplicativo

1. Defina os segredos do Foundry Tools como as configurações de aplicativo CS_ACCOUNT_NAME e CS_ACCOUNT_KEY.

   # Get the subscription key for the Foundry Tools resource
   csKey1=$(az cognitiveservices account keys list --resource-group $groupName --name $csResourceName --query key1 --output tsv)
   
   az webapp config appsettings set --resource-group $groupName --name $appName --settings CS_ACCOUNT_NAME="$csResourceName" CS_ACCOUNT_KEY="$csKey1"
   

2. Em um navegador, acesse seu aplicativo implantado em <app-name>.azurewebsites.net. Experimente o detector de idiomas inserindo cadeias de caracteres em vários idiomas.

   

   Se você examinar o código do aplicativo, a saída de depuração dos resultados da detecção poderá estar na mesma cor da fonte que a tela de fundo. Você pode ver a saída realçando o espaço em branco diretamente abaixo do resultado.

Proteger a conectividade de back-end

Os segredos de conexão agora são armazenados como configurações de aplicativo em seu aplicativo do Serviço de Aplicativo. Essa abordagem já protege os segredos de conexão da base de código do aplicativo. No entanto, qualquer colaborador que possa gerenciar seu aplicativo também pode ver as configurações do aplicativo. Nesta seção, você move os segredos de conexão para um cofre de chaves. Você bloqueia o acesso para que somente você possa gerenciá-lo e somente o aplicativo do Serviço de Aplicativo possa lê-lo usando sua identidade gerenciada.

1. Crie um cofre de chaves. Substitua <vault-name> por um nome exclusivo.

   # Save the key vault name as a variable for convenience
   vaultName=<vault-name>
   
   az keyvault create --resource-group $groupName --name $vaultName --location $region --sku standard --enable-rbac-authorization
   

   O parâmetro --enable-rbac-authorizationdefine o RBAC do Azure (controle de acesso baseado em função) como o modelo de permissão. Essa configuração invalida todas as permissões de políticas de acesso por padrão.

2. Atribua a si mesmo a função RBAC Responsável pelos segredos do Key Vault no cofre.

   vaultResourceId=$(az keyvault show --name $vaultName --query id --output tsv)
   myId=$(az ad signed-in-user show --query id --output tsv)
   az role assignment create --role "Key Vault Secrets Officer" --assignee-object-id $myId --assignee-principal-type User --scope $vaultResourceId
   

3. Habilite a identidade gerenciada atribuída pelo sistema para seu aplicativo e dê a ela a função RBAC Usuário de Segredos do Key Vault no cofre.

   az webapp identity assign --resource-group $groupName --name $appName --scope $vaultResourceId --role  "Key Vault Secrets User"
   

4. Adicione o nome do recurso de Foundry Tools e a chave de subscrição como segredos no gerenciador de segredos e salve as suas IDs como variáveis de ambiente para a próxima etapa.

   csResourceKVUri=$(az keyvault secret set --vault-name $vaultName --name csresource --value $csResourceName --query id --output tsv)
   csKeyKVUri=$(az keyvault secret set --vault-name $vaultName --name cskey --value $csKey1 --query id --output tsv)
   

5. Antes, você definia os segredos como configurações de aplicativo CS_ACCOUNT_NAME e CS_ACCOUNT_KEY em seu aplicativo. Agora, defina-os como referências de Key Vault.

   az webapp config appsettings set --resource-group $groupName --name $appName --settings CS_ACCOUNT_NAME="@Microsoft.KeyVault(SecretUri=$csResourceKVUri)" CS_ACCOUNT_KEY="@Microsoft.KeyVault(SecretUri=$csKeyKVUri)"
   

6. Em um navegador, vá para <app-name>.azurewebsites.net novamente. Se você receber resultados da detecção, estará se conectando ao endpoint do Foundry Tools usando referências ao Key Vault.

Parabéns, seu aplicativo agora se conecta às Ferramentas Foundry utilizando segredos mantidos em seu cofre de segredos, e você não precisou fazer nenhuma alteração no código do aplicativo.

Limpar os recursos

Nas etapas anteriores, você criou recursos do Azure em um grupo de recursos. Se você não espera precisar desses recursos no futuro, exclua o grupo de recursos executando o seguinte comando no Cloud Shell:

az group delete --name $groupName

Esse comando pode levar alguns minutos para ser executado.

Conteúdo relacionado

• Tutorial: Isolar a comunicação de back-end com integração à Virtual Network
• Integrate seu aplicativo com uma rede virtual Azure
• Recursos de rede do Serviço de Aplicativo