Como usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions

Artigo
09/30/2024

Nota

A partir de 1º de junho de 2024, todos os aplicativos do Serviço de Aplicativo recém-criados terão a opção de gerar um nome de host padrão exclusivo usando a convenção <app-name>-<random-hash>.<region>.azurewebsites.netde nomenclatura. Os nomes de aplicativos existentes permanecerão inalterados.

Exemplo: myapp-ds27dh7271aah175.westus-01.azurewebsites.net

Para obter mais detalhes, consulte Nome de host padrão exclusivo para recurso do Serviço de Aplicativo.

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

Importante

Como as identidades gerenciadas não oferecem suporte a cenários entre diretórios, elas não se comportarão como esperado se seu aplicativo for migrado entre assinaturas ou locatários. Para recriar as identidades gerenciadas após essa mudança, consulte As identidades gerenciadas serão recriadas automaticamente se eu mover uma assinatura para outro diretório?. Os recursos a jusante também precisam de ter as políticas de acesso atualizadas para utilizar a nova identidade.

Nota

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

Uma identidade gerenciada do Microsoft Entra ID permite que seu aplicativo acesse facilmente outros recursos protegidos pelo Microsoft Entra, como o Azure Key Vault. A identidade é gerida pela plataforma do Azure e não precisa de aprovisionar nem rodar segredos. Para obter mais informações sobre identidades gerenciadas no Microsoft Entra ID, consulte Identidades gerenciadas para recursos do Azure.

Pode conceder dois tipos de identidades à aplicação:

Uma identidade atribuída ao sistema é vinculada ao aplicativo e é excluída se o aplicativo for excluído. Uma aplicação só pode ter uma identidade atribuída pelo sistema.
Uma identidade atribuída pelo utilizador é um recurso autónomo do Azure que pode ser atribuído à aplicação. Um aplicativo pode ter várias identidades atribuídas pelo usuário e 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 de identidade gerenciada é específica para o slot. Para configurar uma identidade gerenciada para um slot de implantação no portal, navegue primeiro até o slot. Para localizar a identidade gerenciada para seu aplicativo Web ou slot de implantação em seu locatário do Microsoft Entra no portal do Azure, pesquise-a diretamente na página Visão geral do seu locatário. Normalmente, o nome do slot é semelhante ao <app-name>/slots/<slot-name>.

Este vídeo mostra como usar identidades gerenciadas para o Serviço de Aplicativo.

As etapas no vídeo também são descritas nas seções a seguir.

Adicionar uma identidade atribuída ao sistema

Aceda às definições da sua aplicação no portal do Azure no grupo Definições no painel de navegação esquerdo.
Selecione a Identidade.
Na guia Sistema atribuído, alterne Status para Ativado. Clique em Guardar.

Execute o comando para criar uma identidade atribuída ao az webapp identity assign sistema:

az webapp identity assign --name myApp --resource-group myResourceGroup

Para o Serviço de Aplicativo

Execute o comando para criar uma identidade atribuída ao sistema para o Set-AzWebApp -AssignIdentity Serviço de Aplicativo:

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

Para funções

Execute o comando para criar uma identidade atribuída pelo Update-AzFunctionApp -IdentityType sistema para um aplicativo de função:

Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType SystemAssigned

Um modelo do Azure Resource Manager pode ser usado para automatizar a implantação de seus recursos do Azure. Para saber mais sobre a implantação no Serviço de Aplicativo e nas Funções, consulte Automatizando a implantação de recursos no Serviço de Aplicativo e Automatizando a implantação de recursos no Azure Functions.

Qualquer recurso do tipo Microsoft.Web/sites pode ser criado com uma identidade, incluindo a seguinte propriedade na definição de recurso:

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

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

Por exemplo, o modelo de um aplicativo Web pode se parecer com o 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 tem as seguintes propriedades adicionais:

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

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

Se você precisar fazer referência a essas propriedades em um estágio posterior no modelo, poderá fazê-lo por meio da reference() função de modelo com o 'Full' sinalizador, 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

Criar um aplicativo com uma identidade atribuída pelo usuário requer que você crie a identidade e, em seguida, adicione seu identificador de recurso à configuração do aplicativo.

Primeiro, você precisará criar um recurso de identidade atribuído pelo usuário.

Crie um recurso de identidade gerenciado atribuído pelo usuário de acordo com estas instruções.
Na navegação à esquerda da página da sua aplicação, desloque-se para baixo até ao grupo Definições .
Selecione a Identidade.
Selecione Adicionar atribuído ao> usuário.
Procure a identidade criada anteriormente, selecione-a e selecione Adicionar.

Depois de selecionar Adicionar, o aplicativo é reiniciado.

Crie uma identidade atribuída pelo usuário.

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

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>

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.

Para funções

Crie uma identidade atribuída pelo usuário.

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

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

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

Qualquer recurso do tipo Microsoft.Web/sites pode ser criado com uma identidade incluindo o seguinte bloco na definição de recurso, substituindo <resource-id> pelo ID de recurso da identidade desejada:

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

Nota

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

Adicionar o tipo atribuído pelo usuário informa ao Azure para usar a identidade atribuída pelo usuário especificada para seu aplicativo.

Por exemplo, o modelo de um aplicativo Web pode se parecer com o 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 tem as seguintes propriedades adicionais:

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

O principalId é um identificador exclusivo para a identidade usada para a administração do Microsoft Entra. O clientId é um identificador exclusivo para a nova identidade do aplicativo que é usado para especificar qual identidade usar durante chamadas de tempo de execução.

Configurar recurso de destino

Talvez seja necessário configurar o recurso de destino para permitir o acesso a partir do seu aplicativo ou função. Por exemplo, se você solicitar um token para acessar o Cofre da Chave, também deverá adicionar uma política de acesso que inclua a identidade gerenciada do seu aplicativo ou função. Caso contrário, suas chamadas para o Cofre da Chave serão rejeitadas, mesmo se você usar um token válido. O mesmo é verdadeiro para o Banco de Dados SQL do Azure. Para saber mais sobre quais recursos oferecem suporte a tokens do Microsoft Entra, consulte Serviços do Azure que oferecem suporte à autenticação do Microsoft Entra.

Importante

Os serviços back-end para identidades geridas mantêm um cache por URI de recurso durante cerca de 24 horas. Isso significa que pode levar várias horas para que as alterações no grupo ou associação de função de uma identidade gerenciada entrem em vigor. Hoje, não é possível forçar o token de uma identidade gerenciada a ser atualizado antes de seu vencimento. Se você alterar a associação de grupo ou 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 usa 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 são protegidos pela ID do Microsoft Entra, como o Banco de Dados SQL do Azure, o Cofre da Chave do Azure 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 tokens. O ponto de extremidade REST pode ser acessado de dentro do aplicativo com um HTTP GET padrão, que pode ser implementado com um cliente HTTP genérico em todos os idiomas. Para .NET, JavaScript, Java e Python, a biblioteca de cliente do Azure Identity fornece uma abstração sobre esse 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 do serviço.

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

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>

E uma resposta de exemplo pode ter a seguinte aparência:

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 é a mesma que a resposta para a solicitação de token de acesso de serviço a serviço do Microsoft Entra. Para acessar o Cofre da Chave, você adicionará o valor de uma conexão de access_token cliente com o cofre.

Nota

Ao conectar-se a fontes de dados SQL do Azure com o Entity Framework Core, considere usar Microsoft.Data.SqlClient, que fornece cadeias de conexão especiais para conectividade de identidade gerenciada. Para obter um exemplo, consulte Tutorial: Proteger a 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 cliente do Azure Identity para .NET. Para obter orientações detalhadas, consulte Tutorial: Conectar-se a bancos de dados do Azure a partir do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Consulte os respetivos títulos de documentação da biblioteca do cliente para obter informações:

Os exemplos vinculados usam DefaultAzureCredential. É útil para a maioria dos cenários porque o mesmo padrão funciona no Azure (com identidades gerenciadas) e em sua máquina local (sem identidades gerenciadas).

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

Consulte os respetivos títulos de documentação da biblioteca do cliente para obter informações:

Para obter mais exemplos de código da biblioteca de cliente do Azure Identity para JavaScript, consulte Exemplos do Azure Identity.

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

Consulte os respetivos títulos de documentação da biblioteca do cliente para obter informações:

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

Consulte os respetivos títulos de documentação da biblioteca do cliente para obter informações:

Para obter mais exemplos de código da biblioteca de cliente do Azure Identity para Java, consulte Exemplos de identidade do Azure.

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

$resourceURI = "https://<AAD-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 Referência do ponto de extremidade REST.

Remover uma identidade

Quando você remove uma identidade atribuída ao sistema, ela é excluída da ID do Microsoft Entra. As identidades atribuídas ao sistema também são removidas automaticamente do Microsoft Entra ID quando você exclui o próprio recurso do aplicativo.

Na navegação à esquerda da página da sua aplicação, desloque-se para baixo até ao grupo Definições .
Selecione a Identidade. Em seguida, siga as etapas com base no tipo de identidade:
- Identidade atribuída ao sistema: na guia Sistema atribuído, alterne Status para Desativado. Clique em Guardar.
- Identidade atribuída pelo usuário: selecione a guia Usuário atribuído , marque a caixa de seleção da identidade e selecione Remover. Selecione Sim para confirmar.

Para remover a identidade atribuída ao sistema:

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

Para remover uma ou mais identidades atribuídas pelo usuário:

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

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

Para o Serviço de Aplicativo

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

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

Para funções

Para remover todas as identidades no Azure PowerShell (somente Azure Functions):

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType None

Para remover todas as identidades em um modelo ARM:

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

Nota

Há também uma configuração de aplicativo que pode ser definida, WEBSITE_DISABLE_MSI, que apenas desativa o serviço de token local. No entanto, ele deixa a identidade no lugar e as ferramentas ainda mostrarão a identidade gerenciada como "on" ou "enabled". Como resultado, o uso dessa configuração não é recomendado.

Referência do ponto de extremidade REST

Um aplicativo com uma identidade gerenciada disponibiliza esse ponto de extremidade definindo duas variáveis de ambiente:

IDENTITY_ENDPOINT - a URL para o serviço de token local.
IDENTITY_HEADER - um cabeçalho usado para ajudar a mitigar ataques de falsificação de solicitação do lado do servidor (SSRF). O valor é girado pela plataforma.

O IDENTITY_ENDPOINT é uma URL local a partir da qual seu aplicativo pode solicitar tokens. Para obter um token para um recurso, faça uma solicitação HTTP GET para esse ponto de extremidade, incluindo os seguintes parâmetros:

Nome do parâmetro Em Description

recurso Query O URI do recurso Microsoft Entra do recurso para o qual um token deve ser obtido. Este pode ser um dos serviços do Azure que suportam a autenticação do Microsoft Entra ou qualquer outro URI de recurso.

api-version Query A versão da API de token a ser usada. 2019-08-01Utilize.

CABEÇALHO DE IDENTIDADE X Cabeçalho O valor da variável de ambiente IDENTITY_HEADER. Esse cabeçalho é usado para ajudar a mitigar ataques de falsificação de solicitação do lado do servidor (SSRF).

client_id Query (Opcional) O ID do cliente da identidade atribuída pelo usuário a ser usada. 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_id, e mi_res_id) forem omitidos, a identidade atribuída ao sistema será usada.

principal_id Query (Opcional) O ID principal da identidade atribuída pelo usuário a ser usada. object_id é um alias que pode ser usado em vez disso. Não pode ser usado em uma solicitação que inclua client_id, mi_res_id ou object_id. Se todos os parâmetros de ID (client_id, principal_id, object_id, e mi_res_id) forem omitidos, a identidade atribuída ao sistema será usada.

mi_res_id Query (Opcional) A ID de recurso do Azure da identidade atribuída pelo usuário a ser usada. 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_id, e mi_res_id) forem omitidos, a identidade atribuída ao sistema será usada.

Nome do parâmetro	Em	Description
recurso	Query	O URI do recurso Microsoft Entra do recurso para o qual um token deve ser obtido. Este pode ser um dos serviços do Azure que suportam a autenticação do Microsoft Entra ou qualquer outro URI de recurso.
api-version	Query	A versão da API de token a ser usada. `2019-08-01`Utilize.
CABEÇALHO DE IDENTIDADE X	Cabeçalho	O valor da variável de ambiente IDENTITY_HEADER. Esse cabeçalho é usado para ajudar a mitigar ataques de falsificação de solicitação do lado do servidor (SSRF).
client_id	Query	(Opcional) O ID do cliente da identidade atribuída pelo usuário a ser usada. Não pode ser usado em uma solicitação que inclua `principal_id`, `mi_res_id`ou `object_id`. Se todos os parâmetros de ID (`client_id`, `principal_id`, `object_id`, e `mi_res_id`) forem omitidos, a identidade atribuída ao sistema será usada.
principal_id	Query	(Opcional) O ID principal da identidade atribuída pelo usuário a ser usada. `object_id` é um alias que pode ser usado em vez disso. Não pode ser usado em uma solicitação que inclua client_id, mi_res_id ou object_id. Se todos os parâmetros de ID (`client_id`, `principal_id`, `object_id`, e `mi_res_id`) forem omitidos, a identidade atribuída ao sistema será usada.
mi_res_id	Query	(Opcional) A ID de recurso do Azure da identidade atribuída pelo usuário a ser usada. Não pode ser usado em uma solicitação que inclua `principal_id`, `client_id`ou `object_id`. Se todos os parâmetros de ID (`client_id`, `principal_id`, `object_id`, e `mi_res_id`) forem omitidos, a identidade atribuída ao sistema será usada.

Importante

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

Partilhar via

Como usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions

Adicionar uma identidade atribuída ao sistema

Para o Serviço de Aplicativo

Para funções

Adicionar uma identidade atribuída pelo usuário

Para o Serviço de Aplicativo

Para funções

Configurar recurso de destino

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

Remover uma identidade

Para o Serviço de Aplicativo

Para funções

Referência do ponto de extremidade REST

Próximos passos

Comentários

Recursos adicionais