Autenticar aplicativos JavaScript hospedados no Azure para recursos do Azure usando uma identidade gerenciada atribuída pelo usuário

A abordagem recomendada para autenticar um aplicativo hospedado em Azure para outros recursos Azure é usar uma identidade gerenciada. Essa abordagem é com suporte para a maioria dos serviços Azure, incluindo aplicativos hospedados em Azure App Service, Azure Container Apps e Azure Virtual Machines. Descubra mais sobre diferentes técnicas e abordagens de autenticação na página de visão geral da autenticação . Nas seções a seguir, você aprenderá:

Conceitos essenciais de identidade gerenciada
Como criar uma identidade gerenciada atribuída pelo usuário para seu aplicativo
Como atribuir funções à identidade gerenciada atribuída pelo usuário
Como autenticar usando a identidade gerenciada atribuída ao usuário a partir do código do aplicativo

Conceitos essenciais de identidade gerenciada

Uma identidade gerenciada permite que seu aplicativo se conecte com segurança a outros recursos Azure sem o uso de chaves secretas ou outros segredos do aplicativo. Internamente, Azure controla a identidade e os recursos aos quais tem permissão para se conectar. Azure usa essas informações para obter automaticamente Microsoft Entra tokens para o aplicativo para permitir que ele se conecte a outros recursos Azure.

Há dois tipos de identidades gerenciadas a serem consideradas ao configurar seu aplicativo hospedado:

As identidades gerenciadas atribuídas pelo sistema são habilitadas diretamente em um recurso do Azure e estão vinculadas ao seu ciclo de vida. Quando o recurso é excluído, Azure exclui automaticamente a identidade para você. As identidades atribuídas pelo sistema fornecem uma abordagem minimalista para o uso de identidades gerenciadas.
Identidades gerenciadas atribuídas ao usuário são criadas como recursos autônomos do Azure e oferecem maior flexibilidade e funcionalidades. Elas são ideais para soluções que envolvem vários recursos de Azure que precisam compartilhar a mesma identidade e permissões. Por exemplo, se várias máquinas virtuais precisarem acessar o mesmo conjunto de recursos Azure, uma identidade gerenciada atribuída pelo usuário fornecerá reutilização e gerenciamento otimizado.

Dica

Saiba mais sobre como selecionar e gerenciar identidades gerenciadas atribuídas pelo sistema e atribuídas pelo usuário no artigo de recomendações de melhores práticas de identidade gerenciada .

As seções a seguir descrevem as etapas para habilitar e usar uma identidade gerenciada atribuída pelo usuário para um aplicativo hospedado Azure. Se você precisar usar uma identidade gerenciada atribuída pelo sistema, visite o artigo de identidades gerenciadas atribuídas pelo sistema para obter mais informações.

Criar uma identidade gerenciada atribuída ao usuário

As identidades gerenciadas atribuídas pelo usuário são criadas como recursos autônomos em sua assinatura de Azure usando o portal Azure ou o Azure CLI. Azure CLI comandos podem ser executados no Azure Cloud Shell ou em uma estação de trabalho com o Azure CLI instalado.

Azure portal
Azure CLI

No portal do Azure, insira Configurações gerenciadas na barra de pesquisa principal e selecione o resultado correspondente na seção Services.
Na página Identidades Gerenciadas , selecione + Criar.
Na página Criar Identidade Gerenciada Atribuída ao Usuário , selecione uma assinatura, um grupo de recursos e uma região para a identidade gerenciada atribuída pelo usuário e forneça um nome.
Selecione Examinar + criar para examinar e validar suas entradas.
Selecione Criar para criar a identidade gerenciada atribuída pelo usuário.
Depois que a identidade for criada, selecione Ir para o recurso.
Na página Visão geral da nova identidade, copie o valor da ID do cliente a ser usado posteriormente quando você configurar o código do aplicativo.

Use o comando Azure CLI az identity create para criar uma identidade gerenciada:

az identity create \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId' \
    --output json

A saída do comando imprime a ID do cliente da identidade gerenciada atribuída pelo usuário criada. A ID do cliente é usada para configurar o código do aplicativo que depende da identidade.

Você sempre pode exibir as propriedades de identidade gerenciada novamente usando o az identity show comando:

az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json

Atribuir a identidade gerenciada ao seu aplicativo

Uma identidade gerenciada atribuída pelo usuário pode ser associada a um ou mais recursos Azure. Todos os recursos que utilizam essa identidade recebem as permissões atribuídas pelas funções da identidade.

Azure portal
Azure CLI

No portal Azure, navegue até o recurso que hospeda o código do aplicativo, como uma instância Azure App Service ou Azure Container Apps.
Na página Visão geral do recurso, expanda Configurações e selecione Identidade na navegação.
Na página Identidade, alterne para a aba Atribuição do usuário.
Selecione + Adicionar para abrir o painel Adicionar identidade gerenciada atribuída pelo usuário .
No painel Adicionar identidade gerenciada atribuída pelo usuário, use a lista suspensa Assinatura para filtrar as identidades nos resultados da pesquisa. Use a caixa de pesquisa Identidades gerenciadas atribuídas pelo usuário para localizar a identidade gerenciada atribuída pelo usuário que você habilitou para o recurso Azure que hospeda seu aplicativo.
Selecione a identidade e escolha Adicionar na parte inferior do painel para continuar.

O Azure CLI fornece comandos diferentes para atribuir uma identidade gerenciada atribuída pelo usuário a diferentes tipos de serviços de hospedagem.

Para atribuir uma identidade gerenciada pelo usuário a um recurso, como um aplicativo Web do Azure App Service, usando o Azure CLI, você precisará da ID da identidade. Use o az identity show comando para recuperar a ID do recurso:
```
az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json \
    --query id
```

Depois de ter a ID do recurso, use o comando Azure CLI comando az <resourceType> identity assign para associar a identidade gerenciada atribuída pelo usuário a recursos diferentes, como o seguinte:

Para Azure App Service, use o comando Azure CLI az webapp identity assign:

az webapp identity assign \
    --resource-group <resource-group-name> \
    --name <webapp-name> \
    --identities <user-assigned-identity-resource-id>

Para Azure Container Apps, use o comando Azure CLI az containerapp identity assign:

az containerapp identity assign \
    --resource-group <resource-group-name> \
    --name <containerapp-name> \
    --user-assigned <user-assigned-identity-resource-id>

Para Azure Virtual Machines, use o comando Azure CLI az vm identity assign:

az vm identity assign \
    --resource-group <resource-group-name> \
    --name <vm-name> \
    --identities <user-assigned-identity-resource-id>

Atribuir funções à identidade gerenciada

Em seguida, determine quais funções seu aplicativo precisa e atribua essas funções à identidade gerenciada. Você pode atribuir funções a uma identidade gerenciada nos seguintes escopos:

Recurso: as funções atribuídas se aplicam somente a esse recurso específico.
Grupo de recursos: as funções atribuídas se aplicam a todos os recursos contidos no grupo de recursos.
Assinatura: as funções atribuídas se aplicam a todos os recursos contidos na assinatura.

O exemplo a seguir mostra como atribuir funções no escopo do grupo de recursos, já que muitos aplicativos gerenciam todos os recursos de Azure relacionados usando um único grupo de recursos.

Azure portal
Azure CLI

Navegue até a página Visão geral do grupo de recursos que contém o aplicativo com a identidade gerenciada atribuída pelo usuário.
Selecione controle de acesso (IAM) na navegação à esquerda.
Na página controle de acesso (IAM ), selecione + Adicionar no menu superior e, em seguida, escolha Adicionar atribuição de função para navegar até a página Adicionar atribuição de função .
A página Adicionar atribuição de função apresenta um fluxo de trabalho de várias etapas com guias para atribuir funções a identidades. Na guia Função inicial, use a caixa de pesquisa na parte superior para localizar a função que você deseja atribuir à identidade.
Selecione a função nos resultados e, em seguida , escolha Avançar para ir para a guia Membros .
Para a opção Atribuir acesso à opção, selecione Identidade gerenciada.
Para a opção Membros , escolha + Selecionar membros para abrir o painel Selecionar identidades gerenciadas .
No painel Selecionar identidades gerenciadas , use as listas suspensas Assinatura e Identidade Gerenciada para filtrar os resultados da pesquisa para suas identidades. Use a caixa de pesquisa Select para localizar a identidade gerenciada atribuída pelo usuário que você habilitou para o recurso Azure que hospeda seu aplicativo.
Selecione a identidade e escolha Selecionar na parte inferior do painel para continuar.
Selecione Examinar + atribuir na parte inferior da página.
Na guia Revisão + atribuição final, selecione Examinar + atribuir para concluir o fluxo de trabalho.

Para atribuir uma função a uma identidade gerenciada atribuída pelo usuário usando o Azure CLI, você precisará da ID principal da identidade. Use o az identity show comando para recuperar a ID principal.
```
az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json \
    --query principalId
```

Use o comando az role definition list para explorar quais funções uma identidade gerenciada pode ser atribuída:

az role definition list \
    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
    --output table

Atribua uma função a uma identidade gerenciada usando o comando az role assignment create :
```
az role assignment create \
    --assignee <your-principal-id> \
    --role <role-name> \
    --scope <scope>
```
Por exemplo, para permitir que a identidade gerenciada com a ID 99999999-9999-9999-9999-999999999999 tenha acesso para ler, gravar e excluir aos contêineres de blob e dados do Azure Storage em todas as contas de armazenamento no grupo de recursos msdocs-sdk-auth-example, atribua o principal de serviço do aplicativo à função Storage Blob Data Contributor usando o seguinte comando:
```
az role assignment create \
    --assignee 99999999-9999-9999-9999-999999999999 \
    --role "Storage Blob Data Contributor" \
    --scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-sdk-auth-example"
```

Para obter informações sobre como atribuir permissões no nível do recurso ou da assinatura usando o Azure CLI, consulte o artigo Atribuir funções do Azure usando o Azure CLI.

Autenticar nos serviços do Azure a partir do seu aplicativo

A biblioteca Azure Identity fornece várias credenciais - implementações de TokenCredential adaptadas para dar suporte a diferentes cenários e fluxos de autenticação do Microsoft Entra. Como a identidade gerenciada não está disponível ao ser executada localmente, as etapas à frente demonstram qual credencial usar em qual cenário:

Ambiente de desenvolvimento local: somente durante o desenvolvimento local, use uma classe chamada DefaultAzureCredential para uma cadeia de credenciais opinativa e pré-configurada. DefaultAzureCredential descobre as credenciais do usuário de seu IDE ou ferramentas locais, como o Azure CLI ou Visual Studio Code. Ele também oferece flexibilidade e conveniência para novas tentativas, tempos de espera para respostas e suporte para várias opções de autenticação. Visite o artigo Autenticação nos serviços do Azure durante o desenvolvimento local para saber mais.
Azure-hosted apps: quando o aplicativo estiver em execução no Azure, use ManagedIdentityCredential para descobrir com segurança a identidade gerenciada configurada para seu aplicativo. Especificar esse tipo exato de credencial impede que outras credenciais disponíveis sejam coletadas inesperadamente.

Implementar o código

Em um projeto JavaScript, adicione o pacote @azure/identidade . Em um terminal de sua escolha, navegue até o diretório do projeto de aplicativo e execute os seguintes comandos:

npm install @azure/identity

Azure serviços são acessados usando classes de cliente especializadas das várias bibliotecas de cliente Azure SDK. Em index.js, conclua as seguintes etapas para configurar a autenticação baseada em token:

Importe o @azure/identity pacote.
Passe uma instância apropriada TokenCredential para o cliente:
- Use DefaultAzureCredential quando o aplicativo estiver em execução localmente.
- Use ManagedIdentityCredential quando o aplicativo estiver em execução no Azure e configurar a ID do cliente, a ID do recurso ou a ID do objeto.

A ID do cliente é usada para identificar uma identidade gerenciada ao configurar aplicativos ou serviços que precisam ser autenticados usando essa identidade.

Recupere a ID do cliente atribuída a uma identidade gerenciada atribuída pelo usuário usando o seguinte comando:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId'

Configure ManagedIdentityCredential com o ID do cliente:

import { BlobServiceClient } from '@azure/storage-blob';
import { ManagedIdentityCredential, DefaultAzureCredential } from '@azure/identity';

console.log(process.env);

function createBlobServiceClient() {
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    if (!accountName) throw Error('Azure Storage accountName not found');
    const url = `https://${accountName}.blob.core.windows.net`;

    if (process.env.NODE_ENV === "production") {
        const clientId = process.env.AZURE_CLIENT_ID;
        if (!clientId) throw Error('AZURE_CLIENT_ID not found for Managed Identity');
        return new BlobServiceClient(url, new ManagedIdentityCredential(clientId));
    } else {
        return new BlobServiceClient(url, new DefaultAzureCredential());
    }
}

async function main() {
    try {
        const blobServiceClient = createBlobServiceClient();
        const containerClient = blobServiceClient.getContainerClient(process.env.AZURE_STORAGE_CONTAINER_NAME);
        // do something with client
        const properties = await containerClient.getProperties();

        console.log(properties);
    } catch (err) {
        console.error("Error retrieving container properties:", err.message);
        throw err;
    }
}

main().catch((err) => {
    console.error("Error running sample:", err.message);
    process.exit(1);
});

A ID do recurso identifica exclusivamente o recurso de identidade gerenciada em sua assinatura Azure usando a seguinte estrutura:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}

As IDs de recurso podem ser criadas por convenção, o que as torna mais convenientes ao trabalhar com um grande número de identidades gerenciadas atribuídas pelo usuário em seu ambiente.

Recupere a ID do recurso para uma identidade gerenciada atribuída pelo usuário usando o seguinte comando:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'id'

Configure ManagedIdentityCredential com a ID do recurso:

import { BlobServiceClient } from '@azure/storage-blob';
import { ManagedIdentityCredential, DefaultAzureCredential } from '@azure/identity';


function createBlobServiceClient() {
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    if (!accountName) throw Error('Azure Storage accountName not found');
    const url = `https://${accountName}.blob.core.windows.net`;

    if (process.env.NODE_ENV === "production") {
        const resourceId = process.env.AZURE_RESOURCE_ID;
        if (!resourceId) throw Error('AZURE_RESOURCE_ID not found for Managed Identity');
        return new BlobServiceClient(url, new ManagedIdentityCredential(resourceId));
    } else {
        return new BlobServiceClient(url, new DefaultAzureCredential());
    }
}

async function main() {
    try {
        const blobServiceClient = createBlobServiceClient();
        const containerClient = blobServiceClient.getContainerClient(process.env.AZURE_STORAGE_CONTAINER_NAME);
        // do something with client
        const properties = await containerClient.getProperties();

        console.log(properties);
    } catch (err) {
        console.error("Error retrieving container properties:", err.message);
        throw err;
    }
}

main().catch((err) => {
    console.error("Error running sample:", err.message);
    process.exit(1);
});

Uma ID principal é outro nome para uma ID de objeto.

Recupere a ID do objeto para uma identidade gerenciada atribuída pelo usuário usando o seguinte comando:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'principalId'

Configure ManagedIdentityCredential com a ID do objeto:

import { BlobServiceClient } from '@azure/storage-blob';
import { ManagedIdentityCredential, DefaultAzureCredential } from '@azure/identity';


function createBlobServiceClient() {
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    if (!accountName) throw Error('Azure Storage accountName not found');
    const url = `https://${accountName}.blob.core.windows.net`;

    if (process.env.NODE_ENV === "production") {
        const objectId = process.env.AZURE_OBJECT_ID;
        if (!objectId) throw Error('AZURE_OBJECT_ID not found for Managed Identity');
        return new BlobServiceClient(url, new ManagedIdentityCredential(objectId));
    } else {
        return new BlobServiceClient(url, new DefaultAzureCredential());
    }
}

async function main() {
    try {
        const blobServiceClient = createBlobServiceClient();
        const containerClient = blobServiceClient.getContainerClient(process.env.AZURE_STORAGE_CONTAINER_NAME);
        // do something with client
        const properties = await containerClient.getProperties();

        console.log(properties);
    } catch (err) {
        console.error("Error retrieving container properties:", err.message);
        throw err;
    }
}

main().catch((err) => {
    console.error("Error running sample:", err.message);
    process.exit(1);
});

Implementar o código

Em um projeto TypeScript, adicione o pacote @azure/identidade . Em um terminal de sua escolha, navegue até o diretório do projeto de aplicativo e execute os seguintes comandos:

npm install typescript @azure/identity @types/node

Importe o @azure/identity pacote.
Passe uma instância apropriada TokenCredential para o cliente:
- Usar DefaultAzureCredential quando o aplicativo estiver em execução localmente
- Use ManagedIdentityCredential quando o aplicativo estiver em execução no Azure e configurar a ID do cliente, a ID do recurso ou a ID do objeto.

A ID do cliente é usada para identificar uma identidade gerenciada ao configurar aplicativos ou serviços que precisam ser autenticados usando essa identidade.

Recupere a ID do cliente atribuída a uma identidade gerenciada atribuída pelo usuário usando o seguinte comando:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId'

Configure ManagedIdentityCredential com o ID do cliente:

import { BlobServiceClient } from '@azure/storage-blob';
import { ManagedIdentityCredential, DefaultAzureCredential } from '@azure/identity';

function createBlobServiceClient(): BlobServiceClient {
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    if (!accountName) throw Error('Azure Storage accountName not found');
    const url = `https://${accountName}.blob.core.windows.net`;

    if (process.env.NODE_ENV === "production") {
        const clientId = process.env.AZURE_CLIENT_ID;
        if (!clientId) throw Error('AZURE_CLIENT_ID not found for Managed Identity');
        return new BlobServiceClient(url, new ManagedIdentityCredential(clientId));
    } else {
        return new BlobServiceClient(url, new DefaultAzureCredential());
    }
}

async function main(): Promise<void> {
    try {
        const blobServiceClient = createBlobServiceClient();
        const containerClient = blobServiceClient.getContainerClient(process.env.AZURE_STORAGE_CONTAINER_NAME!);
        const properties = await containerClient.getProperties();

        console.log(properties);
    } catch (err: any) {
        console.error("Error retrieving container properties:", err.message);
        throw err;
    }
}

main().catch((err: Error) => {
    console.error("Error running sample:", err.message);
    process.exit(1);
});

A ID do recurso identifica exclusivamente o recurso de identidade gerenciada em sua assinatura Azure usando a seguinte estrutura:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}

As IDs de recurso podem ser criadas por convenção, o que as torna mais convenientes ao trabalhar com um grande número de identidades gerenciadas atribuídas pelo usuário em seu ambiente.

Recupere a ID do recurso para uma identidade gerenciada atribuída pelo usuário usando o seguinte comando:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'id'

Configure ManagedIdentityCredential com a ID do recurso:

import { BlobServiceClient } from '@azure/storage-blob';
import { ManagedIdentityCredential, DefaultAzureCredential } from '@azure/identity';

function createBlobServiceClient(): BlobServiceClient {
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    if (!accountName) throw Error('Azure Storage accountName not found');
    const url = `https://${accountName}.blob.core.windows.net`;

    if (process.env.NODE_ENV === "production") {
        const resourceId = process.env.AZURE_RESOURCE_ID;
        if (!resourceId) throw Error('AZURE_RESOURCE_ID not found for Managed Identity');
        return new BlobServiceClient(url, new ManagedIdentityCredential(resourceId));
    } else {
        return new BlobServiceClient(url, new DefaultAzureCredential());
    }
}

async function main(): Promise<void> {
    try {
        const blobServiceClient = createBlobServiceClient();
        const containerClient = blobServiceClient.getContainerClient(process.env.AZURE_STORAGE_CONTAINER_NAME!);
        const properties = await containerClient.getProperties();

        console.log(properties);
    } catch (err: any) {
        console.error("Error retrieving container properties:", err.message);
        throw err;
    }
}

main().catch((err: Error) => {
    console.error("Error running sample:", err.message);
    process.exit(1);
});

Uma ID principal é outro nome para uma ID de objeto.

Recupere a ID do objeto para uma identidade gerenciada atribuída pelo usuário usando o seguinte comando:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'principalId'

Configure ManagedIdentityCredential com a ID do objeto:

import { BlobServiceClient } from '@azure/storage-blob';
import { ManagedIdentityCredential, DefaultAzureCredential } from '@azure/identity';

function createBlobServiceClient(): BlobServiceClient {
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    if (!accountName) throw Error('Azure Storage accountName not found');
    const url = `https://${accountName}.blob.core.windows.net`;

    if (process.env.NODE_ENV === "production") {
        const objectId = process.env.AZURE_OBJECT_ID;
        if (!objectId) throw Error('AZURE_OBJECT_ID not found for Managed Identity');
        return new BlobServiceClient(url, new ManagedIdentityCredential(objectId));
    } else {
        return new BlobServiceClient(url, new DefaultAzureCredential());
    }
}

async function main(): Promise<void> {
    try {
        const blobServiceClient = createBlobServiceClient();
        const containerClient = blobServiceClient.getContainerClient(process.env.AZURE_STORAGE_CONTAINER_NAME!);
        const properties = await containerClient.getProperties();

        console.log(properties);
    } catch (err: any) {
        console.error("Error retrieving container properties:", err.message);
        throw err;
    }
}

main().catch((err: Error) => {
    console.error("Error running sample:", err.message);
    process.exit(1);
});

O código anterior se comporta de forma diferente dependendo do ambiente em que está em execução:

Em sua estação de trabalho de desenvolvimento local, DefaultAzureCredential procura nas variáveis de ambiente de uma entidade de serviço de aplicativo ou em ferramentas de desenvolvedor instaladas localmente, como Visual Studio Code, para um conjunto de credenciais de desenvolvedor.
Quando implantado em Azure, ManagedIdentityCredential descobre as configurações de identidade gerenciada para se autenticar automaticamente em outros serviços.

Comentários

Esta página foi útil?

Last updated on 2026-03-11

Compartilhar via

Autenticar aplicativos JavaScript hospedados no Azure para recursos do Azure usando uma identidade gerenciada atribuída pelo usuário

Conceitos essenciais de identidade gerenciada

Criar uma identidade gerenciada atribuída ao usuário

Atribuir a identidade gerenciada ao seu aplicativo

Atribuir funções à identidade gerenciada

Autenticar nos serviços do Azure a partir do seu aplicativo

Implementar o código

Implementar o código

Comentários

Recursos adicionais