Usar identidades gerenciadas no Gerenciamento de API do Azure

APLICA-SE A: todas as camadas do Gerenciamento de API

Este artigo mostra como criar uma identidade gerenciada para uma instância do 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 do Gerenciamento de API acesse com facilidade e segurança outros recursos protegidos do Microsoft Entra, como o Azure Key Vault. O Azure gerencia essa identidade para que você não precise provisionar ou girar nenhum segredo. Para obter mais informações sobre identidades gerenciadas, confira O que são identidades gerenciadas para recursos do Azure?.

Você pode conceder dois tipos de identidade para uma instância do Gerenciamento de API:

• Uma identidade atribuída pelo sistema é vinculada ao seu serviço e é excluída se o seu serviço é excluído. O serviço 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 serviço. Um serviço pode ter várias identidades atribuídas pelo usuário.

Criar uma identidade gerenciada atribuída pelo sistema

Portal do Azure

Para configurar uma identidade gerenciada no portal do Azure, primeiro crie uma instância do Gerenciamento de API e depois habilite o recurso.

1. Crie uma instância de Gerenciamento de API no portal, como você faria normalmente. Navegue até ela no portal.

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

3. Na guia Sistema atribuído, alterne o Status para Ativado. Clique em Salvar.

   

Azure PowerShell

As etapas a seguir guiarão você na criação de uma instância do 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 do Guia do Azure PowerShell. Então, 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 pelo sistema. Para obter mais exemplos de como usar o Azure PowerShell com uma instância do Gerenciamento de API, confira Exemplos do PowerShell do 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
   

Atualize 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 do Azure Resource Manager

Crie uma instância de Gerenciamento de API com uma identidade atribuída pelo sistema incluindo a seguinte propriedade na definição de recurso:

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

Essa propriedade faz com que o Azure crie e gerencie a identidade da 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 propriedade tenantId identifica a qual locatário do Microsoft Entra a identidade pertence. A propriedade principalId é 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 do Gerenciamento de API.

Configurar o acesso do Key Vault usando uma identidade gerenciada

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

Configurar o acesso ao Key Vault

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

2. No menu à esquerda, selecione Configuração de acesso e anote o Modelo de permissão configurado.

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

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

   1. No menu à esquerda, selecione Políticas de acesso.
   2. Na página Políticas de acesso, selecione + Criar.
   3. Na guia Permissões, em Permissões em Permissões de segredo, escolha Obter e Listar. Clique em Avançar.
   4. Na guia Entidade de segurança, Selecionar entidade de segurança, procure o nome do recurso da identidade gerenciada e selecione Avançar. Se você estiver usando uma identidade atribuída pelo sistema, a entidade de segurança será o nome da instância de Gerenciamento de API.
   5. Selecione novamente Avançar. Na guia Revisar + criar, selecione Criar.

   Para configurar o acesso ao RBAC do Azure:
   

   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 do Certificado do Key Vault.
   4. Na guia Membros, selecione Identidade gerenciada>+ Selecionar membros.
   5. Na página Selecionar identidade gerenciada, escolha a identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância do Gerenciamento de API e clique em Selecionar.
   6. Selecione Examinar + atribuir.

Requisitos para firewall do Key Vault

Se o firewall do Key Vault estiver habilitado no seu cofre de chaves, os itens a seguir serão requisitos adicionais:

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

• No firewall do Key Vault, habilite a opção Permitir que os serviços confiáveis da Microsoft ignorem esse firewall.

• Verifique se o endereço IP do cliente local tem permissão para acessar o cofre de chaves temporariamente enquanto você seleciona um certificado ou segredo a ser adicionado ao Gerenciamento de API do Azure. Para obter mais informações, confira Definir configurações de rede do Azure Key Vault.

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

Requisitos de rede virtual

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

• Habilite um ponto de extremidade de serviço para o Azure Key Vault na sub-rede do Gerenciamento de API.
• Configure uma regra de NSG (grupo de segurança de rede) para permitir tráfego de saída para as marcas de serviço AzureKeyVault e AzureActiveDirectory.

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

Cenários com suporte usando a identidade atribuída pelo sistema

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

Você pode usar a identidade atribuída pelo sistema de uma instância do Gerenciamento de API para recuperar certificados TLS/SSL personalizados armazenados no Azure Key Vault. Então, você pode atribuir esses certificados a domínios personalizados na instância do Gerenciamento de API. Lembre-se do seguinte:

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

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 do domínio personalizado do Key Vault.

Pré-requisitos

• Uma instância de serviço do Gerenciamento de API configurada com uma identidade gerenciada atribuída pelo 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 do domínio personalizado no Gerenciamento de API.

O modelo a seguir contém as seguintes etapas.

1. Atualizar as políticas de acesso de uma instância do Azure Key Vault e permitir que a instância do Gerenciamento de API obtenha os segredos dele.
2. Atualizar a instância do Gerenciamento de API configurando um nome de domínio personalizado por meio de um certificado da instância do Key Vault.

Ao executar o modelo, forneça valores de parâmetros 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 pelo sistema para acessar o Azure Key Vault para armazenar e gerenciar segredos para uso em políticas de Gerenciamento de API. Para saber mais, confira Usar valores nomeados nas políticas de Gerenciamento de API do Azure.

Autenticar no back-end usando uma identidade do Gerenciamento de API

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

Conectar-se aos recursos do Azure por trás do Firewall de IP usando a identidade gerenciada atribuída pelo sistema

O Gerenciamento de API é um serviço confiável da Microsoft para os recursos a seguir. Isso permite que o serviço se conecte aos recursos a seguir, por trás de um 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 da instância corresponde à função do Azure atribuída à identidade gerenciada.

Registrar eventos para um hub de eventos

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

Criar uma identidade gerenciada atribuída ao usuário

Portal do Azure

Para configurar uma identidade gerenciada no portal, primeiro crie uma instância do Gerenciamento de API e crie uma identidade atribuída pelo usuário. Então, habilite o recurso.

1. Crie uma instância de Gerenciamento de API no portal, como você faria normalmente. Navegue até ela 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 você criou anteriormente e selecione-a. Selecione Adicionar.

   

Azure PowerShell

As etapas a seguir guiarão você na criação de uma instância do 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 do Guia do Azure PowerShell. Então, 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 do Gerenciamento de API, confira Exemplos do PowerShell do 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
   

Também é possível 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 do Azure Resource Manager

Crie 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 a 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 site é criado, ele tem as seguintes propriedades adicionais:

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

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

Cenários com suporte usando a identidade gerenciada atribuída pelo usuário

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

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

Lembre-se do seguinte:

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

Armazenar e gerenciar valores nomeados do Azure Key Vault

Você pode usar uma identidade gerenciada atribuída pelo usuário para acessar o Azure Key Vault para armazenar e gerenciar segredos para uso em políticas de Gerenciamento de API. Para saber mais, confira Usar valores nomeados nas políticas de Gerenciamento de API do Azure.

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

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

Registrar eventos para 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 em log eventos de uma instância do Gerenciamento de API. Para obter mais informações, confira Como registrar eventos para Hubs de Eventos do Azure no Gerenciamento de API do Azure.

Remover uma identidade

Você pode remover uma identidade atribuída pelo sistema desabilitando o recurso por meio do portal ou do modelo de Azure Resource Manager da mesma forma que ele 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 pelo sistema dessa maneira também a excluirá do Microsoft Entra ID. As identidades atribuídas pelo sistema também são automaticamente removidas do Microsoft Entra ID quando a instância do Gerenciamento de API é excluída.

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

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

Próximas etapas

Saiba mais sobre identidades gerenciadas para recursos do Azure:

• O que são identidades gerenciadas para recursos do Azure?
• Modelos do Gerenciador de Recursos do Azure
• Autenticar com uma identidade gerenciada em uma política