Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 o Gerenciamento de API acesse com facilidade e segurança outros recursos protegidos pelo Microsoft Entra, como o Azure Key Vault. O Azure gerencia essas identidades, portanto, você não precisa provisionar nem girar segredos. 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 pode ter apenas 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 no qual 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 reconfigurar 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, crie uma instância de Gerenciamento de API e habilite o recurso.
Crie uma instância de Gerenciamento de API no portal, como você faria normalmente. Vá até ele no portal.
No menu à esquerda, em Segurança, selecione Identidades Gerenciadas.
Na guia Atribuída pelo sistema , altere o Status para Ativado. Clique em Salvar.
Azure PowerShell
Observação
Recomendamos que você use o módulo Azure Az PowerShell para interagir com o Azure. Para começar, consulte Instalar o Microsoft Azure PowerShell. Para saber como migrar para o módulo Az PowerShell, veja Migrar o Microsoft Azure PowerShell do AzureRM para o Az.
As etapas a seguir levam você à criação de uma instância de Gerenciamento de API e à atribuição de uma identidade usando o Azure PowerShell.
Se você precisar, instale o Azure PowerShell seguindo as instruções no guia do Azure PowerShell. Então, execute
Connect-AzAccountpara criar uma conexão com o Azure.Use o código a seguir para criar uma instância com uma identidade gerenciada atribuída pelo sistema. Para obter mais exemplos de como usar o Azure PowerShell com o 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
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 ARM (Azure Resource Manager)
Você pode criar uma instância de Gerenciamento de API com uma identidade atribuída pelo sistema, incluindo a seguinte propriedade na definição de recurso de modelo do ARM:
"identity" : {
"type" : "SystemAssigned"
}
Essa propriedade instrui o Azure a criar e gerenciar a identidade para sua instância de Gerenciamento de API.
Por exemplo, um modelo completo do ARM pode ser semelhante a este:
{
"$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 de Gerenciamento de API pode ter identidades atribuídas pelo sistema e atribuídas pelo usuário. Nesse cenário, a type propriedade é SystemAssigned,UserAssigned.
Configurar o acesso ao Key Vault usando uma identidade gerenciada
As configurações a seguir serão necessárias se você quiser usar o Gerenciamento de API para acessar certificados de um cofre de chaves do Azure.
Configurar o acesso ao Key Vault
- No portal, acesse seu cofre de chaves.
- No menu à esquerda, selecione Configurações>de Acesso. Observe 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 secretas, selecione Obter e Listar e selecione Avançar.
- Na guia Principal , pesquise o nome do recurso de sua 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 janela Selecionar identidades gerenciadas , selecione a identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário associada à instância de Gerenciamento de API e clique em Selecionar.
- Selecione Revisar + atribuir.
Requisitos para firewall do Key Vault
Se o firewall do Key Vault estiver habilitado no cofre de chaves, você deverá atender a estes requisitos:
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 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 Key Vault na sub-rede de 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 a configuração de rede ao configurar o Gerenciamento de API em uma rede virtual.
Cenários com suporte que usam a identidade atribuída pelo sistema
A seguir estão alguns cenários comuns para usar uma identidade gerenciada atribuída pelo sistema no Gerenciamento de API do Azure.
Obter um certificado TLS/SSL personalizado para a instância de Gerenciamento de API do Key Vault
Você pode usar a identidade atribuída pelo sistema de uma instância de Gerenciamento de API para recuperar certificados TLS/SSL personalizados armazenados no Key Vault. Então, você pode atribuir esses certificados a domínios personalizados na instância do Gerenciamento de API. Leve estas considerações em conta:
- O tipo de conteúdo do segredo deve ser application/x-pkcs12. Para obter mais informações, consulte as opções de certificado de domínio.
- Você deve usar o ponto de extremidade do segredo do certificado do Key Vault, que contém o segredo.
Importante
Se você não fornecer a versão do objeto do certificado, o Gerenciamento de API obterá automaticamente qualquer versão mais recente do certificado dentro de quatro horas após ele ser atualizado no Key Vault.
O exemplo a seguir mostra um modelo do ARM que usa a identidade gerenciada atribuída pelo sistema de uma instância de Gerenciamento de API para recuperar um certificado de domínio personalizado do Key Vault.
Pré-requisitos
- Uma instância de 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 Key Vault no mesmo grupo de recursos. A instância deve hospedar um certificado que será usado como um certificado de domínio personalizado no Gerenciamento de API.
O modelo contém as etapas a seguir.
- Atualize as políticas de acesso da instância do Key Vault e permita que a instância de Gerenciamento de API obtenha segredos dela.
- 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â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 instance"
}
},
"publisherEmail": {
"type": "string",
"minLength": 1,
"metadata": {
"description": "The email address of the owner of the instance"
}
},
"publisherName": {
"type": "string",
"minLength": 1,
"metadata": {
"description": "The name of the owner of the instance"
}
},
"sku": {
"type": "string",
"allowedValues": ["Developer",
"Standard",
"Premium"],
"defaultValue": "Developer",
"metadata": {
"description": "The pricing tier of the API Management instance"
}
},
"skuCount": {
"type": "int",
"defaultValue": 1,
"metadata": {
"description": "The instance size of the API Management instance"
}
},
"keyVaultName": {
"type": "string",
"metadata": {
"description": "The 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 Key Vault
Você pode usar uma identidade gerenciada atribuída pelo sistema para acessar o 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 autenticar-se em um serviço de back-end por meio da política autenticação-por-identidade-gerenciada.
Conectar-se aos recursos do Azure por trás de um firewall de IP usando uma identidade gerenciada atribuída pelo sistema
O Gerenciamento de API é um serviço confiável da Microsoft para os recursos a seguir. Esse status confiável permite que o serviço se conecte aos seguintes recursos por trás de um firewall. Depois de atribuir explicitamente a função apropriada do Azure à identidade gerenciada atribuída pelo sistema para uma instância de recurso, o escopo de acesso da instância corresponde à função do Azure atribuída à identidade gerenciada.
- Acesso confiável para o Key Vault
- Acesso confiável para o Armazenamento do Azure
- Acesso confiável para o Barramento de Serviços do Azure
- Acesso confiável para Hubs de Eventos do Azure
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 de Gerenciamento de API. Para obter mais informações, consulte Como registrar eventos em hubs de eventos 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 a até 10 identidades gerenciadas atribuídas pelo usuário.
portal do Azure
Para configurar uma identidade gerenciada no portal, primeiro você deve criar uma instância de Gerenciamento de API e criar uma identidade atribuída pelo usuário. Em seguida, conclua as etapas a seguir.
Acesse sua instância de Gerenciamento de API 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 Azure Az PowerShell para interagir com o Azure. Para começar, consulte Instalar o Microsoft Azure PowerShell. Para saber como migrar para o módulo Az PowerShell, veja Migrar o Microsoft Azure PowerShell do AzureRM para o Az.
As etapas a seguir levam você à criação de uma instância de Gerenciamento de API e à atribuição de uma identidade usando o Azure PowerShell.
Se você precisar, instale o Azure PowerShell seguindo as instruções no 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 o 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 code 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 code requires installation of the Az.ManagedServiceIdentity module.
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName
# Update the API Management instance.
$userIdentities = @($userAssignedIdentity.Id)
Set-AzApiManagement -InputObject $apimService -UserAssignedIdentity $userIdentities
modelo do ARM
Você pode criar uma instância de Gerenciamento de API que tenha uma identidade, incluindo a seguinte propriedade na definição de recurso:
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {}
}
}
Adicionar o tipo atribuído pelo usuário instrui o Azure a usar a identidade de usuário correspondente especificada para sua instância.
Por exemplo, um modelo completo do ARM pode ser semelhante a este:
{
"$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 de Gerenciamento de API pode ter identidades atribuídas pelo sistema e atribuídas pelo usuário. Nesse cenário, a type propriedade seria SystemAssigned,UserAssigned.
Cenários com suporte que usam identidades gerenciadas atribuídas pelo usuário
A seguir estão alguns cenários comuns para usar uma identidade gerenciada atribuída pelo usuário no Gerenciamento de API do Azure.
Obter um certificado TLS/SSL personalizado para a instância de Gerenciamento de API do Key Vault
Você pode usar uma identidade atribuída pelo usuário para estabelecer a confiança entre uma instância de Gerenciamento de API e o Key Vault. Essa confiança pode ser usada para recuperar certificados TLS/SSL personalizados armazenados no 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 Serviços Confiáveis da Microsoft ignorem este firewall deve estar habilitada.
Leve estas considerações em conta:
- O tipo de conteúdo do segredo deve ser application/x-pkcs12.
- Você deve usar o ponto de extremidade do segredo do certificado do Key Vault, que contém o segredo.
Importante
Se você não fornecer a versão do objeto do certificado, o Gerenciamento de API obterá automaticamente qualquer versão mais recente do certificado dentro de quatro horas após ele ser atualizado no Key Vault.
Armazenar e gerenciar valores nomeados do Key Vault
Você pode usar uma identidade gerenciada atribuída pelo usuário para acessar o 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 Serviços Confiáveis da Microsoft ignorem este 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 eventos de uma instância de 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 de um modelo do ARM 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 exclui da ID do Microsoft Entra. 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 um modelo do ARM, atualize esta seção:
"identity": {
"type": "None"
}
Importante
Se uma instância de 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 resolver isso alternando de um certificado do Key Vault para um certificado embutido codificado e desabilitando a identidade gerenciada. Para saber mais, confira Configurar um nome de domínio personalizado.