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.
Observação
As identidades gerenciadas são específicas para o locatário do Microsoft Entra em que sua assinatura do Azure está hospedada. Elas não serão atualizadas se uma assinatura for movida para um diretório diferente. Se uma assinatura for movida, você precisará recriar e configurar as identidades.
Observação
Atualmente, esse recurso não está disponível em workspaces.
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.
Crie uma instância de Gerenciamento de API no portal, como você faria normalmente. Navegue até ela no portal.
No menu à esquerda, em Segurança, selecione Identidades Gerenciadas.
Na guia Sistema atribuído, alterne o Status para Ativado. Clique em Salvar.
Azure PowerShell
Observação
Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. Para saber como migrar para o módulo Az PowerShell, confira Migrar o Azure PowerShell do AzureRM para o Az.
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.
Se necessário, instale o Azure PowerShell usando as instruções do Guia do Azure PowerShell. Então, execute
Connect-AzAccountpara criar uma conexão com o Azure.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.
Observação
Uma instância do Gerenciamento de API pode ter identidades atribuídas pelo sistema e atribuídas pelo usuário ao mesmo tempo. Nesse caso, a propriedade type seria SystemAssigned,UserAssigned.
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
No portal, navegue até o cofre de chaves.
No menu à esquerda, selecione Configuração de acesso e anote o Modelo de permissão configurado.
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:
- No menu à esquerda, selecione Políticas de acesso.
- Na página Políticas de acesso, selecione + Criar.
- Na guia Permissões, em Permissões em Permissões de segredo, escolha Obter e Listar. Clique em Avançar.
- 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.
- Selecione novamente Avançar. Na guia Revisar + criar, selecione Criar.
Para configurar o acesso ao RBAC do Azure:
- No menu à esquerda, selecione Controle de acesso (IAM) .
- Na página Controle de acesso (IAM), selecione Adicionar atribuição de função.
- Na guia Função, selecione Usuário do Certificado do Key Vault.
- Na guia Membros, selecione Identidade gerenciada>+ Selecionar membros.
- 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.
- 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.
Importante
Se você não fornecer a versão do objeto do certificado, o Gerenciamento de API obterá automaticamente a versão mais recente do certificado dentro de quatro horas após sua atualização no Key Vault.
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.
- 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.
- 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.
| Serviço do Azure | Link |
|---|---|
| Cofre de Chave do Azure | Trusted-access-to-azure-key-vault |
| Armazenamento do Azure | Acesso confiável ao armazenamento do Azure |
| Barramento de Serviço do Azure | Acesso confiável ao barramento de serviço do Azure |
| Hubs de eventos do Azure | Trusted-access-to-azure-event-hub |
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
Observação
Você pode associar uma instância de Gerenciamento de API com até 10 identidades gerenciadas atribuídas pelo 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.
Crie uma instância de Gerenciamento de API no portal, como você faria normalmente. Navegue até ela no portal.
No menu à esquerda, em Segurança, selecione Identidades Gerenciadas.
Na guia Usuário atribuído, selecione Adicionar.
Procure a identidade que você criou anteriormente e selecione-a. Selecione Adicionar.
Azure PowerShell
Observação
Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. Para saber como migrar para o módulo Az PowerShell, confira Migrar o Azure PowerShell do AzureRM para o Az.
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.
Se necessário, instale o Azure PowerShell usando as instruções do Guia do Azure PowerShell. Então, execute
Connect-AzAccountpara criar uma conexão com o Azure.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.
Observação
Uma instância do Gerenciamento de API pode ter identidades atribuídas pelo sistema e atribuídas pelo usuário ao mesmo tempo. Nesse caso, a propriedade type seria SystemAssigned,UserAssigned.
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.
Importante
Se o firewall do Key Vault estiver habilitado no cofre de chaves, você não poderá usar uma identidade atribuída pelo usuário para acesso de Gerenciamento de API. Em vez disso, você pode usar a identidade atribuída pelo sistema. No firewall do Key Vault, a opção Permitir que os serviços confiáveis da Microsoft ignorem esse firewall deve estar habilitada.
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.
Importante
Se você não fornecer a versão do objeto do certificado, o Gerenciamento de API obterá automaticamente a versão mais recente do certificado dentro de quatro horas após sua atualização no Key Vault.
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.
Observação
Se o firewall do Key Vault estiver habilitado no cofre de chaves, você não poderá usar uma identidade atribuída pelo usuário para acesso de Gerenciamento de API. Em vez disso, você pode usar a identidade atribuída pelo sistema. No firewall do Key Vault, a opção Permitir que os serviços confiáveis da Microsoft ignorem esse firewall deve estar habilitada.
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"
}
Importante
Se uma instância do Gerenciamento de API estiver configurada com um certificado SSL personalizado do Key Vault e você tentar desabilitar uma identidade gerenciada, a solicitação falhará.
Você pode desbloqueá-lo alternando de um certificado do Azure Key Vault para um certificado codificado embutido e, depois, desabilitando a identidade gerenciada. Para saber mais, confira Configurar um nome de domínio personalizado.
Próximas etapas
Saiba mais sobre identidades gerenciadas para recursos do Azure: