Publicación de las API de Microsoft Azure Data Manager for Energy en una puerta de enlace de API protegida
Azure API Management sirve como intermediario fundamental entre las aplicaciones cliente y las API de back-end. Facilita a los clientes el acceso a servicios ocultando los detalles técnicos y proporcionando a las organizaciones control sobre la seguridad de API.
Al publicar las API de Azure Data Manager for Energy a través de Azure API Management, puede usar la funcionalidad Private Link de Azure Data Manager for Energy para el tráfico privado y quitar completamente el acceso público directo a su instancia.
En este artículo se describe cómo configurar Azure API Management para proteger las API de Azure Data Manager for Energy.
Requisitos previos
Necesitará los componentes, las herramientas y la información siguientes disponibles para completar este tutorial:
una red virtual con dos subredes disponibles, una para el punto de conexión privado de Azure Data Manager for Energy y la otra para la inserción de red virtual de API Management.
Azure Data Manager for Energy configurado con vínculo privado implementado en la subred.
Azure API Management aprovisionado e implementado en la red virtual mediante inserción de red virtual. Seleccione el modo Externo o vea la sección Otras opciones para el modo Interno.
Editor de código como Visual Studio Code para modificar las especificaciones de OpenAPI de Azure Data Manager for Energy para cada una de las API publicadas.
Descargue las especificaciones de OpenAPI de Azure Data Manager for Energy desde el repositorio de GitHub adme-samples. Vaya al directorio rest-apis y seleccione la versión adecuada para la aplicación.
En el registro de aplicaciones de la aplicación de Azure Data Manager for Energy que se usó en el momento del aprovisionamiento, observe el id. de inquilino y el id. de cliente:
Preparación de la instancia de API Management
Use los pasos siguientes para realizar cambios de configuración en la instancia de API Management:
En el panel Todos los recursos, elija la instancia de Azure API Management que se usa para este tutorial.
Vaya a la página Configuración de los productos al seleccionarla en la agrupación de configuración de la API:
En la página Productos, seleccione el botón Agregar para crear un nuevo producto. Productos de Azure API Management permiten crear una agrupación de acoplamiento flexible de API que se pueden regular y administrar de forma conjunta. Creamos un producto para nuestras API de Azure Data Manager for Energy.
En la página Agregar producto, escriba los valores que se describen en la tabla siguiente para crear el producto.
Configuración Value Nombre "Producto de Azure Data Manager for Energy" ID "adme-product" Descripción Escriba una descripción que indique a los desarrolladores qué API agrupamos. Publicado Active esta casilla para publicar el producto que creamos. Requiere suscripción Active esta casilla para proporcionar una autorización básica para nuestras API. Requiere aprobación Opcionalmente, seleccione si quiere que un administrador revise y acepte o rechace los intentos de suscripción a este producto. Si no se selecciona, los intentos de suscripción se aprueban automáticamente. Límite de recuento de suscripciones Tiene la opción de limitar el número de varias suscripciones simultáneas. Términos legales Opcionalmente, defina los términos de uso del producto que deben aceptar los suscriptores para usarlo. API existentes Podemos pasar por alto esta característica. Asociamos API más adelante en este artículo Seleccione Crear para crear el producto.
Una vez finalizada la creación del producto, el portal le devuelve a la página Productos. Seleccione nuestro producto recién creado Producto de Azure Data Manager for Energy para ir a la página de recursos del producto. Seleccione el elemento de menú de configuración de directivas en el menú de configuración.
En el panel de procesamiento de entrada, seleccione el icono </>, que permite modificar directivas para el producto. Agregue tres conjuntos de directivas para mejorar la seguridad de la solución:
- Validación del token de Entra ID para asegurarse de que se detectan solicitudes no autenticadas en la puerta de enlace de API
- Cuota y Límite de frecuencia para controlar la tasa de solicitudes y el total de solicitudes o datos transferidos
- Establecimiento de encabezado para quitar encabezados devueltos por API de back-end, lo que podría revelar detalles confidenciales a posibles delincuentes
Agregue la siguiente directiva validate-azure-ad-token a nuestra configuración dentro de las etiquetas de entrada y debajo de la etiqueta base. Asegúrese de actualizar la plantilla con los detalles de la aplicación de Microsoft Entra ID que se indican en los requisitos previos.
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>Debajo de la directiva validate-azure-ad-token, agregue las siguientes directivas quota y rate-limit. Actualice los valores de configuración de directivas según corresponda para los consumidores.
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />En la sección de salida del editor de directivas y debajo de la etiqueta base, agregue las siguientes directivas set-header.
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />Seleccione Guardar para confirmar los cambios.
Vuelva al recurso de API Management en Azure Portal. Seleccione el elemento de menú Back-end y seleccione el botón + Agregar.
En la ventana modal Back-end, escriba los valores descritos en la tabla siguiente para crear el back-end.
Configuración Value Nombre "adme-backend" Descripción Escriba una descripción que indique a los desarrolladores que este back-end está relacionado con las API de Azure Data Manager for Energy. Tipo Dirección URL personalizada URL del runtime Escriba el URI de Azure Data Manager for Energy _ex. https://INSERT_ADME_NAME.energy.azure.com/Validar cadena de certificados Activada Validar nombre del certificado Activada 
Seleccione Crear para crear el back-end. Este back-end recién creado se usará en la sección siguiente cuando publiquemos API.
Importación de API de Azure Data Manager for Energy
Siga estos pasos para importar, configurar y publicar API de Azure Data Manager for Energy en la puerta de enlace de Azure API Management:
Vuelva a la instancia de Azure API Management que se usa en la última sección.
Seleccione el el elemento de menú API en el menú y, a continuación, seleccione el botón + Agregar API.
Seleccione OpenAPI en el encabezado Crear a partir de la definición.
En la ventana modal Crear a partir de la especificación OpenAPI, seleccione el botón de alternancia Completo.
Busque las especificaciones de OpenAPI que descargó como parte de los requisitos previos y abra la especificación Esquema mediante el editor de código que prefiera. Busque la palabra "servidor" y anote la dirección URL del servidor en el archivo, por ejemplo, /api/schema-service/v1/.
Seleccione Seleccionar un archivo y seleccione la especificación de la API de esquema. Una vez completada la carga, la ventana modal carga algunos valores de la especificación.
Para los demás campos, escriba los valores descritos en la tabla siguiente:
Configuración Valor Inclusión de los parámetros de consulta necesarios en las plantillas de operación Activada Nombre para mostrar Escriba un nombre para mostrar que tenga sentido para los desarrolladores de aplicaciones, por ejemplo, Servicio de esquema de Azure Data Manager for Energy. Nombre API Management sugiere un nombre en formato kebab. Opcionalmente, el nombre se puede cambiar, pero debe ser único para la instancia. Descripción La especificación de OpenAPI podría definir una descripción; si es así, la descripción se rellena automáticamente. Opcionalmente, actualice la descripción según el caso de uso. Esquema URL Seleccione "Ambos". Sufijo de dirección URL de API Escriba un sufijo para todas las API de Azure Data Manager for Energy (por ejemplo, adme). A continuación, escriba la dirección URL del servidor del paso 5. El valor final debe ser similar a /adme/api/schema-service/v1/. Un sufijo nos permite ser compatibles con los clientes existentes y kits de desarrollo de software que normalmente se conectan a API de Azure Data Manager for Energy directamente. Etiquetas Opcionalmente, escriba etiquetas. Productos Seleccione el producto "Azure Data Manager for Energy" creado en la sección anterior. Importante
Valide el sufijo de dirección URL de API, se trata de una causa común de errores al publicar las API de Azure Data Manager for Energy.
Seleccione Crear para crear la fachada de la API.
Seleccione la fachada de la API de esquema recién creada en la lista de API y seleccione Todas las operaciones en la lista de operaciones. En el panel de procesamiento de entrada, seleccione el icono </> para editar el documento de directiva.
Para configurar la API, agregue dos conjuntos de directivas:
- Establecimiento del servicio back-end para enrutar las solicitudes a la instancia de Azure Data Manager for Energy
- URI de reescritura para quitar el prefijo adme y compilar la solicitud a la API de back-end. Esta instrucción de directiva usa expresiones de directiva para agregar dinámicamente el valor de la plantilla de dirección URL de la operación actual a nuestra dirección URL del servidor.
Anote la dirección URL del servidor del paso 5. Debajo de la etiqueta base, en la sección de entrada, inserte las dos instrucciones de directiva siguientes.
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />Seleccione Guardar para confirmar los cambios.
Para probar la API, seleccione la operación de obtención de información de la versión en la lista de operaciones. A continuación, seleccione la pestaña Prueba para ir a la consola de prueba de Azure API Management.
Escriba los valores que se describen en la tabla siguiente. Genere un token de autenticación para su instancia de Azure Data Manager for Energy. Seleccione Enviar para probar la API.
Configuración Valor data-partition-id Identificador de partición de datos para su instancia de Azure Data Manager for Energy Producto Seleccione el producto de Azure Data Manager for Energy creado anteriormente. Authorization "Portador" y token de autenticación que ha generado 
Si la API está configurada correctamente, debería ver una respuesta HTTP 200 (correcto) similar a la captura de pantalla. Si no es así, compruebe la sección Solución de problemas.
Repita los pasos anteriores para cada API de Azure Data Manager for Energy y la especificación asociada.
Solución de problemas
Durante las pruebas de las API a través de Azure API Management, si se producen errores, normalmente apuntan a problemas de configuración. En función del error, revise los posibles pasos de resolución.
| Código | Mensaje de error | Detalles |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
Asegúrese de que tiene un encabezado de autenticación válido para el inquilino de Microsoft Entra ID y una aplicación cliente para su instancia de Azure Data Manager for Energy. |
HTTP 401 Unauthorized |
Azure AD JWT not present |
Asegúrese de que el encabezado de autenticación se agrega a la solicitud de prueba. |
HTTP 404 Not Found |
Este error normalmente significa que la solicitud a la API de back-end se realiza en la dirección URL equivocada. Haga un seguimiento de la solicitud de API en API Management para conocer qué dirección URL se genera para la solicitud de back-end y asegúrese de que es válida. Si no lo es, compruebe la directiva url-rewrite o el back-end. | |
HTTP 500 Internal Server Error |
Internal server error |
Este error normalmente refleja un problema al realizar solicitudes a la API de back-end. Normalmente, en este escenario, el problema está relacionado con los servicios de nombres de dominio (DNS). Compruebe que hay una zona DNS privada configurada en las redes virtuales o que su resolución de DNS personalizada tiene los reenviadores adecuados. Haga un seguimiento de la solicitud de API en API Management para conocer qué solicitud de back-end se ha realizado y qué errores notifica API Management al intentar realizar la solicitud. |
Otras consideraciones
Modo de red virtual interna de API Management
El modo interno aísla completamente Azure API Management en lugar de exponer los puntos de conexión a través de una dirección IP pública. En esta configuración, las organizaciones pueden asegurarse de que Azure Data Manager for Energy es interno en su totalidad. Dado que Azure Data Manager for Energy es una solución de colaboración para trabajar con asociados y clientes, este escenario podría no ser beneficioso tal y como está.
App Gateway con firewall de aplicaciones web
En lugar de usar el modo de red virtual interna solo, muchas organizaciones optan por aplicar un mecanismo de aplicación de un proxy inverso protegido para exponer la instancia de Azure API Management de modo interno a asociados y clientes externos. La instancia de modo interno permanece completamente aislada con una entrada estrechamente controlada que debe pasar por el proxy.
Azure App Gateway es un servicio común que se usa como proxy inverso. Azure App Gateway también tiene una funcionalidad de firewall de aplicaciones web (WAF), que detecta activamente posibles ataques contra vulnerabilidades en las aplicaciones y las API.
Configuración de Azure API Management con un dominio personalizado
Otra característica común de esta arquitectura es aplicar un dominio personalizado a las API. Aunque Azure Data Manager for Energy no admite esta característica, puede configurar un dominio personalizado en Azure API Management en su lugar.
Un certificado del dominio es un requisito previo. Sin embargo, Azure API Management admite la creación de certificados administrados gratuitos para el dominio personalizado.