Uso de valores con nombre en las directivas de Azure API Management

  • Artículo

SE APLICA A: todos los niveles de API Management

Las directivas de API Management constituyen una eficaz funcionalidad del sistema que permite al editor cambiar el comportamiento de la API a través de la configuración. Las directivas son una colección de declaraciones que se ejecutan secuencialmente en la solicitud o respuesta de una API. Las instrucciones de las directivas se pueden crear con valores de texto literal, expresiones de directiva y valores con nombre.

Los valores con nombre son una colección global de pares nombre-valor en cada instancia de API Management. No se impone ningún límite en el número de elementos de la colección. Los valores con nombre se pueden usar para administrar secretos y valores de cadena constantes en todas las directivas y la configuración de API.

Valores con nombre en Azure Portal

Tipos de valor

Tipo Descripción
Normal Cadena literal o expresión de directiva
Secreto Cadena literal o expresión de directiva cifrada por API Management
Key vault Identificador de un secreto almacenado en una instancia de Azure Key Vault.

Los valores normales o los secretos pueden contener expresiones de directiva. Por ejemplo, la expresión @(DateTime.Now.ToString()) devuelve una cadena que contiene la fecha y la hora actuales.

Para obtener más información sobre los atributos de los valores con nombre, consulte la referencia de la API REST de API Management.

Secretos de un almacén de claves

Los valores de los secretos se pueden almacenar como cadenas cifradas en API Management (secretos personalizados) o mediante referencia a secretos en Azure Key Vault.

Se recomienda el uso de secretos de Key Vault, ya que esto ayuda a mejorar la seguridad de API Management:

  • Los secretos almacenados en almacenes de claves se pueden reutilizar entre servicios
  • Se pueden aplicar directivas de acceso pormenorizadas a los secretos
  • Los secretos actualizados en el almacén de claves se rotan automáticamente en API Management. Después de la actualización en el almacén de claves, un valor con nombre en API Management se actualiza en un plazo de 4 horas. También puede actualizar manualmente el secreto mediante Azure Portal o a través de la API REST de administración.

Requisitos previos

Requisitos previos para la integración de un almacén de claves

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 y anote 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 al 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 de secretos, seleccione Obtener y Lista, y luego Siguiente.
    4. 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.
    5. Seleccione Siguiente de nuevo. En la pestaña Revisar y crear, seleccione Crear.

    Para configurar el acceso de Azure RBAC:

    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 secretos de Key Vault.
    4. En la pestaña Miembros, seleccione Identidad administrada>+Seleccionar miembros.
    5. 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.
    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, 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:

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

Adición o edición de un valor con nombre

Agregar un secreto del almacén de claves a API Management

Consulte Requisitos previos para la integración de un almacén de claves.

Importante

Al agregar un secreto de almacén de claves a la instancia de API Management, debe tener permisos para enumerar los secretos del almacén de claves.

Precaución

Al usar un secreto del almacén de claves en API Management, tenga cuidado de no eliminar el secreto, el almacén de claves ni la identidad administrada que se usa para acceder al almacén de claves.

  1. Vaya a la instancia de API Management en Azure Portal.

  2. En API, seleccione Calores con nombre>+Agregar.

  3. Escriba un identificador de Nombre y escriba un Nombre para mostrar que se use para hacer referencia a la propiedad en las directivas.

  4. En Tipo de valor, seleccione Almacén de claves.

  5. Escriba el identificador de un secreto de almacén de claves (sin versión) o elija Seleccionar para seleccionar un secreto de un almacén de claves.

    Importante

    Si especifica usted mismo el identificador de un secreto del almacén de claves, asegúrese de que no tenga la información de versión. De lo contrario, el secreto no se rotará automáticamente en API Management después de una actualización en el almacén de claves.

  6. En Client identity (Identidad del cliente), seleccione una identidad asignada por el sistema o una identidad administrada existente asignada por el usuario. Obtenga información sobre cómo agregar o modificar identidades administradas en el servicio de API Management.

    Nota

    La identidad necesita permisos para obtener y enumerar los secretos del almacén de claves. Si aún no ha configurado el acceso al almacén de claves, API Management se lo pedirá para poder configurar automáticamente la identidad con los permisos necesarios.

  7. Agregue una o varias etiquetas opcionales para ayudar a organizar los valores con nombre y, a continuación, elija Guardar.

  8. Seleccione Crear.

    Adición de un valor de secreto del almacén de claves

Agregar un valor normal o secreto a API Management

  1. Vaya a la instancia de API Management en Azure Portal.
  2. En API, seleccione Calores con nombre>+Agregar.
  3. Escriba un identificador de Nombre y escriba un Nombre para mostrar que se use para hacer referencia a la propiedad en las directivas.
  4. En Tipo de valor, seleccione Normal o Secreto.
  5. En Valor, escriba una cadena o expresión de directiva.
  6. Agregue una o varias etiquetas opcionales para ayudar a organizar los valores con nombre y, a continuación, elija Guardar.
  7. Seleccione Crear.

Una vez creado el valor con nombre, selecciónelo para editarlo. Si cambia el nombre para mostrar, las directivas que hagan referencia a ese valor con nombre se actualizarán automáticamente para utilizar el nuevo nombre para mostrar.

Uso de un valor con nombre

En los ejemplos de esta sección se usan los valores con nombre que aparecen en la tabla siguiente.

Nombre Value Secreto
ContosoHeader TrackingId Falso
ContosoHeaderValue •••••••••••••••••••••• True
ExpressionProperty @(DateTime.Now.ToString()) Falso
ContosoHeaderValue2 This is a header value. Falso

Para utilizar un valor con nombre en una directiva, coloque su nombre para mostrar dentro de un par doble de llaves (como {{ContosoHeader}}), de la misma forma que se muestra en el ejemplo siguiente:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

En este ejemplo, ContosoHeader se utiliza como el nombre de un encabezado en una directiva set-header, y ContosoHeaderValue se utiliza como valor de ese encabezado. Cuando esta directiva se evalúa durante una solicitud o responde a la pasarela de API Management, {{ContosoHeader}} y {{ContosoHeaderValue}} se reemplazan por sus respectivos valores.

Los valores con nombre se pueden utilizar como atributo completo o como valores de elemento (tal como se muestra en el ejemplo anterior), pero también se pueden insertar o combinar con parte de una expresión de texto literal, como en el ejemplo siguiente:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Los valores con nombre también pueden contener expresiones de directiva. En el ejemplo siguiente, se usa la expresión ExpressionProperty.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Cuando se evalúa esta directiva, se reemplaza {{ExpressionProperty}} por su valor, @(DateTime.Now.ToString()). Puesto que el valor es una expresión de directiva, la expresión se evalúa y la directiva continúa con su ejecución.

Para probarlo en Azure Portal o en el portal para desarrolladores, puede llamar a una operación que tenga dentro de su ámbito una directiva con valores con nombre. En el ejemplo siguiente, se llama a una operación con las dos directivas set-header de ejemplo anteriores con valores con nombre. Tenga en cuenta que la respuesta contiene dos encabezados personalizados que se han configurado mediante directivas con valores con nombre.

Prueba de la respuesta de la API

Si busca en el seguimiento de API de salida una llamada que incluya las dos directivas de ejemplo anteriores con valores con nombre, verá las dos directivas set-header con los valores con nombre insertados, así como la evaluación de la expresión de directiva para el valor con nombre que la contiene.

Seguimiento de API Inspector

La interpolación de cadenas también se puede usar con valores con nombre.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

El valor de CustomHeader será The URL encoded value is This+is+a+header+value..

Precaución

Si una directiva hace referencia a un secreto en Azure Key Vault, el valor del almacén de claves será visible para los usuarios que tengan acceso a las suscripciones habilitadas para el seguimiento de solicitudes de API.

Aunque los valores con nombre pueden contener expresiones de directiva, no pueden contener otros valores con nombre. En caso de usarse texto que contenga una referencia a valores con nombre para un valor, como Text: {{MyProperty}}, dicha referencia no se resolverá ni reemplazará.

Eliminación de un valor con nombre

Para eliminar un valor con nombre, seleccione el nombre y, a continuación, seleccione Eliminar en el menú contextual ( … ).

Importante

Si alguna directiva de API Management hace referencia al valor con nombre, no podrá eliminarlo hasta que lo quite de todas las directivas que lo usen.

Pasos siguientes