Suscripciones en Azure API Management

  • Artículo

SE APLICA A: todos los niveles de API Management

En Azure API Management, las suscripciones son la forma más habitual de acceso a las API publicadas por medio de una instancia de API Management para los consumidores. En este artículo se proporciona información general del concepto.

Nota:

Una suscripción de API Management se usa específicamente para llamar a las API a través de API Management utilizando una clave de suscripción. No es lo mismo que una suscripción de Azure.

¿Qué son las suscripciones?

Si publica API por medio de API Management, puede proteger fácilmente el acceso a las API mediante claves de suscripción. Los desarrolladores que necesiten usar las API publicadas deben incluir una clave de suscripción válida en las solicitudes HTTP al realizar llamadas a esas API. Sin una clave de suscripción válida, las llamadas:

  • Se rechazan inmediatamente por la puerta de enlace de API Management.
  • No se reenvían a los servicios back-end.

Para acceder a las API, los desarrolladores necesitan una suscripción y una clave de suscripción. Una suscripción es un contenedor con nombre para un par de claves de suscripción.

Además:

  • Los desarrolladores pueden obtener suscripciones sin que sea necesaria la aprobación de los publicadores de API.
  • Los publicadores de API pueden crear suscripciones directamente para los consumidores de API.

Sugerencia

API Management también admite otros mecanismos para proteger el acceso a las API, por ejemplo:

Administrar claves de suscripción

La regeneración periódica de claves es una precaución de seguridad común. Al igual que la mayoría de los servicios de Azure que requieren una clave de suscripción, API Management genera claves en pares. Cada aplicación que usa el servicio puede cambiar de la clave A a la clave B y regenerar la clave A con una interrupción mínima, y viceversa.

Para establecer claves específicas en lugar de volver a generarlas, puede invocar la suscripción de Azure API Management: crear o actualizar la API REST de Azure. En concreto, es necesario establecer properties.primaryKeyproperties.secondaryKey en el cuerpo de la solicitud HTTP.

Nota:

  • API Management no proporciona características integradas para administrar el ciclo de vida de las claves de suscripción, como establecer fechas de expiración o rotar automáticamente las claves. Puede desarrollar flujos de trabajo para automatizar estos procesos mediante herramientas como Azure PowerShell o los SDK de Azure.
  • Para aplicar el acceso limitado a las API, los publicadores de API pueden usar directivas con claves de suscripción o bien usar un mecanismo que proporcione expiración integrada, como la autenticación basada en tokens.

Ámbito de las suscripciones

Las suscripciones se pueden asociar a diversos ámbitos: producto, todas las API o una API individual.

Suscripciones para un producto

Tradicionalmente, las suscripciones de API Management se han asociado a un solo ámbito de producto. Desarrolladores:

  • Encontraban la lista de productos en el portal para desarrolladores.
  • Enviaban las solicitudes de suscripción de los productos que querían usar.
  • Usaban las claves de esas suscripciones (aprobadas automáticamente o por publicadores de API) para acceder a todas las API del producto.

En este momento, en la sección Perfil de usuario del portal para desarrolladores solo aparecen las suscripciones del ámbito del producto.

Suscripciones de producto

Suscripciones para todas las API o una API individual

También puede crear claves que concedan acceso a:

  • una sola API, o
  • todas las API dentro de una instancia de API Management.

En estos casos, no es necesario crear un producto y agregarle API primero.

Suscripción de acceso completo

Cada instancia de API Management viene con una suscripción de acceso total integrada que concede acceso a todas las API. Esta suscripción de ámbito de servicio facilita y agiliza a los propietarios de servicios la prueba y depuración de las API en la consola de pruebas.

Advertencia

La suscripción de acceso completo permite el acceso a todas las API de la instancia de API Management y solo deben usarse los usuarios autorizados. Nunca use esta suscripción para el acceso de API rutinario o inserte la clave de suscripción de acceso completo en las aplicaciones cliente.

Nota:

Si usa una suscripción con ámbito de API, una suscripción a todas las API o la suscripción integrada de acceso completo, las directivas configuradas en el ámbito del producto no se aplican a las solicitudes de esa suscripción.

Suscripciones independientes

API Management también permite suscripciones independientes, que no están asociadas a una cuenta de desarrollador. Esta característica resulta útil en escenarios similares a cuando varios desarrolladores o equipos comparten una suscripción.

La creación de una suscripción sin asignarle un propietario la convierte en una suscripción independiente. Para conceder a los desarrolladores y al resto del equipo acceso a la clave de suscripción independiente:

  • Comparta manualmente la clave de suscripción.
  • Use un sistema personalizado para poner a disposición del equipo la clave de suscripción.

Creación y administración de suscripciones en Azure Portal

Los publicadores de API pueden crear suscripciones directamente en Azure Portal.

Cuando se crea en el portal, una suscripción está en estado Activo, lo que significa que cualquier suscriptor puede llamar a una API asociada mediante una clave de suscripción válida. Puede cambiar el estado de la suscripción según sea necesario. Por ejemplo, puede suspender, cancelar o eliminar cualquier suscripción (incluida la suscripción de acceso completo integrada) para evitar el acceso a la API.

Uso de una clave suscripción

Un suscriptor puede usar una clave de suscripción de API Management de una de estas dos maneras:

  • Agregue el encabezado HTTP Ocp-Apim-Subscription-Key a la solicitud y pase el valor de una clave de suscripción válida.

  • Incluya el parámetro de consulta subscription-key y un valor válido en la dirección URL. El parámetro de consulta solo se comprueba si el encabezado no está presente.

Sugerencia

Ocp-Apim-Subscription-Key es el nombre predeterminado del encabezado de clave de suscripción y subscription-key es el nombre predeterminado del parámetro de consulta. Si lo desea, puede modificar estos nombres en la configuración de cada API. Por ejemplo, en el portal, actualice estos nombres en la pestaña Configuración de una API.

Nota:

Cuando se incluye en un encabezado de solicitud o un parámetro de consulta, la clave de suscripción se pasa de forma predeterminada al backend y se puede exponer en registros de supervisión de backend u otros sistemas. Si se considera datos confidenciales, puede configurar una directiva al final de la sección inbound para quitar el encabezado de clave de suscripción (set-header) o el parámetro de consulta (set-query-parameter).

Habilitación o deshabilitación del requisito de suscripción para el acceso a la API o al producto

De forma predeterminada, al crear una API, se requiere una clave de suscripción para acceder a ella. De forma similar, al crear un producto, se requiere una clave de suscripción de forma predeterminada para acceder a cualquier API que se agregue a él. En determinados escenarios, es posible que los publicadores de API quieran publicar un producto o una API determinada para el público sin necesidad de suscripciones. Aunque un publicador puede optar por habilitar el acceso no seguro (anónimo) a determinadas API, se recomienda configurar otro mecanismo para proteger el acceso de cliente.

Precaución

Tenga cuidado al configurar un producto o una API que no requiera una suscripción. Esta configuración puede ser excesivamente permisiva y hacer que una API sea más vulnerable a determinadas amenazas de seguridad de API.

Nota:

Los productos abiertos tienen deshabilitada la configuración Requiere suscripción, lo que significa que los usuarios no necesitan suscribirse. Por este motivo, los productos abiertos no se muestran en la página Productos del portal para desarrolladores.

El requisito de suscripción se puede deshabilitar tanto en el momento de creación de una API o un producto, como en una fecha posterior.

Para deshabilitar el requisito de suscripción mediante el portal:

  • Deshabilite el requisito del producto: en la página Configuración del producto, deshabilite Requiere suscripción.
  • Deshabilite el requisito de la API: en la página Configuración de la API, deshabilite Se requiere suscripción.

Después de deshabilitar el requisito de la suscripción, se puede acceder a las API seleccionadas sin una clave de suscripción.

Cómo gestiona API Management solicitudes con o sin claves de suscripción

Solicitud de API con una clave de suscripción

Cuando API Management una solicitud de API de un cliente sin clave de suscripción, la administra según estas reglas:

  1. Compruebe si es una clave válida asociada a una suscripción activa, ya sea:

    • Una suscripción cuyo ámbito es la API.
    • Una suscripción cuyo ámbito es un producto asignado a la API.
    • Una suscripción cuyo ámbito son todas las API.
    • La suscripción cuyo ámbito es el servicio (suscripción de todos los accesos integrada)

    Si se proporciona una clave válida para una suscripción activa con un ámbito adecuado, se permite el acceso. Las directivas se aplican en función de la configuración de la definición de directiva en ese ámbito.

  2. De lo contrario, se deniega el acceso (error 401 Acceso denegado).

Solicitud de API sin clave de suscripción

Cuando API Management una solicitud de API de un cliente sin una clave de suscripción, administra la solicitud según estas reglas:

  1. Comprueba primero la existencia de un producto que incluya la API, pero que no requiera una suscripción (un producto abierto). Si el producto abierto existe, administra la solicitud en el contexto de las API, las directivas y las reglas de acceso configuradas para el producto. Una API se puede asociar como máximo a un producto abierto.
  2. Si no se encuentra un producto abierto que incluya la API, comprueba si la API requiere una suscripción. Si no se requiere una suscripción, controla la solicitud en el contexto de esa API y operación.
  3. Si no se encuentra ningún producto o API configurado, se deniega el acceso (error 401 Acceso denegado).

Tabla de resumen

En la siguiente tabla se resume la forma en que puerta de enlace controla las solicitudes de API con o sin claves de suscripción en diferentes escenarios. Se indican las configuraciones que podrían habilitar el acceso de API anónimo y no deseado.

Todos los productos asignados a la API requieren una suscripción La API requiere suscripción Llamada API con clave de suscripción Llamada API sin clave de suscripción Escenarios típicos
✔️ ✔️ Acceso permitido:

• Clave cuyo ámbito es el producto
• Clave cuyo ámbito es la API
• Clave cuyo ámbito son todas las API
• Clave cuyo ámbito es el servicio

Acceso denegado:

• Otra clave cuyo ámbito no es una API o producto aplicables		 Acceso denegado Acceso de API protegido mediante una suscripción cuyo ámbito es un producto o cuyo ámbito es una API
✔️ ❌ Acceso permitido:

• Clave cuyo ámbito es el producto
• Clave cuyo ámbito es la API
• Clave cuyo ámbito son todas las API
• Clave cuyo ámbito es el servicio

Acceso denegado:

• Otra clave cuyo ámbito no es una API o producto aplicables.		 Acceso permitido (contexto de API). • Acceso de API protegido con una suscripción cuyo ámbito es un producto.

• Acceso anónimo a API. Si no está previsto el acceso anónimo, configure directivas de nivel de API para aplicar la autenticación y la autorización.
❌1 ✔️ Acceso permitido:

• Clave cuyo ámbito es el producto
• Clave cuyo ámbito es la API
• Clave cuyo ámbito son todas las API
• Clave cuyo ámbito es el servicio

Acceso denegado:

• Otra clave cuyo ámbito no es una API o producto aplicables.		 Acceso permitido (contexto de producto abierto) • Acceso de API protegido con una suscripción cuyo ámbito es una API

• Acceso anónimo a API. Si no está previsto el acceso anónimo, realice la configuración con directivas de producto para aplicar la autenticación y la autorización.
❌1 ❌ Acceso permitido:

• Clave cuyo ámbito es el producto
• Clave cuyo ámbito es la API
• Clave cuyo ámbito son todas las API
• Clave cuyo ámbito es el servicio

Acceso denegado:

• Otra clave cuyo ámbito no es una API o producto aplicables.		 Acceso permitido (contexto de producto abierto) Acceso anónimo a API. Si no está previsto el acceso anónimo, realice la configuración con directivas de producto para aplicar la autenticación y la autorización.

1 Existe un producto abierto asociado a la API.

Consideraciones

  • El acceso de API en un contexto de producto es el mismo, independientemente de que el producto se publique o no. Al anular la publicación, el producto lo oculta en el portal para desarrolladores, pero no invalida las claves de suscripción nuevas o existentes.
  • Aunque un producto o una API no requieran una suscripción, se puede usar una clave válida de una suscripción activa que permita el acceso al producto o a la API.
  • El "contexto" del acceso de API significa las directivas y los controles de acceso que se aplican en un ámbito determinado (por ejemplo, API o producto).

Pasos siguientes

Para más información sobre API Management: