Usar identidades gerenciadas no gerenciamento de API do AzureUse managed identities in Azure API Management

Este artigo mostra como criar uma identidade gerenciada para uma instância de serviço de gerenciamento de API e como acessar outros recursos.This article shows you how to create a managed identity for an API Management service instance and how to access other resources. Uma identidade gerenciada gerada pelo Azure Active Directory (Azure AD) permite que a instância de gerenciamento de API com facilidade e segurança acessar outros recursos do Azure protegidos pelo AD, como o Azure Key Vault.A managed identity generated by Azure Active Directory (Azure AD) allows your API Management instance to easily and securely access other Azure AD-protected resources, such as Azure Key Vault. Essa identidade é gerenciada pelo Azure e não exige provisionamento ou giro de nenhum segredo.This identity is managed by Azure and does not require you to provision or rotate any secrets. Para obter mais informações sobre identidades gerenciadas, consulte What ' s identidades gerenciadas para recursos do Azure.For more information about managed identities, see What is managed identities for Azure resources.

Criar uma identidade gerenciada para uma instância de gerenciamento de APICreate a managed identity for an API Management instance

Usando o portal do AzureUsing the Azure portal

Para configurar uma identidade gerenciada no portal, você primeiro cria uma instância de gerenciamento de API como normal e, em seguida, habilite o recurso.To set up a managed identity in the portal, you will first create an API Management instance as normal and then enable the feature.

  1. Crie uma instância de Gerenciamento de API no portal, como você faria normalmente.Create an API Management instance in the portal as you normally would. Navegue até ele no portal.Navigate to it in the portal.
  2. Selecione identidades de serviço gerenciadas.Select Managed service identities.
  3. Defina Registrar com o Azure Active Directory como Ativado.Switch Register with Azure Active Directory to On. Clique em Salvar.Click Save.

Habilitar MSI

Usando o modelo do Azure Resource ManagerUsing the Azure Resource Manager template

Crie uma instância de Gerenciamento de API com uma identidade incluindo a seguinte propriedade na definição de recurso:You can create an API Management instance with an identity by including the following property in the resource definition:

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

Isso faz com que o Azure crie e gerencie a identidade para sua instância do Gerenciamento de API.This tells Azure to create and manage the identity for your API Management instance.

Por exemplo, um modelo completo do Azure Resource Manager pode ter a seguinte aparência:For example, a complete Azure Resource Manager template might look like the following:

{
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2017-03-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"
        }
    }]
}

Usar a identidade de serviço gerenciado para acessar outros recursosUse the managed service identity to access other resources

Observação

Atualmente, as identidades gerenciadas podem ser usadas para obter certificados do Azure Key Vault para nomes de domínio personalizado de gerenciamento de API.Currently, managed identities can be used to obtain certificates from Azure Key Vault for API Management custom domain names. Em breve, mais cenários receberão suporte.More scenarios will be supported soon.

Obter um certificado do Azure Key VaultObtain a certificate from Azure Key Vault

Pré-requisitosPrerequisites

  1. O Key Vault que contém o certificado pfx deve estar na mesma assinatura do Azure e no mesmo Grupo de recursos que o serviço de Gerenciamento de API.The Key Vault containing the pfx certificate must be in the same Azure subscription and the same Resource Group as the API Management service. Este é um requisito do modelo do Azure Resource Manager.This is a requirement of the Azure Resource Manager template.
  2. O Tipo de conteúdo do segredo deve ser application/x-pkcs12.The Content Type of the secret must be application/x-pkcs12. É possível usar o seguinte script para carregar o certificado:You can use the following script to upload the certificate:
$pfxFilePath = "PFX_CERTIFICATE_FILE_PATH" # Change this path 
$pwd = "PFX_CERTIFICATE_PASSWORD" # Change this password 
$flag = [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable 
$collection = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2Collection 
$collection.Import($pfxFilePath, $pwd, $flag) 
$pkcs12ContentType = [System.Security.Cryptography.X509Certificates.X509ContentType]::Pkcs12 
$clearBytes = $collection.Export($pkcs12ContentType) 
$fileContentEncoded = [System.Convert]::ToBase64String($clearBytes) 
$secret = ConvertTo-SecureString -String $fileContentEncoded -AsPlainText –Force 
$secretContentType = 'application/x-pkcs12' 
Set-AzureKeyVaultSecret -VaultName KEY_VAULT_NAME -Name KEY_VAULT_SECRET_NAME -SecretValue $Secret -ContentType $secretContentType

Importante

Se a versão do objeto do certificado não for fornecida, o Gerenciamento de API obterá automaticamente a versão mais recente do certificado depois de carregada no Key Vault.If the object version of the certificate is not provided, API Management will automatically obtain the newer version of the certificate after it is uploaded to Key Vault.

O exemplo a seguir mostra um modelo do Azure Resource Manager que contém as seguintes etapas:The following example shows an Azure Resource Manager template that contains the following steps:

  1. Crie uma instância de gerenciamento de API com uma identidade gerenciada.Create an API Management instance with a managed identity.
  2. Atualizar as políticas de acesso de uma instância do Azure Key Vault e permitir que a instância de Gerenciamento de API obtenha os segredos dele.Update the access policies of an Azure Key Vault instance and allow the API Management instance to obtain secrets from it.
  3. Atualizar a instância de Gerenciamento de API configurando um nome de domínio personalizado por meio de um certificado da instância do Key Vault.Update the API Management instance by setting a custom domain name through a certificate from the Key Vault instance.
{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "publisherEmail": {
            "type": "string",
            "minLength": 1,
            "metadata": {
                "description": "The email address of the owner of the service"
            }
        },
        "publisherName": {
            "type": "string",
            "defaultValue": "Contoso",
            "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 vault"
            }
        },
        "proxyCustomHostname1": {
            "type": "string",
            "metadata": {
                "description": "Proxy Custom hostname."
            }
        },
        "keyVaultIdToCertificate": {
            "type": "string",
            "metadata": {
                "description": "Reference to the KeyVault certificate. https://contoso.vault.azure.net/secrets/contosogatewaycertificate."
            }
        }
    },
    "variables": {
        "apiManagementServiceName": "[concat('apiservice', uniqueString(resourceGroup().id))]",
        "apimServiceIdentityResourceId": "[concat(resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName')),'/providers/Microsoft.ManagedIdentity/Identities/default')]"
    },
    "resources": [{
        "apiVersion": "2017-03-01",
        "name": "[variables('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": "2015-06-01",
        "dependsOn": [
            "[resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName'))]"
        ],
        "properties": {
            "accessPolicies": [{
                "tenantId": "[reference(variables('apimServiceIdentityResourceId'), '2015-08-31-PREVIEW').tenantId]",
                "objectId": "[reference(variables('apimServiceIdentityResourceId'), '2015-08-31-PREVIEW').principalId]",
                "permissions": {
                    "secrets": ["get"]
                }
            }]
        }
    },
    {
        "apiVersion": "2017-05-10",
        "name": "apimWithKeyVault",
        "type": "Microsoft.Resources/deployments",
        "dependsOn": [
        "[resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName'))]"
        ],
        "properties": {
            "mode": "incremental",
            "templateLink": {
                "uri": "https://raw.githubusercontent.com/solankisamir/arm-templates/master/basicapim.keyvault.json",
                "contentVersion": "1.0.0.0"
            },
            "parameters": {
                "publisherEmail": { "value": "[parameters('publisherEmail')]"},
                "publisherName": { "value": "[parameters('publisherName')]"},
                "sku": { "value": "[parameters('sku')]"},
                "skuCount": { "value": "[parameters('skuCount')]"},
                "proxyCustomHostname1": {"value" : "[parameters('proxyCustomHostname1')]"},
                "keyVaultIdToCertificate": {"value" : "[parameters('keyVaultIdToCertificate')]"}
            }
        }
    }]
}

Próximas etapasNext steps

Saiba mais sobre identidades gerenciadas para recursos do Azure:Learn more about managed identities for Azure resources: