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

Artigo
09/30/2024

Observação

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

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

Para obter mais detalhes, consulte Nome do Host Padrão Exclusivo para o 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 dão suporte a cenários entre diretórios, elas não se comportarão conforme o esperado se seu aplicativo for migrado entre assinaturas ou locatários. Para recriar as identidades gerenciadas após essa movimentação, consulte 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.

Observação

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 é gerenciada pela plataforma do Azure e não exige provisionamento ou giro de nenhum segredo. Para saber mais sobre identidades gerenciadas no Microsoft Entra ID, confira Identidades gerenciadas para recursos do Azure.

Seu aplicativo pode receber dois tipos de identidades:

Uma identidade atribuída pelo sistema está vinculada ao aplicativo e será excluída se o aplicativo for excluído. Um aplicativo só pode ter 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 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 da identidade gerenciada é específica para o slot. Para configurar uma identidade gerenciada para um slot de implantação no portal, primeiro navegue até o slot. 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. Normalmente, o nome do slot é semelhante a <app-name>/slots/<slot-name>.

Esse vídeo lhe 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 pelo sistema

Acesse as configurações do aplicativo no portal do Azure no grupo Configurações no painel de navegação esquerdo.
Selecionar Identidade.
Na guia Sistema atribuído, alterne o Status para Ligado. Clique em Save (Salvar).

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

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

Para o Serviço de Aplicativo

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

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

Para o Functions

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

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

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

Qualquer recurso do tipo Microsoft.Web/sites pode ser criado com uma identidade, incluindo a propriedade a seguir 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 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. No Microsoft Entra ID, a entidade de serviço tem o mesmo nome dado à sua instância do Serviço de Aplicativo ou do Azure Functions.

Se você precisar referenciar essas propriedades em uma fase adiante no modelo, poderá fazer isso por meio da reference() função do modelo com o sinalizador '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

Criar um aplicativo com uma identidade atribuída pelo usuário exige que você crie a identidade e, em seguida, adicione seu identificador de recursos à 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.
No painel de navegação esquerdo da página do aplicativo, role para baixo até o grupo Configurações.
Selecionar Identidade.
Selecione Usuário atribuído>Adicionar.
Procure a identidade que você criou 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 comando az webapp identity assign 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

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

Para o Functions

Crie uma identidade atribuída pelo usuário.

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

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

Qualquer recurso do tipo Microsoft.Web/sites pode ser criado com uma identidade incluindo o seguinte bloco na definição do recurso, substituindo <resource-id> pelo ID do 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 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, 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 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 que é 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 as chamadas de runtime.

Configurar o recurso de destino

Talvez seja necessário configurar o recurso de destino para permitir o acesso do aplicativo ou função. Por exemplo, se você solicitar um token para acessar o Key Vault, também precisará adicionar uma política de acesso que inclua a identidade gerenciada de seu aplicativo ou função. Caso contrário, as chamadas para o Key Vault serão rejeitadas, mesmo se você usar um token válido. O mesmo é verdadeiro para Banco de Dados SQL do Azure. 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.

Importante

Os serviços de back-end para identidades gerenciadas mantêm um cache por URI de recurso por cerca de 24 horas. Isso significa que 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 o token de uma identidade gerenciada a ser atualizado antes da expiração. Se você alterar a associação de grupo ou de função de uma identidade gerenciada para adicionar ou remover permissões, poderá ser 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 pelo Microsoft Entra ID, como o Banco de Dados SQL do Azure, o Azure Key Vault e o Armazenamento do Microsoft Azure. Esses tokens representam o acesso do aplicativo ao recurso e não um 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. 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 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.

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 seguinte:

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, você adicionará então o valor de access_token a uma conexão de cliente com o cofre.

Observação

Ao se conectar a fontes de dados do SQL do Azure com o Entity Framework Core, considere usar o Microsoft.Data.SqlClient, que fornece cadeias de conexão especiais para conectividade de identidade gerenciada. Por exemplo, confira o Tutorial: Proteger a conexão do Banco de Dados SQL do Azure no 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 uma orientação detalhada, consulte o tutorial: Conectar-se aos bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Consulte os respectivos títulos de documentação da biblioteca de clientes para obter informações:

Os exemplos vinculados usam DefaultAzureCredential. Isso é útil para a maioria dos cenários porque o mesmo padrão funciona no Azure (com identidades gerenciadas) e no computador 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 clientes de Identidade do Azure para JavaScript. Para uma orientação detalhada, consulte o tutorial: Conectar-se aos bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Consulte os respectivos títulos de documentação da biblioteca de clientes para obter informações:

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

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 uma orientação detalhada, consulte o tutorial: Conectar-se aos bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Consulte os respectivos títulos de documentação da biblioteca de clientes 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 clientes de Identidade do Azure para Java. Para uma orientação detalhada, consulte o tutorial: Conectar-se aos bancos de dados do Azure do Serviço de Aplicativo sem segredos usando uma identidade gerenciada.

Consulte os respectivos títulos de documentação da biblioteca de clientes para obter informações:

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

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://<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, confira referência de ponto de extremidade REST.

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.

No painel de navegação esquerdo da página do aplicativo, role para baixo até o grupo Configurações.
Selecionar Identidade. Em seguida, siga as etapas com base no tipo de identidade:
- Identidade atribuída pelo sistema: na guia Atribuída pelo sistema, alterne Status para Desativado. Clique em Salvar.
- 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.

Para remover a identidade atribuída pelo 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 pelo sistema especificando [system] em --identities.

Para o Serviço de Aplicativo

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

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

Para o Functions

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 do ARM:

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

Observação

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 em vigor e as ferramentas ainda mostrarão a identidade gerenciada como "ativada" ou "habilitada". Como resultado, o uso dessa configuração não é recomendado.

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 usado para ajudar a reduzir os ataques de falsificação da solicitação do lado do servidor (SSRF). O valor é trocado pela plataforma.

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

Nome do parâmetro No Descrição

recurso Query O URI do recurso do Microsoft Entra do recurso para o qual um token deve ser obtido. 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 reduzir os ataques de falsificação da solicitação do lado do servidor (SSRF).

client_id Consulta (Opcional) A ID da identidade atribuída pelo usuário a ser usada. Não pode ser usada em uma solicitação que inclui 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. object_id é um alias que pode ser usado no lugar dela. Não pode ser usada em uma solicitação que inclui client_id, mi_res_id ou 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. Não pode ser usada em uma solicitação que inclui 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.

Nome do parâmetro	No	Descrição
recurso	Query	O URI do recurso do Microsoft Entra do recurso para o qual um token deve ser obtido. 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 reduzir os ataques de falsificação da solicitação do lado do servidor (SSRF).
client_id	Consulta	(Opcional) A ID da identidade atribuída pelo usuário a ser usada. Não pode ser usada em uma solicitação que inclui `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, 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. `object_id` é um alias que pode ser usado no lugar dela. Não pode ser usada em uma solicitação que inclui 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, 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. Não pode ser usada em uma solicitação que inclui `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, será usada a identidade atribuída pelo sistema.

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 pelo sistema, que pode ou não existir.

Compartilhar via

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

Adicionar uma identidade atribuída pelo sistema

Para o Serviço de Aplicativo

Para o Functions

Adicionar uma identidade atribuída pelo usuário

Para o Serviço de Aplicativo

Para o Functions

Configurar o 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 o Functions

Referência de ponto de extremidade REST

Próximas etapas

Comentários

Recursos adicionais