Tutorial: Ligação Segura ao Serviço Cognitivo a partir do JavaScript App Service usando o Key Vault

O Azure App Service pode usar identidades geridas para se ligar a serviços back-end sem uma cadeia de ligação. Esta abordagem elimina segredos de ligação a gerir e mantém a sua conectividade back-end segura num ambiente de produção. Quando terminares, tens uma aplicação que faz chamadas programáticas para o Foundry Tools sem guardar quaisquer segredos de ligação no App Service.

Para serviços de back-end que não suportam identidades geridas e ainda assim exigem segredos de ligação, podes usar o Azure Key Vault para gerir segredos de ligação. Este tutorial usa o Foundry Tools como exemplo. Quando terminares, tens uma aplicação que faz chamadas programáticas para o Foundry Tools sem guardar quaisquer segredos de ligação dentro do App Service.

Aplicação de exemplo

Gorjeta

O Foundry Tools suporta autenticação através de identidades geridas. Este tutorial utiliza autenticação por chave de subscrição para demonstrar como se pode ligar a um serviço Azure que não suporta identidades geridas a partir do App Service.

Diagrama que mostra o utilizador a ligar-se a um serviço, que por sua vez se liga a um cofre de chaves para aceder aos Serviços Cognitivos.

Nesta arquitetura:

Identidades geridas garantem a ligação ao cofre de chaves.
O Serviço de Aplicações acede aos segredos usando referências ao Key Vault como definições da aplicação.
O acesso ao cofre de chaves é restrito ao aplicativo. Os colaboradores da aplicação, como os administradores, podem ter controlo total sobre os recursos do Serviço de Aplicações e, ao mesmo tempo, não ter acesso aos segredos do Key Vault.
Se o código do seu aplicativo já acessar segredos de conexão com as configurações do aplicativo, nenhuma alteração será necessária.

Neste tutorial, você aprende:

Ativar identidades geridas
Use identidades geridas para se ligar ao Key Vault
Utilize referências ao Key Vault
Aceder às Ferramentas da Fundição

Pré-requisitos

Prepare o seu ambiente para a Azure CLI.

Usa o ambiente Bash em Azure Cloud Shell. Para mais informações, consulte Comece com Azure Cloud Shell.
Se preferires executar comandos de referência de CLI localmente, instala a Azure CLI. Se estiveres a correr no Windows ou macOS, considera executar Azure CLI num contentor Docker. Para mais informações, veja Como executar o Azure CLI num contentor Docker.
- Se estiveres a usar uma instalação local, inicia sessão na Azure CLI usando o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de iniciação de sessão, veja Autenticar para Azure usando Azure CLI.
- Quando for solicitado, instale a extensão Azure CLI na primeira utilização. Para mais informações sobre extensões, veja Usar e gerir extensões com a Azure CLI.
- Execute az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.

Crie uma aplicação com ligação ao Foundry Tools

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

Crie um recurso para Foundry Tools. Substitua <cs-resource-name> por um nome único.
```
# 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
```
Nota

--sku F0 cria um recurso de nível gratuito do Foundry Tools. Cada assinatura é limitada a uma cota de um recurso de nível TextAnalytics gratuito. Se já usou a sua quota, use --sku S em vez disso.

Configurar 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.

# 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 de Serviço de Aplicações Linux
Crie uma aplicação web para Node.js 24 LTS
Configurar o aplicativo Web para instalar os pacotes npm na implantação
Carregue o arquivo zip e instale os pacotes npm

Configurar segredos como configurações de aplicativo

Configure os segredos das Foundry Tools como definições de aplicação 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"

Num navegador, vá à sua aplicação implementada em <app-name>.azurewebsites.net. Experimenta o detector de línguas introduzindo cadeias em várias línguas.

Se você olhar para o código da aplicação, a saída de depuração para os resultados de deteção pode estar na mesma cor da fonte que o fundo. Pode ver o resultado ao destacar o espaço em branco diretamente abaixo do resultado.

Conectividade de back-end segura

Os segredos de ligação estão agora guardados como definições da aplicação na aplicação do Serviço de Aplicações. Esta abordagem já protege os segredos de conexão do código da sua aplicação. No entanto, qualquer colaborador que possa gerenciar seu aplicativo também poderá ver as configurações do aplicativo. Nesta secção, transferes os segredos da ligação para um cofre de chaves. Bloqueias o acesso para que só tu possas geri-lo e só a aplicação do App Service o possa ler usando a sua identidade gerida.

Criar 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 controlo de acesso baseado em funções (RBAC) do Azure como o modelo de permissões. Esta definição invalida todas as permissões das políticas de acesso por defeito.

Conceda-se a si próprio o papel Key Vault Secrets Officer RBAC para o 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

Ative a identidade gerida atribuída pelo sistema para a sua aplicação e dê-lhe o papel RBAC Key Vault Secrets User para o cofre.
```
az webapp identity assign --resource-group $groupName --name $appName --scope $vaultResourceId --role  "Key Vault Secrets User"
```

Adicione o nome do recurso Foundry Tools e a chave de subscrição como segredos ao cofre, e guarde os IDs destes como variáveis de ambiente para o próximo passo.

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)

Anteriormente, você definia os segredos como configurações CS_ACCOUNT_NAME do aplicativo e CS_ACCOUNT_KEY no seu aplicativo. Agora, defina-os como referências de cofre de chaves.

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)"

Num navegador, aceda a <app-name>.azurewebsites.net novamente. Se obtiver resultados de deteção, está a conectar-se ao endpoint do Foundry Tools usando referências de cofre de chaves.

Parabéns, a sua aplicação agora liga-se ao Foundry Tools usando segredos guardados no seu cofre de chaves, e não fez quaisquer alterações ao código da sua aplicação.

Limpar recursos

Nos passos anteriores, criou recursos do Azure num grupo de recursos. Se não espera precisar destes recursos no futuro, elimine o grupo de recursos executando o seguinte comando na Cloud Shell:

az group delete --name $groupName

Esse comando pode levar um minuto para ser executado.

Comentários

Esta página foi útil?

Last updated on 2026-04-24