Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 o Gerenciamento de API acesse com facilidade e segurança outros recursos protegidos pelo Microsoft Entra, como o Azure Key Vault. O Azure gere estas identidades, para que não precise provisionar ou alterar quaisquer 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 para o locatário do Microsoft Entra no qual 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 reconfigurar as identidades.
Nota
Atualmente, esse recurso não está disponível em espaços de trabalho.
Criar uma identidade gerenciada atribuída ao 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 faria normalmente. Aceda a isso no portal.
No menu à esquerda, em Segurança, selecione Identidades gerenciadas.
Na guia Sistema atribuído , altere o Status para Ativado. Selecione Guardar.
Azure PowerShell
Nota
Recomendamos que utilize o módulo Azure Az do PowerShell para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. 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 guiam 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.
Se precisar, instale o Azure PowerShell seguindo as instruções no guia do Azure PowerShell. Em seguida, 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 ao 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
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 do Azure Resource Manager (ARM)
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 do modelo 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 ARM completo pode se parecer com 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 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 Gerenciamento de API pode ter identidades atribuídas ao sistema e ao usuário. Nesse cenário, a type propriedade é SystemAssigned,UserAssigned.
Configurar o acesso ao Cofre da Chave usando uma identidade gerenciada
As configurações a seguir sã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 cofre de chaves
- No portal, aceda ao cofre das chaves.
- No menu à esquerda, selecione Configuração de acesso. Observe o modelo de permissão que está configurado.
- 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:
- No menu à esquerda, selecione Políticas de acesso.
- Na página Políticas de acesso , selecione + Criar.
- No separador Permissões , em Permissões secretas, selecione Obter e Listar e, em seguida, selecione Seguinte.
- No separador Principal , selecione Principal, 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.
- Selecione Avançar novamente. No separador Rever + criar, selecione Criar.
Para configurar o acesso ao Azure RBAC:
- 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 Cofre da Chave.
- 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 à sua instância de Gerenciamento de API e clique em Selecionar.
- Selecione Rever + atribuir.
Requisitos para o firewall do Key Vault
Se o firewall do Cofre da Chave estiver habilitado no cofre da chave, você deverá atender aos seguintes 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 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:
- Habilite um ponto de extremidade de serviço para o Cofre da Chave na sub-rede Gerenciamento de API.
- Configure uma regra NSG (grupo de segurança de rede) para permitir o tráfego de saída para as tags de serviço AzureKeyVault e AzureActiveDirectory.
Para obter detalhes, consulte Configuração de rede ao configurar o Gerenciamento de API em uma rede virtual.
Cenários suportados que usam identidade atribuída ao sistema
A seguir estão alguns cenários comuns para usar uma identidade gerenciada atribuída ao sistema no Gerenciamento de API do Azure.
Obter um certificado TLS/SSL personalizado para a instância de Gerenciamento de API no Cofre da Chave
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 Cofre da Chave. Em seguida, você pode atribuir esses certificados a domínios personalizados na instância de Gerenciamento de API. Tenha em conta as seguintes considerações:
- O tipo de conteúdo do segredo deve ser application/x-pkcs12. Para obter mais informações, consulte Opções de certificado de domínio.
- Você deve usar o endpoint secreto 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 qualquer 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 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 Cofre da Chave.
Pré-requisitos
- Uma instância 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 Cofre da Chave 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 seguintes etapas.
- Atualize as políticas de acesso da instância do Cofre da Chave e permita que a instância de Gerenciamento de API obtenha segredos dela.
- 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 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"
}
}]
}
}
}
]
}
Armazene e gerencie valores nomeados do Cofre da Chave
Você pode usar uma identidade gerenciada atribuída pelo sistema para acessar o Cofre da Chave 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 pelo sistema para autenticar em um serviço de backend por meio da política de identidade gerenciada por autenticação.
Conectar-se aos recursos do Azure por trás de um firewall IP usando uma identidade gerenciada atribuída ao sistema
A Gestão de API é um serviço Microsoft fidedigno para os seguintes recursos. 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 para a instância corresponde à função do Azure atribuída à identidade gerenciada.
- Acesso confiável para 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 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 em Hubs de Eventos 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ê deve primeiro criar uma instância de Gerenciamento de API e criar uma identidade atribuída pelo usuário. Em seguida, conclua as etapas a seguir.
Vá para 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 criou anteriormente e selecione-a. Selecione Adicionar.
Azure PowerShell
Nota
Recomendamos que utilize o módulo Azure Az do PowerShell para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. 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 guiam 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.
Se precisar, instale o Azure PowerShell seguindo as instruções no guia do Azure PowerShell. Em seguida, 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
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 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 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 informa o Azure para usar a identidade atribuída pelo usuário especificada para sua instância.
Por exemplo, um modelo ARM completo pode se parecer com 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 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 Gerenciamento de API pode ter identidades atribuídas ao sistema e ao usuário. Nesse cenário, a type propriedade seria SystemAssigned,UserAssigned.
Cenários suportados 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 no Cofre da Chave
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. Essa relação de confiança pode ser usada para recuperar certificados TLS/SSL personalizados armazenados no Cofre da Chave. 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 deve ser habilitada.
Tenha em conta as seguintes considerações:
- O tipo de conteúdo do segredo deve ser application/x-pkcs12.
- Você deve usar o endpoint secreto 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 qualquer versão mais recente do certificado dentro de quatro horas após a atualização no Cofre da Chave.
Armazene e gerencie valores nomeados do Cofre da Chave
Você pode usar uma identidade gerenciada atribuída pelo usuário para acessar o Cofre de Chaves 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 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 de um modelo ARM da mesma forma 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 maneira também a exclui 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 um modelo 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 Cofre da Chave e você tentar desabilitar uma identidade gerenciada, a solicitação falhará.
Pode resolver isso alternando de um certificado do Azure Key Vault para um certificado codificado inline e, em seguida, desabilitando a identidade gerida. Para obter mais informações, consulte Configurar um nome de domínio personalizado.