Compartir a través de

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 el identificador de Entra de Microsoft permite a API Management acceder fácilmente y de forma segura a otros recursos protegidos por Microsoft Entra, como Azure Key Vault. Azure administra estas identidades, por lo que 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 en el que 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, debe volver a crear y volver a 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

Portal de Azure

Para configurar una identidad administrada en Azure Portal, cree una instancia de API Management y, a continuación, habilite la característica.

  1. Cree una instancia de API Management en el portal como lo haría normalmente. Vaya a ella 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 el estado a Activado. Seleccione Guardar.

    Captura de pantalla que muestra cómo habilitar una identidad administrada asignada por el sistema.

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 pasos siguientes le llevan a crear una instancia de API Management y asignarle una identidad mediante Azure PowerShell.

  1. Si lo necesita, instale Azure PowerShell siguiendo las instrucciones de 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 una instancia con una identidad administrada asignada por el sistema. Para obtener más ejemplos de cómo usar Azure PowerShell con API Management, consulte 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 de Azure Resource Manager (ARM)

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 de plantilla de ARM:

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

Esta propiedad indica a Azure que cree y administre la identidad de la instancia de API Management.

Por ejemplo, una plantilla de ARM completa podría tener este aspecto:

{
    "$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. En ese escenario, la type propiedad es SystemAssigned,UserAssigned.

Configuración del acceso a Key Vault mediante una identidad administrada

Las siguientes configuraciones son necesarias si desea usar API Management para acceder a los certificados desde un almacén de claves de Azure.

Configuración del acceso al almacén de claves

  1. En el portal, vaya al almacén de claves.
  2. En el menú de la izquierda, seleccione Configuración de acceso. Tenga en cuenta el modelo de permisos configurado.
  3. 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 del almacén de claves:

  1. En el menú de la izquierda, seleccione Directivas de acceso.
  2. En la página Directivas de acceso, seleccione + Crear.
  3. En la pestaña Permisos , en Permisos secretos, seleccione Obtener y enumerar y, a continuación, seleccione Siguiente.
  4. En la pestaña Principal, seleccione Principal, busque el nombre del recurso de su identidad administrada y, a continuación, seleccione Siguiente. Si usa una identidad asignada por el sistema, la entidad de seguridad es el nombre de la instancia de API Management.
  5. Seleccione Siguiente de nuevo. En la pestaña Revisar y crear, seleccione Crear.

Para configurar el acceso RBAC de Azure:

  1. En el menú izquierdo, seleccione Control de acceso (IAM) .
  2. En la página Control de acceso (IAM), seleccione Agregar asignación de roles.
  3. En la pestaña Rol, seleccione Usuario de certificado de Key Vault.
  4. En la pestaña Miembros, seleccione Identidad administrada>+Seleccionar miembros.
  5. En la ventana Seleccionar identidades administradas , seleccione la identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario asociada a la instancia de API Management y, a continuación, haga clic en Seleccionar.
  6. Seleccione Revisar y asignar.

Requisitos de firewall de Key Vault

Si el firewall de Key Vault está habilitado en el almacén de claves, debe cumplir estos requisitos:

  • Debe usar la identidad administrada asignada por el sistema de la instancia de API Management para acceder al almacén de claves.

  • 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:

Para más información, consulte Configuración de red al configurar API Management en una red virtual.

Escenarios admitidos que usan la identidad asignada por el sistema

A continuación se muestran algunos escenarios comunes para usar una identidad administrada asignada por el sistema en Azure API Management.

Obtención de un certificado TLS/SSL personalizado para la instancia de API Management desde Key Vault

Puede usar la identidad asignada por el sistema de una instancia de API Management para recuperar certificados TLS/SSL personalizados almacenados en Key Vault. Después, puede asignar estos certificados a dominios personalizados en la instancia de API Management. Tenga en cuenta estas consideraciones:

  • El tipo de contenido del secreto debe ser application/x-pkcs12. Para obtener más información, consulte Opciones de certificado de dominio.
  • Debe usar el punto de conexión del secreto de certificado de Key Vault, que contiene el secreto.

Importante

Si no proporciona la versión del objeto del certificado, API Management obtiene automáticamente cualquier versión más reciente del certificado en un plazo de cuatro horas después de actualizarlo en Key Vault.

En el ejemplo siguiente se muestra una plantilla de ARM que usa la identidad administrada asignada por el sistema de una instancia de API Management para recuperar un certificado de dominio personalizado de Key Vault.

Prerrequisitos

  • Una instancia 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 Key Vault en el mismo grupo de recursos. La instancia debe hospedar un certificado que se usará como certificado de dominio personalizado en API Management.

La plantilla contiene los pasos siguientes.

  1. Actualice las directivas de acceso de la instancia de Key Vault y permita 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 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"
					}
				}]
		}
		}
	}
]
}

Almacenamiento y administración de valores con nombre desde Key Vault

Puede usar una identidad administrada asignada por el sistema para acceder a Key Vault para almacenar y administrar secretos para su uso en las 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 back-end mediante la directiva authentication-managed-identity .

Conexión a recursos de Azure detrás de un firewall de IP mediante una identidad administrada asignada por el sistema

API Management es un servicio de confianza de Microsoft para los siguientes recursos. Este estado de confianza permite al servicio conectarse 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 una instancia de recurso, el ámbito de acceso de la instancia corresponde al rol de Azure asignado a la identidad administrada.

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 más información, consulte Registro de eventos en 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.

Portal de Azure

Para configurar una identidad administrada en el portal, primero debe crear una instancia de API Management y crear una identidad asignada por el usuario. A continuación, complete los pasos siguientes.

  1. Vaya a la instancia de API Management 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.

    Captura de pantalla que muestra cómo habilitar una identidad administrada asignada por el usuario.

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 pasos siguientes le llevan a crear una instancia de API Management y asignarle una identidad mediante Azure PowerShell.

  1. Si lo necesita, instale Azure PowerShell siguiendo las instrucciones de 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 obtener más ejemplos de cómo usar Azure PowerShell con API Management, consulte Ejemplos de PowerShell de API Management.

    # 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

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 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

Plantilla ARM

Puede crear una instancia de API Management que tenga una identidad mediante la inclusión de la siguiente propiedad en la definición de recursos:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

Agregar el tipo asignado por el usuario indica a Azure que use la identidad asignada por el usuario que se especifica para su instancia.

Por ejemplo, una plantilla de ARM completa podría tener este aspecto:

{
    "$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. En ese escenario, la type propiedad sería SystemAssigned,UserAssigned.

Escenarios admitidos que usan identidades administradas asignadas por el usuario

A continuación se muestran algunos escenarios comunes para usar una identidad administrada asignada por el usuario en Azure API Management.

Obtención de un certificado TLS/SSL personalizado para la instancia de API Management desde Key Vault

Puede usar una identidad asignada por el usuario para establecer la confianza entre una instancia de API Management y Key Vault. Esta confianza se puede usar para recuperar certificados TLS/SSL personalizados almacenados en 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 habilitarse la opción Permitir que los servicios de Microsoft de confianza omitan esta opción de firewall.

Tenga en cuenta estas consideraciones:

  • El tipo de contenido del secreto debe ser application/x-pkcs12.
  • Debe usar el punto de conexión del secreto de certificado de Key Vault, que contiene el secreto.

Importante

Si no proporciona la versión del objeto del certificado, API Management obtiene automáticamente cualquier versión más reciente del certificado en un plazo de cuatro horas después de actualizarlo en Key Vault.

Almacenamiento y administración de valores con nombre desde Key Vault

Puede usar una identidad administrada asignada por el usuario para acceder a Key Vault para almacenar y administrar secretos para su uso en las 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 habilitarse la opción Permitir que los servicios de Microsoft de confianza omitan esta opción de 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 posterior 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 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.

Quitar una identidad

Puede quitar una identidad asignada por el sistema deshabilitando la característica a través del portal o una plantilla de ARM de la misma manera que se 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 elimina 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 una plantilla de ARM, actualice esta sección:

"identity": {
    "type": "None"
}

Importante

Si una instancia de API Management está configurada con un certificado SSL personalizado de Key Vault e intenta deshabilitar una identidad administrada, se produce un error en la solicitud.

Para resolverlo, cambie de un certificado de Key Vault a un certificado codificado en línea y, a continuación, deshabilite la identidad administrada. Para obtener más información, consulte Configuración de un nombre de dominio personalizado.

Contenido relacionado