Usar identidades gerenciadas no Gerenciamento de API do Azure

APLICA-SE A: Todas as camadas de gerenciamento de API

Este artigo mostra como criar uma identidade gerenciada para uma instância de Gerenciamento de API do Azure e como usá-la para acessar outros recursos. Uma identidade gerenciada gerada pelo Microsoft Entra ID permite que sua instância de Gerenciamento de API acesse com facilidade e segurança outros recursos protegidos pelo Microsoft Entra, como o Azure Key Vault. O Azure gere esta identidade, pelo que não tem de aprovisionar nem rodar segredos. Para obter mais informações sobre identidades gerenciadas, consulte O que são identidades gerenciadas para recursos do Azure?.

Pode conceder dois tipos de identidades a uma instância de Gestão de API:

  • Uma identidade atribuída pelo sistema está associada ao serviço e será eliminada se o serviço for eliminado. O serviç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 ao serviço. O serviço pode ter várias identidades atribuídas pelo utilizador.

Nota

As identidades gerenciadas são específicas do locatário do Microsoft Entra onde sua assinatura do Azure está hospedada. Eles não são atualizados se uma assinatura for movida para um diretório diferente. Se uma assinatura for movida, você precisará recriar e configurar as identidades.

Criar uma identidade gerenciada atribuída ao sistema

Portal do Azure

Para configurar uma identidade gerenciada no portal do Azure, você primeiro criará uma instância de Gerenciamento de API e, em seguida, habilitará o recurso.

  1. Crie uma instância de Gerenciamento de API no portal como faria normalmente. Navegue até ele no portal.

  2. No menu à esquerda, em Segurança, selecione Identidades gerenciadas.

  3. Na guia Sistema atribuído, alterne Status para Ativado. Selecione Guardar.

    Seleções para habilitar uma identidade gerenciada atribuída ao sistema

Azure PowerShell

Nota

Recomendamos que utilize o módulo do Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

As etapas a seguir orientam você na criação de uma instância de Gerenciamento de API e na atribuição de uma identidade a ela usando o Azure PowerShell.

  1. Se necessário, instale o Azure PowerShell usando as instruções no guia do Azure PowerShell. Em seguida, execute Connect-AzAccount para criar uma conexão com o Azure.

  2. Use o código a seguir para criar a instância com uma identidade gerenciada atribuída ao sistema. Para obter mais exemplos de como usar o Azure PowerShell com uma instância de Gerenciamento de API, consulte Exemplos do PowerShell de Gerenciamento de API.

    # Create a resource group.
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    
    # Create an API Management Consumption Sku service.
    New-AzApiManagement -ResourceGroupName $resourceGroupName -Name consumptionskuservice -Location $location -Sku Consumption -Organization contoso -AdminEmail contoso@contoso.com -SystemAssignedIdentity
    

Você também pode atualizar uma instância existente para criar a identidade:

# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName

# Update an API Management instance
Set-AzApiManagement -InputObject $apimService -SystemAssignedIdentity

Modelo Azure Resource Manager

Você pode criar uma instância de Gerenciamento de API com uma identidade atribuída ao sistema incluindo a seguinte propriedade na definição de recurso:

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

Essa propriedade informa ao Azure para criar e gerenciar a identidade para sua instância de Gerenciamento de API.

Por exemplo, um modelo completo do Azure Resource Manager pode ter a seguinte aparência:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2021-08-01",
        "name": "contoso",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {},
        "sku": {
            "name": "Developer",
            "capacity": "1"
        },
        "properties": {
            "publisherEmail": "admin@contoso.com",
            "publisherName": "Contoso"
        },
        "identity": {
            "type": "systemAssigned"
        }
    }]
}

Quando a instância é criada, ela tem as seguintes propriedades adicionais:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<TENANTID>",
    "principalId": "<PRINCIPALID>"
}

A tenantId propriedade identifica a qual locatário do Microsoft Entra a identidade pertence. A principalId propriedade é um identificador exclusivo para a nova identidade da instância. No Microsoft Entra ID, a entidade de serviço tem o mesmo nome que você deu à sua instância de Gerenciamento de API.

Nota

Uma instância de Gestão de API pode ter identidades atribuídas pelo sistema e pelo utilizador ao mesmo tempo. Neste caso, a type propriedade seria SystemAssigned,UserAssigned.

Configurar o acesso do Key Vault com uma identidade gerida

As configurações a seguir são necessárias para que o Gerenciamento de API acesse segredos e certificados de um cofre de chaves do Azure.

Configurar o acesso ao cofre de chaves

  1. No portal, navegue até o cofre das chaves.

  2. No menu à esquerda, selecione Configuração do Access e anote o modelo de permissão que está configurado.

  3. Dependendo do modelo de permissão, configure uma política de acesso ao cofre de chaves ou o acesso RBAC do Azure para uma identidade gerenciada pelo Gerenciamento de API.

    Para adicionar uma política de acesso ao cofre de chaves:

    1. No menu à esquerda, selecione Políticas de acesso.
    2. Na página Políticas de acesso , selecione + Criar.
    3. No separador Permissões, em Permissões secretas, selecione Obter e Listar e, em seguida, selecione Seguinte.
    4. No separador Principal, Selecione entidade de segurança, procure o nome do recurso da sua identidade gerida e, em seguida, selecione Seguinte. Se você estiver usando uma identidade atribuída ao sistema, o principal será o nome da sua instância de Gerenciamento de API.
    5. Selecione Avançar novamente. No separador Rever + criar, selecione Criar.

    Para configurar o acesso ao Azure RBAC:

    1. No menu à esquerda, selecione Controle de acesso (IAM).
    2. Na página Controle de acesso (IAM), selecione Adicionar atribuição de função.
    3. Na guia Função, selecione Usuário de Segredos do Cofre da Chave.
    4. Na guia Membros, selecione Identidade> gerenciada+ Selecionar membros.
    5. Na página Selecionar identidade gerenciada, selecione a identidade gerenciada atribuída ao sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância de Gerenciamento de API e selecione Selecionar.
    6. Selecione Rever + atribuir.

Requisitos para o firewall do Key Vault

Se o firewall do Cofre da Chave estiver habilitado no cofre de chaves, os seguintes requisitos são adicionais:

  • Você deve usar a identidade gerenciada atribuída pelo sistema da instância de Gerenciamento de API para acessar o cofre de chaves.

  • No firewall do Cofre de Chaves, habilite a opção Permitir que Serviços Microsoft Confiáveis ignorem esse firewall .

  • Certifique-se de que o endereço IP do cliente local tenha permissão para acessar o cofre de chaves temporariamente enquanto seleciona um certificado ou segredo para adicionar ao Gerenciamento de API do Azure. Para obter mais informações, consulte Configurar configurações de rede do Cofre da Chave do Azure.

    Depois de concluir a configuração, você pode bloquear o endereço do cliente no firewall do cofre de chaves.

Requisitos da rede virtual

Se a instância de Gerenciamento de API for implantada em uma rede virtual, defina também as seguintes configurações de rede:

Para obter detalhes, consulte Configuração de rede ao configurar o Gerenciamento de API do Azure em uma rede virtual.

Cenários suportados usando identidade atribuída pelo sistema

Obter um certificado TLS/SSL personalizado para a instância de Gestão de API do Azure Key Vault

Pode utilizar a identidade atribuída pelo sistema de uma instância de Gestão de API para obter certificados TLS/SSL personalizados armazenados no Azure Key Vault. Em seguida, você pode atribuir esses certificados a domínios personalizados na instância de Gerenciamento de API. Tenha estas considerações em mente:

  • O tipo de conteúdo do segredo deve ser application/x-pkcs12. Saiba mais sobre os requisitos de certificado de domínio personalizado.
  • Use o ponto de extremidade secreto do certificado do Cofre da Chave, que contém o segredo.

Importante

Se você não fornecer a versão objeto do certificado, o Gerenciamento de API obterá automaticamente a versão mais recente do certificado dentro de quatro horas após a atualização no Cofre da Chave.

O exemplo a seguir mostra um modelo do Azure Resource Manager que usa a identidade gerenciada atribuída pelo sistema de uma instância de serviço de Gerenciamento de API para recuperar um certificado de domínio personalizado do Cofre da Chave.

Pré-requisitos

  • Uma instância de serviço de Gerenciamento de API configurada com uma identidade gerenciada atribuída ao sistema. Para criar a instância, você pode usar um Modelo de Início Rápido do Azure.
  • Uma instância do Azure Key Vault no mesmo grupo de recursos, hospedando um certificado que será usado como um certificado de domínio personalizado no Gerenciamento de API.

O modelo a seguir contém as seguintes etapas.

  1. Atualize as políticas de acesso da instância do Azure Key Vault e permita que a instância de Gerenciamento de API obtenha segredos dela.
  2. Atualize a instância de Gerenciamento de API definindo um nome de domínio personalizado por meio do certificado da instância do Cofre de Chaves.

Ao executar o modelo, forneça valores de parâmetro apropriados para seu ambiente.

{
	"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
	"contentVersion": "1.0.0.0",
	"parameters": {
        "apiManagementServiceName": {
            "type": "string",
            "minLength": 8,
            "metadata":{
                "description": "The name of the API Management service"
            }
        },
		"publisherEmail": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The email address of the owner of the service"
			}
		},
		"publisherName": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The name of the owner of the service"
			}
		},
		"sku": {
			"type": "string",
			"allowedValues": ["Developer",
			"Standard",
			"Premium"],
			"defaultValue": "Developer",
			"metadata": {
				"description": "The pricing tier of this API Management service"
			}
		},
		"skuCount": {
			"type": "int",
			"defaultValue": 1,
			"metadata": {
				"description": "The instance size of this API Management service."
			}
		},
        "keyVaultName": {
            "type": "string",
            "metadata": {
                "description": "Name of the key vault"
            }
        },
		"proxyCustomHostname1": {
			"type": "string",
			"metadata": {
				"description": "Gateway custom hostname 1. Example: api.contoso.com"
			}
		},
		"keyVaultIdToCertificate": {
			"type": "string",
			"metadata": {
				"description": "Reference to the key vault certificate. Example: https://contoso.vault.azure.net/secrets/contosogatewaycertificate"
			}
		}
	},
	 "variables": {
        "apimServiceIdentityResourceId": "[concat(resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName')),'/providers/Microsoft.ManagedIdentity/Identities/default')]"
		    },
	"resources": [ 
   {
        "apiVersion": "2021-08-01",
        "name": "[parameters('apiManagementServiceName')]",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {
        },
        "sku": {
            "name": "[parameters('sku')]",
            "capacity": "[parameters('skuCount')]"
        },
        "properties": {
            "publisherEmail": "[parameters('publisherEmail')]",
            "publisherName": "[parameters('publisherName')]"
        },
        "identity": {
            "type": "systemAssigned"
        }
    },
    {
        "type": "Microsoft.KeyVault/vaults/accessPolicies",
        "name": "[concat(parameters('keyVaultName'), '/add')]",
        "apiVersion": "2018-02-14",
        "properties": {
            "accessPolicies": [{
                "tenantId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').tenantId]",
                "objectId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').principalId]",
                "permissions": {
                     "secrets": ["get", "list"]
                }
            }]
        }
    },
	{
        "apiVersion": "2021-04-01",
		"type": "Microsoft.Resources/deployments",
        "name": "apimWithKeyVault",
		 "dependsOn": [
        "[resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName'))]"
        ],
        "properties": {
            "mode": "incremental",
            "template": {
                "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
				"contentVersion": "1.0.0.0",
				"parameters": {},			
				"resources": [{
					"apiVersion": "2021-08-01",
					"name": "[parameters('apiManagementServiceName')]",
					"type": "Microsoft.ApiManagement/service",
					"location": "[resourceGroup().location]",
					"tags": {
					},
					"sku": {
						"name": "[parameters('sku')]",
						"capacity": "[parameters('skuCount')]"
					},
					"properties": {
						"publisherEmail": "[parameters('publisherEmail')]",
						"publisherName": "[parameters('publisherName')]",
						"hostnameConfigurations": [{
							"type": "Proxy",
							"hostName": "[parameters('proxyCustomHostname1')]",
							"keyVaultId": "[parameters('keyVaultIdToCertificate')]"
						}]
					},
					"identity": {
						"type": "systemAssigned"
					}
				}]
		}
		}
	}
]
}

Armazenar e gerenciar valores nomeados do Azure Key Vault

Você pode usar uma identidade gerenciada atribuída ao sistema para acessar o Cofre de Chaves do Azure para armazenar e gerenciar segredos para uso em políticas de Gerenciamento de API. Para obter mais informações, consulte Usar valores nomeados em políticas de Gerenciamento de API do Azure.

Autenticar em um back-end usando uma identidade de Gerenciamento de API

Você pode usar a identidade atribuída ao sistema para autenticar em um serviço de back-end por meio da política de identidade gerenciada por autenticação.

Ligar aos recursos do Azure protegidos pela firewall de IP com uma identidade gerida atribuída pelo sistema

A Gestão de API é um serviço Microsoft fidedigno para os seguintes recursos. Permite que o serviço se ligue aos seguintes recursos protegidos por uma firewall. Depois de atribuir explicitamente a função apropriada do Azure à identidade gerenciada atribuída pelo sistema para essa instância de recurso, o escopo de acesso para a instância corresponde à função do Azure atribuída à identidade gerenciada.

Serviço do Azure Ligação
Azure Key Vault Acesso confiável ao azure-key-vault
Armazenamento do Azure Acesso confiável ao armazenamento do Azure
Azure Service Bus Acesso confiável ao azure-service-bus
Hubs de Eventos do Azure Acesso confiável ao azure-event-hub

Registrar eventos em um hub de eventos

Você pode configurar e usar uma identidade gerenciada atribuída ao sistema para acessar um hub de eventos para registrar eventos de uma instância de Gerenciamento de API. Para obter mais informações, consulte Como registrar eventos nos Hubs de Eventos do Azure no Gerenciamento de API do Azure.

Criar uma identidade gerida atribuída pelo utilizador

Nota

Você pode associar uma instância de Gerenciamento de API a até 10 identidades gerenciadas atribuídas pelo usuário.

Portal do Azure

Para configurar uma identidade gerenciada no portal, você primeiro criará uma instância de Gerenciamento de API e criará uma identidade atribuída pelo usuário. Em seguida, habilite o recurso.

  1. Crie uma instância de Gerenciamento de API no portal como faria normalmente. Navegue até ele no portal.

  2. No menu à esquerda, em Segurança, selecione Identidades gerenciadas.

  3. Na guia Usuário atribuído, selecione Adicionar.

  4. Procure a identidade que criou anteriormente e selecione-a. Selecione Adicionar.

    Seleções para habilitar uma identidade gerenciada atribuída pelo usuário

Azure PowerShell

Nota

Recomendamos que utilize o módulo do Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

As etapas a seguir orientam você na criação de uma instância de Gerenciamento de API e na atribuição de uma identidade a ela usando o Azure PowerShell.

  1. Se necessário, instale o Azure PowerShell usando as instruções no guia do Azure PowerShell. Em seguida, execute Connect-AzAccount para criar uma conexão com o Azure.

  2. Use o código a seguir para criar a instância. Para obter mais exemplos de como usar o Azure PowerShell com uma instância de Gerenciamento de API, consulte Exemplos do PowerShell de Gerenciamento de API.

    # Create a resource group.
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    
    # Create a user-assigned identity. This requires installation of the "Az.ManagedServiceIdentity" module.
    $userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName
    
    # Create an API Management Consumption Sku service.
    $userIdentities = @($userAssignedIdentity.Id)
    
    New-AzApiManagement -ResourceGroupName $resourceGroupName -Location $location -Name $apiManagementName -Organization contoso -AdminEmail admin@contoso.com -Sku Consumption -UserAssignedIdentity $userIdentities
    

Você também pode atualizar um serviço existente para atribuir uma identidade ao serviço:

# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName

# Create a user-assigned identity. This requires installation of the "Az.ManagedServiceIdentity" module.
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName

# Update an API Management instance
$userIdentities = @($userAssignedIdentity.Id)
Set-AzApiManagement -InputObject $apimService -UserAssignedIdentity $userIdentities

Modelo Azure Resource Manager

Você pode criar uma instância de Gerenciamento de API com uma identidade incluindo a seguinte propriedade na definição de recurso:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

Adicionar o tipo atribuído pelo usuário informa ao Azure para usar a identidade atribuída pelo usuário especificada para sua instância.

Por exemplo, um modelo completo do Azure Resource Manager pode ter a seguinte aparência:

{
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2021-08-01",
        "name": "contoso",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {},
        "sku": {
            "name": "Developer",
            "capacity": "1"
        },
        "properties": {
            "publisherEmail": "admin@contoso.com",
            "publisherName": "Contoso"
        },
        "identity": {
            "type": "UserAssigned",
             "userAssignedIdentities": {
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
             }
        },
         "dependsOn": [
          "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
        ]
    }]
}

Quando o serviço é criado, ele tem as seguintes propriedades adicionais:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {
            "principalId": "<PRINCIPALID>",
            "clientId": "<CLIENTID>"
        }
    }
}

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

Nota

Uma instância de Gestão de API pode ter identidades atribuídas pelo sistema e pelo utilizador ao mesmo tempo. Neste caso, a type propriedade seria SystemAssigned,UserAssigned.

Cenários suportados usando identidade gerenciada atribuída pelo usuário

Obter um certificado TLS/SSL personalizado para a instância de Gestão de API do Azure Key Vault

Você pode usar uma identidade atribuída pelo usuário para estabelecer confiança entre uma instância de Gerenciamento de API e o Cofre de Chaves do Azure. Essa relação de confiança pode ser usada para recuperar certificados TLS/SSL personalizados armazenados no Cofre da Chave do Azure. Em seguida, você pode atribuir esses certificados a domínios personalizados na instância de Gerenciamento de API.

Importante

Se o firewall do Cofre de Chaves estiver habilitado no cofre de chaves, você não poderá usar uma identidade atribuída pelo usuário para acesso a partir do Gerenciamento de API. Em vez disso, você pode usar a identidade atribuída ao sistema. No firewall do Cofre de Chaves, a opção Permitir que Serviços Microsoft Confiáveis ignorem esse firewall também deve ser habilitada.

Tenha estas considerações em mente:

  • O tipo de conteúdo do segredo deve ser application/x-pkcs12.
  • Use o ponto de extremidade secreto do certificado do Cofre da Chave, que contém o segredo.

Importante

Se você não fornecer a versão objeto do certificado, o Gerenciamento de API obterá automaticamente a versão mais recente do certificado dentro de quatro horas após a atualização no Cofre da Chave.

Para obter o modelo completo, consulte Gerenciamento de API com SSL baseado no Cofre de Chaves usando a Identidade Atribuída pelo Usuário.

Neste modelo, você implantará:

  • Instância de Gerenciamento de API do Azure
  • Identidade gerenciada atribuída pelo usuário do Azure
  • Azure Key Vault para armazenar o certificado SSL/TLS

Para executar a implantação automaticamente, selecione o seguinte botão:

Botão para implantar o modelo do Gerenciador de Recursos no Azure.

Armazenar e gerenciar valores nomeados do Azure Key Vault

Você pode usar uma identidade gerenciada atribuída pelo usuário para acessar o Cofre de Chaves do Azure para armazenar e gerenciar segredos para uso em políticas de Gerenciamento de API. Para obter mais informações, consulte Usar valores nomeados em políticas de Gerenciamento de API do Azure.

Nota

Se o firewall do Cofre de Chaves estiver habilitado no cofre de chaves, você não poderá usar uma identidade atribuída pelo usuário para acesso a partir do Gerenciamento de API. Em vez disso, você pode usar a identidade atribuída ao sistema. No firewall do Cofre de Chaves, a opção Permitir que Serviços Microsoft Confiáveis ignorem esse firewall também deve ser habilitada.

Autenticar em um back-end usando uma identidade atribuída pelo usuário

Você pode usar a identidade atribuída pelo usuário para autenticar em um serviço de back-end por meio da política de identidade gerenciada por autenticação.

Registrar eventos em um hub de eventos

Você pode configurar e usar uma identidade gerenciada atribuída pelo usuário para acessar um hub de eventos para registrar eventos de uma instância de Gerenciamento de API. Para obter mais informações, consulte Como registrar eventos nos Hubs de Eventos do Azure no Gerenciamento de API do Azure.

Remover uma identidade

Você pode remover uma identidade atribuída ao sistema desativando o recurso por meio do portal ou do modelo do Azure Resource Manager da mesma maneira que foi criado. As identidades atribuídas pelo usuário podem ser removidas individualmente. Para remover todas as identidades, defina o tipo de identidade como "None".

Remover uma identidade atribuída ao sistema dessa forma também a excluirá da ID do Microsoft Entra. As identidades atribuídas ao sistema também são removidas automaticamente do Microsoft Entra ID quando a instância de Gerenciamento de API é excluída.

Para remover todas as identidades usando o modelo do Azure Resource Manager, atualize esta seção:

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

Importante

Se uma instância de Gerenciamento de API estiver configurada com um certificado SSL personalizado do Cofre da Chave e você tentar desabilitar uma identidade gerenciada, a solicitação falhará.

Você pode se desbloquear alternando de um certificado do Cofre da Chave do Azure para um certificado codificado embutido e, em seguida, desabilitando a identidade gerenciada. Para obter mais informações, consulte Configurar um nome de domínio personalizado.

Próximos passos

Saiba mais sobre identidades gerenciadas para recursos do Azure: