Uso de identidades administradas en Azure API Management
SE APLICA A: todos los niveles de API Management
En este artículo se muestra cómo crear una identidad administrada para una instancia de Azure API Management y cómo usarla para acceder a otros recursos. Una identidad administrada generada por Microsoft Entra ID permite que la instancia de API Management acceda fácilmente y de forma segura a otros recursos protegidos de Microsoft Entra, como Azure Key Vault. Azure administra esta identidad, por lo que usted no tiene que aprovisionar ni rotar ningún secreto. Para obtener más información sobre las identidades administradas, consulte el artículo sobre Qué son las identidades administradas para recursos de Azure.
Puede conceder dos tipos de identidades a una instancia de API Management:
- Una identidad asignada por el sistema está asociada al servicio y se elimina si se elimina el servicio. El servicio solo puede tener una identidad asignada por el sistema.
- Una identidad asignada por el usuario es un recurso de Azure independiente que puede asignarse al servicio. El servicio puede tener varias identidades asignadas por el usuario.
Nota:
Las identidades administradas son específicas del inquilino de Microsoft Entra donde se hospeda la suscripción de Azure. No se actualizan si una suscripción se mueve a otro directorio. Si se mueve una suscripción, deberá volver a crear y configurar las identidades.
Nota:
Actualmente, esta característica no está disponible en áreas de trabajo.
Creación de una identidad administrada asignada por el sistema
Azure portal
Para configurar una identidad administrada en Azure Portal, primero tendrá que crear una instancia de API Management y, a continuación, habilitar la característica.
Cree una instancia de API Management en el portal como lo haría normalmente. Búsquela en el portal.
En el menú de la izquierda, en Seguridad, seleccione Identidades administradas.
En la pestaña Asignado por el sistema, cambie Estado a Activado. Seleccione Guardar.
Azure PowerShell
Nota:
Se recomienda usar el módulo Azure Az de PowerShell para interactuar con Azure. Para comenzar, consulte Instalación de Azure PowerShell. Para más información sobre cómo migrar al módulo Az de PowerShell, consulte Migración de Azure PowerShell de AzureRM a Az.
Los siguientes pasos le guiarán por la creación de una instancia de API Management y la asignación de una identidad a esta mediante Azure PowerShell.
Si es necesario, instale Azure PowerShell con las instrucciones que se encuentra en la Guía de Azure PowerShell. Luego, ejecute
Connect-AzAccountpara crear una conexión con Azure.Use el código siguiente para crear la instancia con una identidad administrada asignada por el sistema. Para ver más ejemplos de cómo utilizar Azure PowerShell con la instancia de API Management, consulte los ejemplos de PowerShell de API Management.
# 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
También puede actualizar una instancia existente para crear la identidad:
# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName
# Update an API Management instance
Set-AzApiManagement -InputObject $apimService -SystemAssignedIdentity
Plantilla del Administrador de recursos de Azure
Puede crear una instancia de API Management con una identidad asignada por el sistema mediante la inclusión de la siguiente propiedad en la definición de recursos:
"identity" : {
"type" : "SystemAssigned"
}
Esta propiedad indica a Azure que debe crear y administrar la identidad para la instancia de API Management.
Por ejemplo, una plantilla de Azure Resource Manager completa podría tener el aspecto siguiente:
{
"$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"
}
}]
}
Cuando se crea la instancia, tiene las siguientes propiedades adicionales:
"identity": {
"type": "SystemAssigned",
"tenantId": "<TENANTID>",
"principalId": "<PRINCIPALID>"
}
La propiedad tenantId identifica a qué inquilino de Microsoft Entra pertenece la identidad. La propiedad principalId es un identificador único para la nueva identidad de la instancia. En Microsoft Entra ID, la entidad de servicio tiene el mismo nombre que asignó a la instancia de API Management.
Nota:
Una instancia de API Management puede tener identidades asignadas por el sistema y asignadas por el usuario al mismo tiempo. En este caso, la propiedad type sería SystemAssigned,UserAssigned.
Configuración del acceso a Key Vault mediante una identidad administrada
Las siguientes configuraciones son necesarias para que API Management pueda acceder a secretos y certificados de Azure Key Vault.
Configuración del acceso al almacén de claves
En el portal, vaya al almacén de claves.
En el menú de la izquierda, seleccione Configuración de acceso y anote el modelo de permisos configurado.
En función del modelo de permisos, configure una directiva de acceso al almacén de claves o el acceso de Azure RBAC para una identidad administrada de API Management.
Para agregar una directiva de acceso al almacén de claves:
- En el menú de la izquierda, seleccione Directivas de acceso.
- En la página Directivas de acceso, seleccione +Crear.
- En la pestaña Permisos, en Permisos de secretos, seleccione Obtener y Lista, y luego Siguiente.
- En la pestaña Entidad de seguridad, seleccione una entidad de seguridad, busque el nombre del recurso de la identidad administrada y, después, seleccione Siguiente. Si usa una identidad asignada por el sistema, la entidad de seguridad es el nombre de la instancia de API Management.
- Seleccione Siguiente de nuevo. En la pestaña Revisar y crear, seleccione Crear.
Para configurar el acceso de Azure RBAC:
- En el menú izquierdo, seleccione Control de acceso (IAM) .
- En la página Control de acceso (IAM), seleccione Agregar asignación de roles.
- En la pestaña Rol, seleccione Usuario de certificado de Key Vault.
- En la pestaña Miembros, seleccione Identidad administrada>+Seleccionar miembros.
- En la página Seleccionar identidad administrada, seleccione la identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario asociada a la instancia de API Management y, después, seleccione Seleccionar.
- Seleccione Revisar y asignar.
Requisitos de firewall de Key Vault
Si el firewall de Key Vault está habilitado en el almacén de claves, los siguientes son requisitos adicionales:
Para acceder al almacén de claves, debe usar la identidad administrada asignada por el sistema de la instancia de API Management.
En el firewall de Key Vault, establezca la opción ¿Quiere permitir que los servicios de confianza de Microsoft puedan omitir este firewall?
Asegúrese de que la dirección IP del cliente local tenga permiso para acceder al almacén de claves temporalmente mientras selecciona un certificado o secreto para agregar a Azure API Management. Para más información, vea Configuración de redes de Azure Key Vault.
Después de completar la configuración, puede bloquear la dirección del cliente en el firewall del almacén de claves.
Requisitos de red virtual
Si la instancia de API Management se ha implementado en una red virtual, configure también las siguientes opciones de red:
- Habilite un punto de conexión de servicio para Azure Key Vault en la subred de API Management.
- Configure una regla de grupo de seguridad de red (NSG) para permitir el tráfico saliente a las etiquetas de servicio AzureKeyVault y AzureActiveDirectory.
Para más información, vea Configuración de red al configurar Azure API Management en una red virtual.
Escenarios admitidos que usan la identidad asignada por el sistema
Obtención de un certificado TLS/SSL personalizado para la instancia de API Management desde Azure Key Vault
Puede usar la identidad asignada por el sistema de una instancia de API Management para recuperar los certificados de TLS/SSL personalizados almacenados en Azure Key Vault. Después, puede asignar estos certificados a dominios personalizados en la instancia de API Management. Tenga en cuenta las consideraciones siguientes:
- El tipo de contenido del secreto debe ser application/x-pkcs12. Más información sobre los requisitos de certificado del dominio personalizado.
- Use el punto de conexión del secreto de certificado de Key Vault, que contiene el secreto.
Importante
Si no se proporciona la versión del objeto del certificado, API Management obtendrá automáticamente la versión más reciente del certificado dentro del plazo de cuatro horas a partir de que se cargue en Key Vault.
En el ejemplo siguiente se muestra una plantilla de Azure Resource Manager que usa la identidad administrada asignada por el sistema de una instancia de servicio de API Management para recuperar un certificado de dominio personalizado de Key Vault.
Prerrequisitos
- Una instancia de servicio de API Management configurada con una identidad administrada asignada por el sistema. Para crear la instancia, puede usar una plantilla de inicio rápido de Azure.
- Una instancia de Azure Key Vault en el mismo grupo de recursos, que hospeda un certificado que se usará como certificado de dominio personalizado en API Management.
La plantilla siguiente contiene estos pasos.
- Actualización de las directivas de acceso de la instancia de Azure Key Vault y permiso para que la instancia de API Management obtenga secretos de ella.
- Actualización de la instancia de API Management al establecer un nombre de dominio personalizado mediante el certificado de la instancia de Key Vault.
Al ejecutar la plantilla, proporcione los valores de parámetro adecuados para su entorno.
{
"$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"
}
}]
}
}
}
]
}
Almacenamiento y administración de valores con nombre en Azure Key Vault
Puede usar una identidad administrada asignada por el sistema para acceder a Azure Key Vault para almacenar y administrar secretos y usarlos en directivas de API Management. Para más información, consulte Uso de valores con nombre en las directivas de Azure API Management.
Autenticación en un back-end mediante una identidad de API Management
Puede usar la identidad asignada por el sistema para autenticarse en un servicio de back-end mediante la directiva authentication-managed-identity.
Conexión a recursos de Azure detrás del firewall de IP mediante una identidad administrada asignada por el sistema
API Management es un servicio de confianza de Microsoft para los siguientes recursos. Esto permite que el servicio se conecte a los siguientes recursos detrás de un firewall. Después de asignar explícitamente el rol de Azure adecuado a la identidad administrada asignada por el sistema para esa instancia de recurso, el ámbito de acceso para la instancia corresponde al rol de Azure asignado a la identidad administrada.
| Servicio de Azure | Vínculo |
|---|---|
| Azure Key Vault | Acceso de confianza a Azure Key Vault |
| Azure Storage | Acceso de confianza a Azure Storage |
| Azure Service Bus | Acceso de confianza a Azure Service Bus |
| Azure Event Hubs | Trusted-access-to-azure-event-hub |
Registro de eventos en un centro de eventos
Puede configurar y usar una identidad administrada asignada por el sistema para acceder a un centro de eventos para registrar eventos desde una instancia de API Management. Para obtener más información, consulte Cómo registrar eventos en Azure Event Hubs en Azure API Management.
Crear una identidad administrada asignada por el usuario
Nota
Puede asociar una instancia de API Management con hasta 10 identidades administradas asignadas por el usuario.
Azure portal
Para configurar una identidad administrada en el portal, primero tendrá que crear una instancia de API Management y una identidad asignada por el usuario. Después, habilite la característica.
Cree una instancia de API Management en el portal como lo haría normalmente. Búsquela en el portal.
En el menú de la izquierda, en Seguridad, seleccione Identidades administradas.
En la pestaña Usuario asignado, seleccione Agregar.
Busque la identidad que creó anteriormente y selecciónela. Seleccione Agregar.
Azure PowerShell
Nota:
Se recomienda usar el módulo Azure Az de PowerShell para interactuar con Azure. Para comenzar, consulte Instalación de Azure PowerShell. Para más información sobre cómo migrar al módulo Az de PowerShell, consulte Migración de Azure PowerShell de AzureRM a Az.
Los siguientes pasos le guiarán por la creación de una instancia de API Management y la asignación de una identidad a esta mediante Azure PowerShell.
Si es necesario, instale Azure PowerShell con las instrucciones que se encuentra en la Guía de Azure PowerShell. Luego, ejecute
Connect-AzAccountpara crear una conexión con Azure.Use el código siguiente para crear la instancia. Para ver más ejemplos de cómo utilizar Azure PowerShell con la instancia de API Management, consulte los ejemplos de PowerShell de API Management.
# 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
También puede actualizar un servicio existente para que asigne una identidad al servicio:
# 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
Plantilla del Administrador de recursos de Azure
Puede crear una instancia de API Management con una identidad mediante la inclusión de la siguiente propiedad en la definición de recursos:
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {}
}
}
Al agregar el tipo asignado por el usuario se indica a Azure que use la identidad asignada por el usuario especificada para la instancia.
Por ejemplo, una plantilla de Azure Resource Manager completa podría tener el aspecto siguiente:
{
"$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'))]"
]
}]
}
Cuando se crea el servicio, tiene las siguientes propiedades adicionales:
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {
"principalId": "<PRINCIPALID>",
"clientId": "<CLIENTID>"
}
}
}
La propiedad principalId es un identificador único para la identidad que se utiliza para la administración de Microsoft Entra. El la propiedad clientId es un identificador único de la nueva identidad de la aplicación que se usa para especificar qué identidad utilizar durante las llamadas de runtime.
Nota
Una instancia de API Management puede tener identidades asignadas por el sistema y asignadas por el usuario al mismo tiempo. En este caso, la propiedad type sería SystemAssigned,UserAssigned.
Escenarios admitidos que usan la identidad administrada asignada por el usuario
Obtención de un certificado TLS/SSL personalizado para la instancia de API Management desde Azure Key Vault
Puede usar una identidad asignada por el usuario para establecer la confianza entre una instancia de API Management y Azure Key Vault. Esta confianza se puede usar para recuperar los certificados TLS/SSL personalizados almacenados en Azure Key Vault. Después, puede asignar estos certificados a dominios personalizados en la instancia de API Management.
Importante
Si el firewall de Key Vault está habilitado en el almacén de claves, no puede usar una identidad asignada por el usuario para el acceso desde API Management. En su lugar, puede usar la identidad asignada por el sistema. En el firewall de Key Vault, debe habilitar también la opción ¿Quiere permitir que los servicios de confianza de Microsoft puedan omitir este firewall?
Tenga en cuenta las consideraciones siguientes:
- El tipo de contenido del secreto debe ser application/x-pkcs12.
- Use el punto de conexión del secreto de certificado de Key Vault, que contiene el secreto.
Importante
Si no se proporciona la versión del objeto del certificado, API Management obtendrá automáticamente la versión más reciente del certificado dentro del plazo de cuatro horas a partir de que se cargue en Key Vault.
Almacenamiento y administración de valores con nombre en Azure Key Vault
Puede usar una identidad administrada asignada por el usuario para acceder a Azure Key Vault para almacenar y administrar secretos y usarlos en directivas de API Management. Para más información, consulte Uso de valores con nombre en las directivas de Azure API Management.
Nota
Si el firewall de Key Vault está habilitado en el almacén de claves, no puede usar una identidad asignada por el usuario para el acceso desde API Management. En su lugar, puede usar la identidad asignada por el sistema. En el firewall de Key Vault, debe habilitar también la opción ¿Quiere permitir que los servicios de confianza de Microsoft puedan omitir este firewall?
Autenticación en un back-end mediante una identidad asignada por el usuario
Puede usar la identidad asignada por el usuario para autenticarse en un servicio de back-end mediante la directiva authentication-managed-identity.
Registro de eventos en un centro de eventos
Puede configurar y usar una identidad administrada asignada por el usuario para acceder a un centro de eventos y registrar eventos desde una instancia de API Management. Para obtener más información, consulte Cómo registrar eventos en Azure Event Hubs en Azure API Management.
Quitar una identidad
Para quitar una identidad asignada por el sistema, puede deshabilitar la característica a través del portal o de la plantilla de Azure Resource Manager de la misma manera en que la creó. Las identidades asignadas por el usuario se pueden quitar individualmente. Para quitar todas las identidades, establezca el tipo de identidad en "None".
Al quitar una identidad asignada por el sistema de esta manera, también se eliminará de Microsoft Entra ID. Las identidades asignadas por el sistema también se quitan automáticamente de Microsoft Entra ID cuando se elimina la instancia de API Management.
Para quitar todas las identidades mediante la plantilla de Azure Resource Manager, actualice esta sección:
"identity": {
"type": "None"
}
Importante
Si una instancia de API Management se configura con un certificado SSL personalizado de Key Vault e intenta deshabilitar una identidad administrada, se producirá un error en la solicitud.
Para desbloquearse, puede cambiar de un certificado de Azure Key Vault a un certificado codificado insertado y, a continuación, deshabilitar la identidad administrada. Para obtener más información, consulte Configuración de un nombre de dominio personalizado.
Pasos siguientes
Obtenga más información sobre las identidades administradas para recursos de Azure: