Usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions

Este artigo mostra como criar uma identidade gerenciada para aplicativos do Serviço de Aplicativo do Azure e do Azure Functions e como usá-la para acessar outros recursos.

Uma identidade gerenciada da ID do Microsoft Entra permite que seu aplicativo acesse facilmente outros recursos protegidos pelo Microsoft Entra, como o Azure Key Vault. A plataforma do Azure gerencia a identidade, portanto, você não precisa provisionar nem atualizar segredos. Para obter mais informações sobre identidades gerenciadas na ID do Microsoft Entra, consulte Identidades gerenciadas para recursos do Azure.

Você pode conceder dois tipos de identidades ao seu aplicativo:

• Uma identidade atribuída pelo sistema está vinculada ao aplicativo e será excluída se o aplicativo for excluído. Um aplicativo pode ter apenas uma identidade atribuída pelo sistema.
• Uma identidade atribuída pelo usuário é um recurso independente do Azure que pode ser atribuído ao seu aplicativo. Um aplicativo pode ter várias identidades atribuídas pelo usuário. Uma identidade atribuída pelo usuário pode ser atribuída a vários recursos do Azure, como dois aplicativos do Serviço de Aplicativo.

A configuração da identidade gerenciada é específica para o slot. Para configurar uma identidade gerenciada para um slot de implantação no portal, vá para o slot primeiro. Para encontrar a identidade gerenciada para o aplicativo Web ou slot de implantação no locatário do Microsoft Entra a partir do portal do Azure, procure-a diretamente na página de Visão geral do locatário.

Observação

As identidades gerenciadas não estão disponíveis para aplicativos implantados no Azure Arc.

Como as identidades gerenciadas não dão suporte a cenários entre diretórios, elas não se comportam conforme o esperado se o aplicativo for migrado entre assinaturas ou locatários. Para recriar as identidades gerenciadas após essa movimentação, consulte Se as identidades gerenciadas serão recriadas automaticamente se eu mover uma assinatura para outro diretório?. Os recursos de downstream também precisarão ter políticas de acesso atualizadas para usar a nova identidade.

Pré-requisitos

Para executar as etapas neste artigo, você deve ter um conjunto mínimo de permissões sobre seus recursos do Azure. As permissões específicas de que você precisa variam de acordo com seu cenário. A tabela a seguir resume os cenários mais comuns:

Cenário	Permissão necessária	Exemplo de funções internas
Criar uma identidade atribuída pelo sistema	Microsoft.Web/sites/write sobre o aplicativo, ou Microsoft.Web/sites/slots/write sobre o slot	Colaborador do Site
Criar uma identidade atribuída pelo usuário	Microsoft.ManagedIdentity/userAssignedIdentities/write sobre o grupo de recursos no qual criar a identidade	Colaborador de Identidade Gerenciada
Atribuir uma identidade atribuída pelo usuário ao seu aplicativo	Microsoft.Web/sites/write sobre o aplicativo, Microsoft.Web/sites/slots/write sobre o slot ou Microsoft.ManagedIdentity/userAssignedIdentities/*/assign/action sobre a identidade	Colaborador do site e Operador de Identidade Gerenciada
Criar atribuições de função do Azure	Microsoft.Authorization/roleAssignments/write sobre o escopo do recurso de destino	Administrador de Controle de Acesso Baseado em Função ou Administrador de Acesso do Usuário

Adicionar uma identidade atribuída pelo sistema

Para habilitar uma identidade gerenciada atribuída pelo sistema, use as instruções a seguir.

Portal do Azure

1. No portal do Azure, vá para a página do aplicativo.

2. No menu à esquerda, selecione Configurações>Identidade.

3. Na guia Sistema atribuído, alterne o Status para Ativado. Em seguida, selecione Salvar.

CLI do Azure

Executar o comando az webapp identity assign:

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

PowerShell do Azure

Para o Serviço de Aplicativo

Executar o comando Set-AzWebApp -AssignIdentity:

Set-AzWebApp -AssignIdentity $true -ResourceGroupName <group-name>  -Name <app-name>

Para o Functions

Executar o comando Update-AzFunctionApp -IdentityType:

Update-AzFunctionApp -ResourceGroupName <group-name> -Name <function-app-name>  -IdentityType SystemAssigned

Modelo de ARM

Você pode usar um modelo do Azure Resource Manager para automatizar a implantação de seus recursos do Azure. Para saber mais, confira Automatizar a implantação de recursos no Serviço de Aplicativo e automatizar a implantação de recursos no Azure Functions.

Você pode criar qualquer recurso do tipo Microsoft.Web/sites com uma identidade, incluindo a seguinte propriedade na definição de recurso:

"identity": {
    "type": "SystemAssigned"
}

Adicionar o tipo atribuído pelo sistema diz ao Azure para criar e gerenciar a identidade do seu aplicativo.

Por exemplo, um modelo de aplicativo Web pode ser semelhante ao seguinte JSON:

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "SystemAssigned"
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
    ]
}

Quando o site é criado, ele inclui as seguintes propriedades:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<tenant-id>",
    "principalId": "<principal-id>"
}

A propriedade tenantId identifica a qual locatário do Microsoft Entra a identidade pertence. A principalId propriedade é um identificador exclusivo para a nova identidade do aplicativo. No Microsoft Entra ID, o principal de serviço tem o mesmo nome que você deu ao seu Serviço de Aplicativo ou à instância do Azure Functions.

Se você precisar consultar essas propriedades em um estágio posterior no modelo, use a reference() função de modelo com a opção 'Full' , como neste exemplo:

{
    "tenantId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.tenantId]",
    "objectId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.principalId]",
}

Adicionar uma identidade atribuída pelo usuário

Para criar um aplicativo com uma identidade atribuída pelo usuário, crie a identidade e adicione seu identificador de recurso à configuração do aplicativo.

Portal do Azure

1. Crie um recurso de identidade gerenciado atribuído pelo usuário de acordo com estas instruções.

2. No menu à esquerda da página do aplicativo, selecione Configurações>Identidade.

3. Selecione Usuário atribuído e, em seguida, selecione Adicionar.

4. Pesquise a identidade que você criou anteriormente, selecione-a e selecione Adicionar.

Depois de concluir essas etapas, o aplicativo será reiniciado.

CLI do Azure

1. Crie uma identidade atribuída pelo usuário:

   az identity create --resource-group <group-name> --name <identity-name>
   

2. Execute o az webapp identity assign comando para atribuir a identidade ao aplicativo:

   az webapp identity assign --resource-group <group-name> --name <app-name> --identities <identity-id>
   

PowerShell do Azure

Para o Serviço de Aplicativo

No momento, não há suporte para a adição de uma identidade atribuída pelo usuário no Serviço de Aplicativo usando o Azure PowerShell.

Para o Functions

1. Crie uma identidade atribuída pelo usuário:

   Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
   $userAssignedIdentity = New-AzUserAssignedIdentity -Name <identity-name> -ResourceGroupName <group-name> -Location <region>
   

2. Execute o comando Update-AzFunctionApp -IdentityType UserAssigned -IdentityId para atribuir a identidade no Functions:

   Update-AzFunctionApp -Name <app-name> -ResourceGroupName <group-name> -IdentityType UserAssigned -IdentityId $userAssignedIdentity.Id
   

Modelo de ARM

Você pode usar um modelo do Azure Resource Manager para automatizar a implantação de seus recursos do Azure. Para saber mais, confira Automatizar a implantação de recursos no Serviço de Aplicativo e automatizar a implantação de recursos no Azure Functions.

Você pode criar qualquer recurso do tipo Microsoft.Web/sites com uma identidade, incluindo o seguinte bloco na definição de recurso. Substitua <resource-id> pela ID de recurso da identidade desejada.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {}
    }
}

Observação

Um aplicativo pode ter identidades atribuídas pelo sistema e atribuídas pelo usuário ao mesmo tempo. Nesse caso, a type propriedade é SystemAssigned,UserAssigned.

Adicionar o tipo atribuído pelo usuário instrui o Azure a usar a identidade atribuída pelo usuário que você especificou para a sua aplicação.

Por exemplo, um modelo de aplicativo Web pode ser semelhante ao seguinte JSON:

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
        }
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
    ]
}

Quando o site é criado, ele inclui as seguintes propriedades:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {
            "principalId": "<principal-id>",
            "clientId": "<client-id>"
        }
    }
}

O propriedade principalId é um identificador exclusivo para a identidade que é usada para a administração do Microsoft Entra. A clientId propriedade é um identificador exclusivo para a nova identidade do aplicativo. Use-a para especificar qual identidade usar durante chamadas de runtime.

Configurar o recurso de destino

Você precisa configurar o recurso de destino para permitir o acesso do seu aplicativo. Para a maioria dos serviços do Azure, você configura o recurso de destino criando uma atribuição de função.

Alguns serviços usam mecanismos diferentes do controle de acesso baseado em função do Azure. Para entender como configurar o acesso usando uma identidade, consulte a documentação de cada recurso de destino. Para saber mais sobre quais recursos dão suporte a tokens do Microsoft Entra, consulte os Serviços do Azure que dão suporte à autenticação do Microsoft Entra.

Por exemplo, se você solicitar um token para acessar um segredo no Azure Key Vault, também deverá criar uma atribuição de função que permita que a identidade gerenciada trabalhe com segredos no cofre de destino. Caso contrário, o Key Vault rejeitará suas chamadas mesmo se você usar um token válido. O mesmo vale para o Banco de Dados SQL do Azure e outros serviços.

Importante

Os serviços de back-end para identidades gerenciadas mantêm um cache por URI de recurso por cerca de 24 horas. Pode levar várias horas para que as alterações em uma associação de grupo ou de função de uma identidade gerenciada entrem em vigor. No momento, não é possível forçar a atualização do token de uma identidade gerenciada antes de sua expiração. Se você alterar o grupo ou a associação de função de uma identidade gerenciada para adicionar ou remover permissões, talvez seja necessário aguardar várias horas para que o recurso do Azure que está usando a identidade tenha o acesso correto.

Para obter alternativas a grupos ou associações de função, consulte Limitação do uso de identidades gerenciadas para autorização.

Conectar-se aos serviços do Azure no código do aplicativo

Com sua identidade gerenciada, um aplicativo pode obter tokens para recursos do Azure que a ID do Microsoft Entra ajuda a proteger, como o Banco de Dados SQL do Azure, o Azure Key Vault e o Armazenamento do Azure. Esses tokens representam o aplicativo que acessa o recurso e não qualquer usuário específico do aplicativo.

O Serviço de Aplicativo e o Azure Functions fornecem um ponto de extremidade REST acessível internamente para recuperação de token. Você pode acessar o ponto de extremidade REST de dentro do aplicativo usando uma solicitação HTTP GET padrão. Você pode implementar a solicitação com um cliente HTTP genérico em cada idioma.

Para .NET, JavaScript, Java e Python, a biblioteca de clientes da Identidade do Azure fornece uma abstração desse ponto de extremidade REST e simplifica a experiência de desenvolvimento. Conectar-se a outros serviços do Azure é tão simples quanto adicionar um objeto de credencial ao cliente específico a um serviço.

HTTP GET

Uma solicitação HTTP GET bruta usa as duas variáveis de ambiente fornecidas e se parece com o seguinte exemplo:

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: <ip-address-:-port-in-IDENTITY_ENDPOINT>
X-IDENTITY-HEADER: <value-of-IDENTITY_HEADER>

Uma resposta de exemplo pode ser semelhante ao exemplo a seguir:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi…",
    "expires_on": "1586984735",
    "resource": "https://vault.azure.net",
    "token_type": "Bearer",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

Essa resposta é igual à resposta para a solicitação de token de acesso de serviço a serviço do Microsoft Entra. Para acessar o Key Vault, adicione o valor de access_token a uma conexão de cliente com o cofre.

.REDE

Observação

Quando você se conectar a fontes de dados SQL do Azure usando o Entity Framework Core, considere usar Microsoft.Data.SqlClient. Esse namespace fornece cadeias de conexão especiais para conectividade de identidade gerenciada. Para obter um exemplo, consulte Tutorial: Proteger uma conexão do Banco de Dados SQL do Azure do Serviço de Aplicativo usando uma identidade gerenciada.

Para aplicativos e funções .NET, a maneira mais simples de trabalhar com uma identidade gerenciada é por meio da biblioteca de clientes de Identidade do Azure para .NET. Para obter mais informações, consulte Tutorial: Conectar-se a bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Para obter mais informações, consulte os respectivos títulos de documentação da biblioteca de clientes:

• Adicionar a biblioteca de clientes da Identidade do Azure ao seu projeto
• Acessar um serviço do Azure usando uma identidade atribuída pelo sistema
• Acessar um serviço do Azure usando uma identidade atribuída pelo usuário

Os exemplos vinculados usam DefaultAzureCredential. O mesmo padrão funciona no Azure com identidades gerenciadas e em seu computador local sem identidades gerenciadas.

JavaScript

Para aplicativos Node.js e funções JavaScript, a maneira mais simples de trabalhar com uma identidade gerenciada é por meio da biblioteca de clientes de Identidade do Azure para JavaScript. Para obter mais informações, consulte Tutorial: Conectar-se a bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Para obter mais informações, consulte os respectivos títulos de documentação da biblioteca de clientes:

• Adicionar uma biblioteca de clientes do Azure Identity ao seu projeto
• Acessar um serviço do Azure usando uma identidade atribuída pelo sistema
• Acessar um serviço do Azure usando uma identidade atribuída pelo usuário

Os exemplos vinculados usam DefaultAzureCredential. O mesmo padrão funciona no Azure com identidades gerenciadas e em seu computador local sem identidades gerenciadas.

Para obter mais exemplos de código da biblioteca de clientes de Identidade do Azure para JavaScript, confira os exemplos de Identidade do Azure.

Pitão

Para aplicativos e funções do Python, a maneira mais simples de trabalhar com uma identidade gerenciada é por meio da biblioteca de clientes de Identidade do Azure para Python. Para obter mais informações, consulte Tutorial: Conectar-se a bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Para obter mais informações, consulte os respectivos títulos de documentação da biblioteca de clientes:

• Adicionar uma biblioteca de clientes do Azure Identity ao seu projeto
• Acessar um serviço do Azure usando uma identidade atribuída pelo sistema
• Acessar um serviço do Azure usando uma identidade atribuída pelo usuário

Os exemplos vinculados usam DefaultAzureCredential. O mesmo padrão funciona no Azure com identidades gerenciadas e em seu computador local sem identidades gerenciadas.

Java

Para aplicativos e funções Java, a maneira mais simples de trabalhar com uma identidade gerenciada é por meio da biblioteca de clientes de Identidade do Azure para Java. Para obter mais informações, consulte Tutorial: Conectar-se a bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Para obter mais informações, consulte os respectivos títulos de documentação da biblioteca de clientes:

• Adicionar uma biblioteca de clientes do Azure Identity ao seu projeto
• Acessar um serviço do Azure usando uma identidade atribuída pelo sistema
• Acessar um serviço do Azure usando uma identidade atribuída pelo usuário

Os exemplos vinculados usam DefaultAzureCredential. O mesmo padrão funciona no Azure com identidades gerenciadas e em seu computador local sem identidades gerenciadas.

Para obter mais exemplos de código da biblioteca de clientes da Identidade do Azure para Java, consulte exemplos de Identidade do Azure.

PowerShell

Use o seguinte script para recuperar um token do ponto de extremidade local especificando um URI de recurso de um serviço do Azure:

$resourceURI = "https://<Entra-resource-URI-for-resource-to-obtain-token>"
$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"
$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI
$accessToken = $tokenResponse.access_token

Para obter mais informações sobre o ponto de extremidade REST, consulte a referência de ponto de extremidade REST mais adiante neste artigo.

Remover uma identidade

Ao remover uma identidade atribuída pelo sistema, ela é excluída do Microsoft Entra ID. As identidades atribuídas pelo sistema também são removidas automaticamente do Microsoft Entra ID ao excluir o próprio recurso do aplicativo.

Portal do Azure

1. No menu à esquerda da página do aplicativo, selecione Configurações>Identidade.

2. Siga as etapas com base no tipo de identidade:

   • Para uma identidade atribuída pelo sistema: na guia Atribuída pelo sistema , alterne o Status para Desativado. Em seguida, selecione Salvar.
   • Para uma identidade atribuída pelo usuário: selecione a guia Atribuída pelo usuário , marque a caixa de seleção da identidade e selecione Remover. Clique em Sim para confirmar.

CLI do Azure

Para remover a identidade atribuída pelo sistema, use este comando:

az webapp identity remove --resource-group <group-name> --name <app-name>

Para remover uma ou mais identidades atribuídas pelo usuário, use este comando:

az webapp identity remove --resource-group <group-name> --name <app-name> --identities <identity-id1> <identity-id2> ...

Você também pode remover a identidade atribuída pelo sistema especificando [system] em --identities.

PowerShell do Azure

Para o Serviço de Aplicativo

Para remover uma identidade atribuída pelo sistema para o Serviço de Aplicativo, execute o Set-AzWebApp -AssignIdentity comando:

Set-AzWebApp -AssignIdentity $false -Name <app-name> -ResourceGroupName <group-name> 

Para o Functions

Para remover todas as identidades no Azure PowerShell (somente no Azure Functions), execute este comando:

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name <function-app-name> -ResourceGroupName <group-name> -IdentityType None

Modelo de ARM

Para remover todas as identidades em um modelo do ARM, use este código:

"identity": {
    "type": "None"
}

Observação

Você também pode definir uma configuração de aplicativo que desabilita apenas o serviço de token local: WEBSITE_DISABLE_MSI. No entanto, ela mantém a identidade intacta. As ferramentas ainda mostram a identidade gerenciada como ativada ou habilitada. Como resultado, não recomendamos que você use essa configuração.

Referência de ponto de extremidade REST

Um aplicativo com uma identidade gerenciada torna esse ponto de extremidade disponível definindo duas variáveis de ambiente:

• IDENTITY_ENDPOINT: a URL para o serviço de token local.
• IDENTITY_HEADER: Um cabeçalho que pode ajudar a mitigar ataques de falsificação de requisição do lado do servidor (SSRF). A plataforma gira o valor.

A IDENTITY_ENDPOINT variável é uma URL local da qual seu aplicativo pode solicitar tokens. Para obter um token para um recurso, faça uma solicitação HTTP GET para esse endpoint. Inclua os seguintes parâmetros:

Nome do parâmetro	No	Descrição
resource	Consulta	O URI do recurso do Microsoft Entra do recurso para o qual um token deve ser obtido. Esse recurso pode ser um dos serviços do Azure que dão suporte à autenticação do Microsoft Entra ou a qualquer outro URI de recurso.
api-version	Consulta	A versão da API do token a ser usada. Use 2019-08-01.
X-IDENTITY-HEADER	Cabeçalho	O valor da variável de ambiente IDENTITY_HEADER. Esse cabeçalho é usado para ajudar a atenuar ataques SSRF.
client_id	Consulta	(Opcional) A ID da identidade atribuída pelo usuário a ser usada. Ele não pode ser usado em uma solicitação que inclua principal_id, mi_res_idou object_id. Se todos os parâmetros de ID (client_id, principal_id, object_ide mi_res_id) forem omitidos, será usada a identidade atribuída pelo sistema.
principal_id	Consulta	(Opcional) A ID principal da identidade atribuída pelo usuário a ser usada. O object_id parâmetro é um alias que pode ser usado em vez disso. Ele não pode ser usado em uma solicitação que inclua client_id, mi_res_idou object_id. Se todos os parâmetros de ID (client_id, principal_id, object_ide mi_res_id) forem omitidos, será usada a identidade atribuída pelo sistema.
mi_res_id	Consulta	(Opcional) A ID do recurso do Azure da identidade atribuída pelo usuário a ser usada. Ele não pode ser usado em uma solicitação que inclua principal_id, client_idou object_id. Se todos os parâmetros de ID (client_id, principal_id, object_ide mi_res_id) forem omitidos, será usada a identidade atribuída pelo sistema.

Importante

Se você estiver tentando obter tokens para identidades atribuídas pelo usuário, inclua uma das propriedades opcionais. Caso contrário, o serviço de token tenta obter um token para uma identidade atribuída pelo sistema, que pode ou não existir.

Conteúdo relacionado

Considere os seguintes tutoriais:

• Conectar-se ao Banco de Dados SQL do Serviço de Aplicativo .NET sem segredos usando uma identidade gerenciada
• Acessar os serviços do Azure de um aplicativo Web .NET
• Acessar o Microsoft Graph de um aplicativo .NET protegido como o aplicativo
• Conexão Segura do Serviço Cognitivo do Serviço de Aplicativo .NET usando o Key Vault