Uso de identidades administradas en Azure 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 Azure Active Directory (Azure AD) permite a la instancia de API Management acceder de forma fácil y segura a otros recursos protegidos de Azure AD, 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 Azure AD 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.

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.

1. Cree una instancia de API Management en el portal como lo haría normalmente. Búsquela en el portal.

2. En el menú de la izquierda, en Seguridad, seleccione Identidades administradas.

3. En la pestaña Asignado por el sistema, cambie Estado a Activado. Seleccione Guardar.

   

Azure PowerShell

Nota:

En este artículo se usa el módulo Az de PowerShell, que es el módulo de PowerShell que se recomienda para interactuar con Azure. Para empezar a trabajar con el módulo Az de PowerShell, 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.

1. Si es necesario, instale Azure PowerShell con las instrucciones que se encuentra en la Guía de Azure PowerShell. Luego, ejecute Connect-AzAccount para crear una conexión con Azure.

2. 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 Azure AD pertenece la identidad. La propiedad principalId es un identificador único para la nueva identidad de la instancia. En Azure AD, 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

Consulte las siguientes configuraciones necesarias para que API Management pueda acceder a secretos y certificados de Key Vault.

Configuración de la directiva de acceso de Key Vault

Para configurar una directiva de acceso mediante el portal:

1. En Azure Portal, vaya al almacén de claves.
2. Seleccione Configuración > Directivas de acceso > + Agregar directiva de acceso.
3. Seleccione Permisos de los secretos, seleccione Obtener y Enumerar.
4. En Seleccionar la entidad de seguridad, seleccione el nombre de recurso de la identidad administrada. Si usa una identidad asignada por el sistema, la entidad de seguridad es el nombre de la instancia de API Management.
5. Seleccione Agregar.

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.

1. 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.
2. 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	Acceso de confianza a Azure Event Hub

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.

1. Cree una instancia de API Management en el portal como lo haría normalmente. Búsquela en el portal.

2. En el menú de la izquierda, en Seguridad, seleccione Identidades administradas.

3. En la pestaña Usuario asignado, seleccione Agregar.

4. Busque la identidad que creó anteriormente y selecciónela. Seleccione Agregar.

   

Azure PowerShell

Nota:

En este artículo se usa el módulo Az de PowerShell, que es el módulo de PowerShell que se recomienda para interactuar con Azure. Para empezar a trabajar con el módulo Az de PowerShell, 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.

1. Si es necesario, instale Azure PowerShell con las instrucciones que se encuentra en la Guía de Azure PowerShell. Luego, ejecute Connect-AzAccount para crear una conexión con Azure.

2. 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>"
        }
    }
}

El valor principalId es un identificador único de la identidad que se usa para la administración de Azure AD. 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.

Para ver la plantilla completa, consulte API Management con SSL basado en Key Vault mediante identidades asignadas por el usuario.

En esta plantilla, implementará lo siguiente:

• Una instancia de Azure API Management
• Una identidad administrada asignada por el usuario de Azure
• Azure Key Vault para almacenar el certificado SSL/TLS

Para ejecutar automáticamente la implementación, seleccione el botón siguiente:

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.

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 Azure AD. Las identidades asignadas por el sistema también se quitan automáticamente de Azure AD 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:

• ¿Qué son las identidades administradas de recursos de Azure?
• Plantillas del Administrador de recursos de Azure
• Autenticación con una identidad administrada en una directiva