Como autenticar aplicativos JavaScript hospedados no Azure nos recursos do Azure usando a biblioteca de Identidades do Azure

Artigo
02/03/2025

Quando um aplicativo é hospedado no Azure (usando um serviço como o Serviço de Aplicativo do Azure, o Azure Functions ou os Aplicativos de Contêiner do Azure), você pode usar uma identidade gerenciada para autenticar seu aplicativo com segurança nos recursos do Azure.

Uma identidade gerenciada fornece uma identidade para seu aplicativo, permitindo que ele se conecte a outros recursos do Azure sem precisar usar um segredo (como uma cadeia de conexão ou chave). Internamente, o Azure reconhece a identidade do seu aplicativo e sabe quais recursos o aplicativo está autorizado a acessar. O Azure usa essas informações para obter automaticamente tokens do Microsoft Entra para o aplicativo, permitindo que ele se conecte a outros recursos do Azure sem exigir que você gerencie (crie ou gire) segredos de autenticação.

Tipos de identidade gerenciada

Há dois tipos de identidades gerenciadas:

Identidades gerenciadas atribuídas pelo sistema – recurso único do Azure
Identidades gerenciadas atribuídas pelo usuário – vários recursos do Azure

Este artigo aborda as etapas para habilitar e usar uma identidade gerenciada atribuída pelo sistema para um aplicativo. Se você precisar usar uma identidade gerenciada atribuída pelo usuário, consulte o artigo Gerenciar identidades gerenciadas atribuídas pelo usuário para ver como criar uma identidade gerenciada atribuída pelo usuário.

Identidades gerenciadas atribuídas pelo sistema para um único recurso

As identidades gerenciadas atribuídas pelo sistema são fornecidas e vinculadas diretamente a um recurso do Azure. Ao habilitar a identidade gerenciada em um recurso do Azure, você obtém uma identidade gerenciada atribuída pelo sistema para esse recurso. A identidade gerenciada está vinculada ao ciclo de vida do recurso do Azure. Quando o recurso é excluído, o Azure exclui automaticamente a identidade para você. Como tudo o que você precisa fazer é habilitar a identidade gerenciada para o recurso do Azure que hospeda seu código, esse tipo de identidade é o tipo mais fácil de identidade gerenciada a ser usado.

Identidades gerenciadas atribuídas pelo usuário para vários recursos

Uma identidade gerenciada atribuída pelo usuário é um recurso autônomo do Azure. Esse tipo de identidade é usado com mais frequência quando sua solução tem várias cargas de trabalho executadas em vários recursos do Azure que precisam compartilhar a mesma identidade e as mesmas permissões. Por exemplo, suponha que sua solução inclua aplicativos executados em várias instâncias do Serviço de Aplicativo e da máquina virtual. Todos os aplicativos precisam de acesso ao mesmo conjunto de recursos do Azure. Criar e usar uma identidade gerenciada atribuída pelo usuário nesses recursos é a melhor opção de design.

1 – Habilitar a identidade gerenciada atribuída pelo sistema no aplicativo hospedado

A primeira etapa é habilitar a identidade gerenciada no recurso do Azure que hospeda seu aplicativo. Por exemplo, se você estiver hospedando um aplicativo Express.js usando o Serviço de Aplicativo do Azure, precisará habilitar a identidade gerenciada para esse aplicativo Web do Serviço de Aplicativo. Se você estiver usando uma VM para hospedar seu aplicativo, habilite sua VM para usar a identidade gerenciada.

Você pode habilitar a identidade gerenciada a ser usada para um recurso do Azure usando o portal do Azure ou a CLI do Azure.

Portal do Azure
CLI do Azure

Instruções	Captura de tela
Navegue até o recurso que hospeda o código do aplicativo no portal do Azure. Por exemplo, você pode digitar o nome do recurso na caixa de pesquisa na parte superior da página e navegar até ele selecionando-o na caixa de diálogo.
Na página do recurso, selecione o item de menu Identidade no menu à esquerda. Todos os recursos do Azure capazes de dar suporte à identidade gerenciada terão um item de menu Identidade, embora o layout do menu possa variar ligeiramente.
Na página Identidade: Mova o controle deslizante Status para Ligar. Selecione Salvar. Uma caixa de diálogo de confirmação verifica se você deseja habilitar a identidade gerenciada para seu serviço. Responda Sim para habilitar a identidade gerenciada para o recurso do Azure.

É possível executar os comandos da CLI do Azure no Azure Cloud Shell ou em uma estação de trabalho com a CLI do Azure instalada.

Os comandos da CLI do Azure usados para habilitar a identidade gerenciada para um recurso do Azure são do formulário az <command-group> identity --resource-group <resource-group-name> --name <resource-name>. Comandos específicos para serviços populares do Azure são fornecidos aqui.

Serviço de Aplicativo do Azure
Máquinas Virtuais do Azure

az webapp identity assign --resource-group <resource-group-name> -name <web-app-name>

az vm identity assign --resource-group <resource-group-name> -name <virtual-machine-name>

A saída tem a seguinte aparência.

{
  "principalId": "<REPLACE_WITH_YOUR_PRINCIPAL_ID>",
  "tenantId": "<REPLACE_WITH_YOUR_TENANT_ID>",
  "type": "SystemAssigned",
  "userAssignedIdentities": null
}

O valor principalId é a ID exclusiva da identidade gerenciada. Mantenha uma cópia dessa saída, pois você precisará desses valores na próxima etapa.

2 – Atribuir funções à identidade gerenciada

Em seguida, você precisa determinar de quais funções (permissões) seu aplicativo precisa e atribuir a identidade gerenciada a essas funções no Azure. Uma identidade gerenciada pode ser atribuída a funções em um escopo de recurso, grupo de recursos ou assinatura. Este exemplo mostra como atribuir funções 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.

Portal do Azure
CLI do Azure

Instruções	Captura de tela
Localize o grupo de recursos do aplicativo pesquisando pelo nome do grupo de recursos e 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. Escolha Identidade gerenciada em Atribuir acesso a. Selecionar + Selecionar membros em Membros Uma caixa de diálogo é aberta no lado direito do portal do Azure.
Na caixa de diálogo Selecionar identidades gerenciadas: A lista suspensa Identidade gerenciada e caixa de texto Selecionar podem ser usadas para filtrar a lista de identidades gerenciadas em sua assinatura. Neste exemplo, selecionando Serviço de Aplicativo, somente identidades gerenciadas associadas a um Serviço de Aplicativo são exibidas. Selecione a identidade gerenciada para o recurso do Azure que hospeda seu aplicativo. Para continuar, escolha Selecionar na parte inferior da caixa de diálogo.
A identidade gerenciada aparece como selecionada 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.

Uma identidade gerenciada recebe uma função no Azure usando o comando [az role assignment create].

az role assignment create --assignee "{managedIdentityId}" \
    --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 identidade gerenciada leia, grave e exclua o acesso a contêineres de blobs e dados do Armazenamento do Azure para todas as contas de armazenamento no grupo de recursos msdocs-sdk-auth-example, você atribuiria a entidade de serviço do aplicativo à função Colaborador de Dados do Blob de Armazenamento usando o comando a seguir.

az role assignment create --assignee aaaaaaaa-bbbb-cccc-7777-888888888888 \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-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 o artigo Atribuir funções do Azure usando a CLI do Azure.

3 – Implementar DefaultAzureCredential no seu aplicativo

DefaultAzureCredential detecta automaticamente que uma identidade gerenciada está sendo usada e usa a identidade gerenciada para autenticar em outros recursos do Azure. Conforme discutido no artigo Visão geral da autenticação da Biblioteca de Identidade do Azure para JavaScript, DefaultAzureCredential dá suporte a vários métodos de autenticação e determina o método de autenticação que está sendo usado em tempo de execução. Dessa forma, seu aplicativo pode usar diferentes métodos de autenticação em ambientes diferentes sem implementar código específico do ambiente.

Primeiro, adicione o pacote @azure/identity ao seu aplicativo.

npm install @azure/identity

Em seguida, para qualquer código JavaScript que crie um objeto de cliente do SDK do Azure em seu aplicativo, você deseja:

Importar a classe DefaultAzureCredential do módulo @azure/identity.
Crie um objeto DefaultAzureCredential.
Passar o objeto DefaultAzureCredential para o construtor do objeto do cliente do SDK do Azure.

Um exemplo dessas etapas é mostrado no segmento de código a seguir.

// connect-with-default-azure-credential.js
import { BlobServiceClient } from '@azure/storage-blob';
import { DefaultAzureCredential } from '@azure/identity';
import 'dotenv/config'

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error('Azure Storage accountName not found');

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

Compartilhar via