Norma para el desarrollo de servicios de interoperabilidad

Ámbito de aplicación de la norma

Esta norma se aplica tanto a nuevos desarrollos como a mantenimientos que incluyan la creación o modificación de servicios de integración interoperables.

Las directrices que contiene la norma son independientes de la pila tecnológica que se utilice para la arquitectura de integración. Los objetivos y características de la arquitectura no están vinculados a la tecnología de implementación. 

Por tanto, al implementar una integración en una tecnología específica, hay que cumplir con:

• Las normas y estándares referidos en esta página.
• Otras normas particulares establecidas para dicha tecnología.

Diseño

Reglas y convenciones para la nomenclatura de los servicios y operaciones y para el versionado de las APIs que las exponen

DIR_01 Nomenclatura de las URI de las operaciones

OBLIGATORIO Las URI de las operaciones seguirán esta serie de reglas estándar para su nomenclatura:

• DEBEN usar solo los métodos GET, POST, PUT y DELETE.
  • GET: obtener información del servidor
  • POST: crear un nuevo recurso y, por consiguiente, modifica el estado del servidor
  • PUT: actualizar un recurso
  • PATCH: actualizar parte de un recurso
  • DELETE: eliminar un recurso
• DEBEN de estar orientadas a la exposición de recursos y no de operaciones. /usuarios/{dni}/informes/{idInforme}
• DEBEN usar nomenclatura de campos y parámetros lowerCamelCase. 
• DEBEN usar plurales en los nombres. /usuarios y no /usuario 
• Las URI NO DEBEN implicar una acción, por lo tanto, no se podrán usar verbos en ellas. 
• Han de ser únicas, NO DEBE haber más de una URI para identificar un mismo recurso.
• DEBEN mantener una jerarquía lógica según el aspecto de negocio que trate. 
  • Por ejemplo, la URI /facturas/25/clientes/007 no sería una URI correcta, ya que no sigue una jerarquía lógica de negocio ya que la factura está asociada al cliente y no al revés. 
  • Para el recurso factura con el identificador 25 del cliente 007, la siguiente URI sería la correcta: /clientes/007/facturas/25.
• Los filtrados de información de un recurso NO DEBEN hacerse en la URI. Se realiza concatenando atributos con QueryParam.
  • Incorrecto: /facturas/anio/2024/total/500-1000
  • Correcto: /facturas?anio=2024&total_min=500&total_max=1000
• Los QueryParam y PathParam NO DEBEN contener datos sensibles. En el caso de necesitar enviar datos sensibles, se enviarán dentro del body (si es una consulta, se DEBE configurar como un POST).
• Las fechas DEBEN tener el siguiente formato: YYYY[MM[DD[HH[mm[ss]]]]]
• Se DEBE incluir la versión de la API en la uri: /v1/usuarios

DIR_02 Versionado y retrocompatibilidad

OBLIGATORIO Se creará una nueva versión de la API si se han realizado cambios que afectan a los consumidores de los servicios (no retrocompatibles).:

Cambios no retrocompatibles:

• Eliminar operaciones o acciones sobre un recurso. Ejemplo: Ya no se aceptan peticiones POST sobre un recurso. 
• Añadir nuevos parámetros de entrada obligatorios. Ejemplo: Ahora para dar de alta un recurso hay que enviar en el cuerpo de la petición un nuevo campo requerido.
• Modificar parámetros de entrada de opcional a obligatorio. Ejemplo: Ahora al crear un recurso Persona, el campo edad, que antes era opcional, ahora es obligatorio. 
• Modificar o eliminar un parámetro en operaciones (verbos sobre recursos) ya existentes. Ejemplo: al consultar un recurso ya no se devuelve determinado campo. Otro ejemplo: un campo que antes era una cadena de caracteres ahora es numérico. 
• Añadir nuevas respuestas en operaciones ya existentes. Ejemplo: ahora la creación de un recurso puede devolver un código de respuesta 412.

DIR_03 Retrocompatibilidad

OBLIGATORIO El servicio aceptará las peticiones de las versiones anteriores de la API, por retrocompatiblidad, hasta que se decida eliminarlas.:

Convenciones sobre la estrategia de diseño de los servicios

DIR_04 Estrategia API-first

OBLIGATORIO Se adoptará una estrategia de desarrollo API-first: primero definición del servicio y luego desarrollos.:

Hay que definir las operaciones, métodos y datos del negocio del servicio como fase inicial del análisis, para implementar posteriormente el código.

• Enfoque API-first

Reglas para la distribución de carga

DIR_05 Balanceo de carga

OBLIGATORIO Se establecerán políticas de balanceo de carga para que distribuyan las solicitudes entrantes entre múltiples instancias de un servicio, de tal forma que se evite la sobrecarga en cualquier instancia individual.:

Los servicios statefull DEBEN configurar su política de balanceo de carga teniendo en cuenta la conservación del estado.

Es necesario consultar el Modelo de Despliegue de la arquitectura, puesto que existen casos en las que la aplicación de esta política esté delegada en la infraestructura y, por lo tanto, sólo será necesario la configuración en dicho componente para que se active el balanceo de carga al servicio.

Reglas relacionadas con la resiliencia de los servicios

DIR_06 Resilencia

OBLIGATORIO Se incluirán las siguientes políticas de resiliencia:

• Circuit Breaker: se DEBEN definir las políticas de Circuit Break para detectar y manejar errores en servicios remotos de una manera eficiente. 
• Fallbacks: se RECOMIENDA definir las políticas de Fallbacks para tener planes de contingencia en el caso de que un servicio principal no está disponible.
• Timeouts: se DEBEN definir las políticas de Timeout para establecer límites de tiempo para las solicitudes a servicios remotos, evitando los bloqueos y manteniendo la capacidad de respuesta del sistema.
• Retries: se RECOMIENDA definir las políticas de Retries para ayudar a recuperarse de fallas temporales en las llamadas a servicios remotos y mejorar la disponibilidad del servicio. Es una política que debe de implementarse con cuidado para evitar la sobrecarga del sistema, por lo que se RECOMIENDA su uso exclusivamente en servicios críticos o en casos donde las fallas transitorias sean comunes.
• Bulkheads: se RECOMIENDA definir las políticas de bulkheads de forma que aíslen partes críticas del sistema y limitar el impacto de las fallas. Esto ayuda a prevenir la propagación de errores y garantiza la disponibilidad continua del sistema.

Construcción

Reglas y convenciones relacionadas con el tipo de comunicación

DIR_07 Comunicación síncrona

OBLIGATORIO En el caso de comunicación síncrona, se utilizará la especificación OpenAPI en su versión 3.1.X como estándar para definir las APIs. Además, las comunicaciones se establecerán con alguno de los siguientes protocolos:

• APIs REST: Método estándar que DEBE ser utilizado en la mayoría de los proyectos, proporcionando consistencia y claridad en la definición de las APIs.

  En aquellos casos en los que históricamente los servicios web de un sistema de información sean SOAP y el cambio tecnológico implique un esfuerzo desproporcionado con los beneficios del cambio, se mantendrán los desarrollos de servicios SOAP. Para ello, es necesario contar con el visto bueno de la Oficina de Arquitectura de Soluciones.

• GraphQL: Se RECOMIENDA su uso en proyectos que necesitan proporcionar métodos de búsqueda y exploración de los datos publicados, permitiendo consultas complejas y precisas para acceder a la información.
• gRPC síncrono: Se RECOMIENDA su uso en proyectos que requieren alta velocidad y eficiencia en la comunicación entre servicios, especialmente en entornos donde se prioriza la comunicación síncrona con bajo tiempo de latencia.

Se DEBE tener en cuenta que OpenAPI puede adaptarse para describir APIs basadas en GraphQL o gRPC, aunque es posible que no cubra todas las características específicas de estos protocolos. Por lo tanto, se RECOMIENDA realizar una evaluación detallada para asegurarse de que la descripción de la API se ajuste adecuadamente al protocolo utilizado. 

En el caso de que se haya permitido el uso de SOAP, se DEBE  usar el patrón de diseño XML Schema y NO DEBEN contener parámetros con XML incrustado.

DIR_08 Comunicación asíncrona

OBLIGATORIO En el caso de comunicación asíncrona, se utilizará AsyncAPI como estándar para definir las APIs. Además, las comunicaciones se realizarán con alguno de los siguientes protocolos:

• SSE (Server-Sent Events): Se RECOMIENDA su uso en proyectos que requieren una transmisión unidireccional de eventos desde el servidor al cliente de manera eficiente y en tiempo real.
• WebSocket: Se RECOMIENDA su uso en proyectos que necesitan una comunicación bidireccional y en tiempo real entre el cliente y el servidor.
• gRPC asíncrono: Se RECOMIENDA su uso en proyectos que demandan una alta velocidad y eficiencia en la comunicación asincrónica entre servicios, especialmente en entornos donde se prioriza la comunicación asíncrona con bajo tiempo de latencia.

Reglas y convenciones para facilitar la mantenibilidad y calidad del servicio

DIR_09 Verificación de la calidad del código

OBLIGATORIO El equipo de desarrollo aplicará un mecanismo de verificación de la calidad del código que se ejecute de forma continua o frecuente, minimizando el número de defectos y reduciendo la deuda técnica.

En aquellos casos en los que sea técnicamente viable, se utilizarán los siguientes Umbrales de aceptación permitidos por SonarQube Quality Gates.

Se RECOMIENDA la instalación de forma local de este conjunto de reglas en los IDEs del equipo de desarrollo para ir monitorizando en tiempo real su cumplimiento y garantizar la resolución instantánea en caso de detección de no conformidades.

DIR_10 Conformidad con la calidad

OBLIGATORIO El equipo de desarrollo mantendrá en niveles mínimos el número de no conformidades respecto a las normas de calidad del código.

En nuevos desarrollos, se cumplirán, cuando estén definidos, los umbrales de aceptación, desde las primeras versiones de código.

En el caso de un sistema preexistente, se establecerá una línea base en la primera entrega, que será considerada como el nivel máximo de no conformidades, cuyo número se debe ir reduciendo.

DIR_11 Versionado

OBLIGATORIO Se utilizará la política de versionado SEMVER (Versionado Semántico).

De cara a garantizar que todos los productos o componentes software sigan una política de versionado estándar, se deben aplicar las pautas marcadas por el esquema de control de versiones SEMVER, que se resumen a continuación:

• El software que use Versionado Semántico DEBE declarar un elemento de infraestructura, configuración o despliegue. Este, puede ser declarado en el código mismo o existir en documentación estricta que, de cualquier manera, debería ser precisa y completa.
• Un número normal de versión DEBE tomar la forma X.Y.Z donde X, Y, y Z son enteros no negativos. X es la versión “major”, Y es la versión “minor”, y Z es la versión “patch”. Cada elemento DEBE incrementarse numéricamente en incrementos de 1. Por ejemplo: 1.9.0 -> 1.10.0 -> 1.11.0.
• Una vez que un paquete versionado ha sido liberado (release), los contenidos de esa versión NO DEBE ser modificados. Cualquier modificación DEBE ser liberada como una nueva versión.
• La versión major en cero (0.y.z) es para desarrollo inicial. Cualquier cosa puede cambiar en cualquier momento. El elemento NO DEBE ser considerada estable.
• La versión 1.0.0 define el elemento. La forma en que el número de versión es incrementado después de este release depende de este elemento y de cómo cambia.
• La versión patch Z (x.y.Z | x > 0) DEBEincrementarse cuando se introducen solo arreglos compatibles con la versión anterior. Un arreglo de bug se define como un cambio interno que corrige un comportamiento erróneo.
• La versión minor Y (x.Y.z | x > 0) DEBE ser incrementada si se introduce nueva funcionalidad compatible con la versión anterior. Se DEBE incrementar si cualquier funcionalidad del elemento es marcada como deprecada. PUEDE ser incrementada si se agrega funcionalidad o arreglos considerables al código privado. Puede incluir cambios de nivel patch. La versión patch DEBE ser reseteada a 0 cuando la versión minor es incrementada.
• La versión major X (X.y.z | X > 0) DEBE ser incrementada si cualquier cambio no compatible con la versión anterior es introducido en el elemento. PUEDE incluir cambios de nivel minor y/o patch. Las versiones patch y minor DEBE ser reseteadas a 0 cuando se incrementa la versión major.

De forma resumida:

• X: Aumentará cuando se producen cambios que rompan la compatibilidad de alguna manera con la versión anterior. (major).
• Y: Aumentará con cada funcionalidad añadida compatible con la versión anterior. (minor).
• Z: Aumentará con correcciones compatibles con la versión anterior. (patch).

Para más información sobre SEMVER:

• SEMVER (Versionado Semántico)

DIR_12 Granularidad de operaciones

RECOMENDADO Se evitará la definición del servicio con una excesiva granularidad de operaciones, buscando un equilibrio entre el número de servicios y operaciones.

Se diseñarán servicios web con las responsabilidades bien repartidas, que sean cohesivos, extensibles, escalables y reutilizables. Puede tomarse como punto de partida la definición de un Servicio Web por cada servicio de negocio identificado. Se RECOMIENDA no sobrepasar las cinco operaciones por servicio.

DIR_13 Configuración externa

RECOMENDADO Las configuraciones no sensibles de los servicios se recomienda gestionarlas dinámicamente de forma externa a la definición del servicio.

Para ello, se desacoplará la configuración del contenedor de las imágenes de aplicación, lo que facilita la gestión de la configuración y su modificación sin necesidad de cambiar el código fuente de la aplicación.

Se almacenarán datos de configuración que no cambian con frecuencia, como variables de entorno y archivos de configuración. Esto permitirá una gestión centralizada y dinámica de la configuración. NO DEBEN contener información sensible.

Por ejemplo, uso de los ConfigMaps de Kubernetes para almacenar datos de configuración.

Políticas para la gestión de errores

DIR_14 Errores

OBLIGATORIO Se definirá una política que gestione los errores para cubrir al completo los posibles escenarios que puedan producirse. Cubrirá tanto errores de carácter técnico, desacoplados del servicio y de la arquitectura del sistema, como errores funcionales derivados del propio tratamiento del mensaje.

Esta política debe tenerse en cuenta a la hora de diseñar e implementar los servicios que proporcionan los sistemas de información.

• Errores de comunicación: relativos al envío y aceptación de los mensajes por parte del sistema receptor de la misma. Los receptores de la mensajería deberán realizar una validación sintáctica del esquema, valores de los campos y formato.
• Errores técnicos de la aplicación: producidos durante el procesamiento (caídas de bbdd, código mal desarrollado, errores de SO, no controlados, …)
• Errores funcionales de la aplicación: derivados del tratamiento de la información contenida en el mensaje aceptado por el sistema proveedor.

SE DEBE usar los códigos de error de forma coherente con el tipo de error (mal uso de errores técnicos en funcionales). Por ejemplo, ante una consulta GET en la que no se encuentran datos, sería incorrecto devolver un 404 Not Found. En su lugar, habría que devolver un 204 No Content.

SE DEBE registrar y manejar los errores de manera segura, evitando la exposición de detalles técnicos que puedan ser aprovechados por posibles atacantes para comprometer la seguridad de la aplicación.

Observabilidad

Reglas y convenciones relativas a la generación de logs y su contenido

DIR_15 Nivel de log

OBLIGATORIO El nivel de log (registro de eventos y actividades del sistema) se adaptará al tipo de mensaje que se quiere registrar.

Podemos utilizar el siguiente esquema para decidir el nivel de log en cada mensaje que queremos registrar:

DIR_16 Nivel de detalle

OBLIGATORIO Cada línea de log contendrá suficiente información para que sea fácil entender exactamente qué estaba pasando y cuál era el estado de la aplicación en ese momento.

De forma adicional, deben seguirse las siguientes normas relativas a formato y contenido:

• Tanto el contenido y forma de cada evento de log, como la semántica de los niveles son parte del diseño del sistema. Estos criterios DEBEN definirse y ser comunicados al equipo de desarrollo para que se apliquen de manera homogénea y coherente en todo el desarrollo.
• DEBEN expresarse en un lenguaje suficientemente natural para ser comprendido por un ser humano y suficientemente esquematizado para ser procesados por herramientas automatizadas de gestión de logs.
• NO DEBEN incluir información sensible. No podemos registrar contraseñas, datos personales, etc. que puedan comprometer la seguridad del sistema y/o incumplir la Ley Orgánica de Protección de Datos.
• DEBEN incluir información que te permita filtrar los registros de logs para reducir el tiempo de diagnóstico. 
• El logging NO DEBEN tener efectos laterales, no puede modificar el estado de ningún parámetro, variable o procedimiento. Solo muestra información. DEBE ser ligero, el propio logging no puede requerir de procesamientos largos o costosos.
• Se DEBEN configurar rotado de logs para mantener estable el tamaño de nuestros registros y así evitar problemas derivados del espacio en disco. 
• Se DEBEN tener en cuenta las diferencias y zonas horarias a la hora de trabajar con logs de varias máquinas o componentes.
• Las llamadas a métodos, componentes distribuidos externos DEBEN registrarse tras la llamada incluyendo los parámetros de entrada y la respuesta, así como clase/componente y método, a nivel de DEBUG. Y a nivel de ERROR y FATAL cuando ocurra un error en la llamada (si fuese una excepción DEBEN incluir los parámetros de entrada y la propia excepción)

• DEBEN proporcionar información de contexto. La persona que lea el log no tiene por qué tener ese contexto y, a veces, ni siquiera tiene acceso al código fuente. Por ejemplo, comparemos las siguientes dos líneas de log: 

  • “La base de datos no responde” 
  • “Error al obtener las preferencias de los usuarios para la identificación de usuario = 1. La base de datos de configuración no responde. Volverá a intentarlo en 5 minutos.” 

  Al leer la segunda línea de log, entendemos fácilmente qué intentaba hacer la aplicación, qué componente falló y si hay algún tipo de solución para este problema.

DIR_17 Datos sensibles

OBLIGATORIO Las trazas de logs no contendrán datos sensibles.

DIR_18 Explotación de los eventos de log

RECOMENDADO Es recomendable que los eventos de logs se integren en una plataforma de observabilidad para su explotación, por lo que deben incluir al menos los siguientes atributos en el evento de log para su explotación:

• Timestamp: Marca de tiempo que indica cuándo ocurrió el evento.
• TracerId: Identifica exclusivamente una transacción o solicitud a lo largo de todo su recorrido en el sistema.
• SpanId: Identifica cada operación individual dentro de una transacción, ayudando a relacionar partes de una transacción entre sí.
• Nivel de Severidad: Indica la gravedad del evento (por ejemplo, INFO, WARNING, ERROR).
• Mensaje: Descripción detallada del evento.
• Contexto: Información adicional relevante para el evento, como datos de la solicitud, usuario o entorno.
• Componente: Nombre del componente o servicio que generó el evento.
• Nombre del Host: Nombre del host o máquina donde ocurrió el evento. 
• Etiquetas o Tags: Metadatos adicionales que facilitan el filtrado y la búsqueda de eventos.

En el caso de que el nivel de severidad sea ERROR, se RECOMIENDA que dentro del campo Mensaje se incluya un código normalizado del error para poder identificar de forma explícita el origen de este.

Reglas para mantener la trazabilidad de las peticiones

DIR_19 Trazabilidad de peticiones

OBLIGATORIO El servicio implementará técnicas de registro y seguimiento de eventos para garantizar la trazabilidad efectiva de las solicitudes, a través de información detallada sobre el contexto de cada solicitud recibida.

El servicio DEBE registrar la siguiente información:

• ID de traza (Tracer Id): Un identificador único que identifica de manera exclusiva una transacción o solicitud a lo largo de todo su recorrido a través del sistema.
• ID de span (Span Id): Identificadores únicos asociados con cada operación individual dentro de una transacción. Estos identificadores ayudan a relacionar diferentes partes de una transacción entre sí.
• Nombre del span (Span Name): Una descripción o nombre que indica la naturaleza de la operación realizada en el span (unidad de trabajo individual dentro de una traza), como "Inicio de solicitud HTTP" o "Consulta a la base de datos".
• Tiempo de inicio y fin (Start Time y End Time): El tiempo en que se inició y finalizó cada operación dentro de la transacción. Estos tiempos son cruciales para calcular la duración de cada span y la duración total de la transacción.
• Metadatos del sistema (Metadata): Información sobre el entorno en el que se ejecuta la transacción, como el nombre del servicio, la versión del software, la dirección IP, etc.

Se RECOMIENDA ampliar la traza con la siguiente información de interés:

• Anotaciones y atributos: Información adicional asociada con cada span, como datos de contexto, parámetros de solicitud, resultados de operaciones, etc.
• Relaciones de parentesco: Información que indica las relaciones jerárquicas entre diferentes spans dentro de una transacción. Por ejemplo, un span que representa una solicitud HTTP podría tener spans secundarios que representan operaciones de bases de datos o llamadas a servicios externos.

Convenciones referentes a métricas y estado de salud de los servicios

DIR_20 Métricas

OBLIGATORIO Los servicios proporcionarán métricas que permitan analizar el sistema y detectar posibles problemas.

Estas métricas permiten monitorizar y analizar el funcionamiento de los servicios y del sistema en su conjunto, facilitando la detección temprana de problemas, la optimización del rendimiento, la toma de decisiones informadas y la mejora continua de la arquitectura y operación del sistema.

Se hará uso de las métricas que proporciona la plataforma de integración y se complementará con las métricas generadas a partir del registro en log.

DIR_21 Chequeo del servicio

OBLIGATORIO El servicio proporcionará un endpoint que permita comprobar su estado de salud.

Este chequeo del servicio no solo indica si el servicio está arrancado o no, sino que debe verificar cualquier circunstancia que pueda interrumpir la atención de las solicitudes entrantes, desde comprobaciones de conectividad con otros sistemas, bases de datos, colas, etc., hasta tiempos de respuestas de otros sistemas con los que se integre, consumos de memoria, grandes cantidades de mensajes en cola con la que se conecte, …

• Liveness: DEBE verificar si el servicio está activo y funcionando correctamente, en caso contrario se inicia el proceso de reinicio del contenedor si el fallo perdura en el tiempo. Se RECOMIENDA verificar los siguientes puntos:
  • Conexión a la base de datos: Intenta realizar una conexión de prueba a la base de datos. 
  • Recursos Externos: intenta realizar una conexión a recursos externos de prueba como servicios REST u otras aplicaciones.
  • Verificación de recursos internos: Realiza comprobaciones internas para asegurarte de que los componentes cruciales de tu aplicación estén funcionando correctamente. 
• Readiness: DEBE verificar si el servicio está listo para manejar solicitudes de manera efectiva, en caso contrario el contenedor se excluye del balanceo de carga y si el fallo perdura en el tiempo, se inicia el proceso de reinicio del contenedor. Se RECOMIENDA  verificar los siguientes puntos:
  • Inicialización de la aplicación: Verifica si tu aplicación ha completado la inicialización correctamente. 
  • Disponibilidad de recursos externos: Verifica si todas las dependencias externas, como bases de datos, servicios REST u otras aplicaciones, están disponibles y listas para manejar solicitudes.
  • Carga de datos iniciales: Si tu aplicación depende de ciertos datos iniciales para funcionar correctamente, puedes verificar si estos datos se han cargado correctamente y están disponibles para su uso.
  • Comprobación de recursos contendor: Verifica que el contenedor tiene los recursos de memoria y cpu necesarios para llevar a cabo las solicitudes.

Seguridad

Establecimiento de políticas de seguridad en las comunicaciones, autorización, validaciones y datos sensibles

DIR_22 SSL

OBLIGATORIO Todas las comunicaciones entre los distintos componentes de la arquitectura se realizarán de forma segura, mediante protocolo SSL.

En la plataforma se va a desplegar una malla de servicios llamada Istio que será la encargada de proporcionar la comunicación segura entre los componentes. Solo se permite el uso de TLS 1.2 y 1.3.

DIR_23 Tokens

OBLIGATORIO Todos los servicios de integración basarán su autenticación en tokens (un token es una cadena de caracteres que representa la identidad de un usuario o de una aplicación).

La autenticación basada en tokens se diferencia del uso tradicional de cookies de sesión al no almacenar información de sesión en el servidor. En su lugar, utiliza tokens emitidos por el servidor y enviados al cliente tras un proceso de autenticación exitoso. Estos tokens se incluyen en las solicitudes posteriores para acceder a recursos protegidos.

Tipos de Tokens

• JWT (JSON Web Tokens): Un formato común y estándar de tokens, que consta de tres partes: encabezado, payload (carga útil) y firma. Es ampliamente utilizado debido a su versatilidad y capacidad de transportar datos de forma segura.
• Opaque Tokens: Tokens opacos que no revelan información sobre el usuario o la sesión cuando se decodifican. Son simplemente identificadores que el servidor verifica contra un almacén de datos.

Ciclo de Vida de un Token

• Autenticación del Usuario: El cliente envía las credenciales de autenticación al servidor.
• Generación del Token: Si las credenciales son válidas, el servidor genera un token (JWT u opaco) y lo envía al cliente.
• Almacenamiento del Token: El cliente almacena el token (por ejemplo, en el almacenamiento local o en una cookie segura).
• Uso del Token: En cada solicitud posterior, el cliente incluye el token en los encabezados de autorización (Authorization: Bearer <token>).
• Validación del Token: El servidor valida el token para asegurar que es legítimo y no ha expirado antes de permitir el acceso al recurso solicitado.
• Renovación/Revocación del Token: Los tokens tienen un tiempo de vida limitado. El servidor puede permitir la renovación de tokens o revocarlos en caso de detectar actividades sospechosas.

DIR_24 Roles

RECOMENDADO Se recomienda que los servicios de integración se securicen mediante roles.

Se asignarán roles y permisos de manera granular para garantizar el principio de mínimo privilegio y la segregación de tareas. Al hacerlo, se limita el acceso a funciones y datos sensibles, reduciendo la superficie de ataque y mitigando el impacto potencial de una brecha de seguridad.

El principio de mínimo privilegio establece que los usuarios deben tener los permisos mínimos necesarios para realizar sus tareas. Esto limita el impacto de una cuenta comprometida y reduce las posibilidades de abuso de privilegios.

La segregación de tareas implica dividir responsabilidades de manera que ninguna persona tenga control total sobre todas las fases de una operación crítica. Esto previene fraudes y errores no intencionados, asegurando que múltiples personas o sistemas supervisen actividades críticas.

Para cumplir esta norma es necesario:

• Identificación de Roles: Identificar y definir claramente todos los roles dentro del sistema. Cada rol debe representar un conjunto específico de responsabilidades y permisos.
• Asignación de Permisos: Asignar permisos a roles en lugar de usuarios individuales. Esto simplifica la gestión de permisos y asegura coherencia en el control de acceso.

DIR_25 Validación de datos de entrada

OBLIGATORIO Se validarán los datos de entrada del servicio para evitar posibles problemas posteriores a la hora de hacer uso de ellos.

La validación de entradas implica verificar que los datos introducidos por los usuarios en la aplicación cumplan con los requisitos especificados, como formato, tipo y longitud. Al implementar una validación rigurosa, se evita que los usuarios introduzcan datos maliciosos que puedan desencadenar ataques como la inyección de código o la manipulación de datos.

DIR_26 Codificación de datos de salida

OBLIGATORIO Se codificarán los datos devueltos para prevenir ataques.

La codificación de salidas implica garantizar que los datos devueltos al usuario estén correctamente formateados y escapados para prevenir ataques de inyección de código, como el cross-site scripting (XSS). Esto se logra utilizando técnicas de codificación adecuadas, como la codificación HTML, que aseguran que los datos no puedan ser interpretados como código malicioso por el navegador del usuario. La codificación de salidas es esencial para proteger la integridad del sistema y garantizar una interacción segura con el usuario.

DIR_27 Configuraciones sensibles

OBLIGATORIO Las configuraciones sensibles como contraseñas, certificados, usuarios de integración, etc., estarán registradas como secretos dentro de la plataforma.

El servicio no debe contener datos sensibles en el código y tampoco en los ficheros de configuración.

DIR_28 Cifrado robusto de datos

OBLIGATORIO  Se usarán algoritmos criptográficos robustos para proteger los datos almacenados

La selección de algoritmos criptográficos robustos y ampliamente aceptados es crucial para garantizar una protección efectiva de los datos almacenados. Algoritmos como AES (Advanced Encryption Standard) o RSA (Rivest-Shamir-Adleman) son ejemplos de algoritmos confiables que ofrecen un alto nivel de seguridad y resistencia a los ataques criptoanalíticos.

DIR_29 Generación de semillas seguras

OBLIGATORIO Se usarán funciones o generadores de semilla seguros

El uso de funciones criptográficamente seguras o generadores de números aleatorios certificados es fundamental para garantizar la aleatoriedad y la entropía de los valores generados en aplicaciones que requieren seguridad criptográfica. Estas funciones están diseñadas específicamente para resistir ataques predictivos y garantizar la imprevisibilidad de los valores generados, lo que fortalece la seguridad de las claves criptográficas y la integridad de los datos almacenados.

Estas funciones criptográficamente seguras son algoritmos diseñados para generar valores que son estadísticamente indistinguibles de valores verdaderamente aleatorios. Se basan en principios criptográficos sólidos y han sido rigurosamente probadas y evaluadas para resistir diversos ataques criptográficos, como el análisis de frecuencia y el ataque de fuerza bruta.

Entre algunos ejemplos de funciones criptográficamente seguras, se incluyen las funciones de resumen (hash) como SHA-256 y SHA-512, que se utilizan para generar valores hash únicos a partir de datos de entrada.

El uso de funciones criptográficas seguras, como las mencionadas, en lugar de otras variantes, se debe a varias consideraciones relacionadas con la seguridad y el rendimiento. Aquí hay algunas razones por las que se recomienda el uso de SHA-256 y SHA-512:

Longitud del hash

Ambas funciones producen hashes de longitud significativamente más larga que sus predecesoras, como SHA-1 (160 bits). SHA-256 produce un hash de 256 bits, mientras que SHA-512 produce uno de 512 bits. Esta mayor longitud aumenta la resistencia a ataques de fuerza bruta y colisiones, lo que significa que es menos probable que dos conjuntos de datos diferentes generen el mismo hash.

Resistencia a colisiones

Las funciones SHA-256 y SHA-512 tienen una mayor resistencia a las colisiones en comparación con algoritmos más antiguos como SHA-1. Una colisión ocurre cuando dos conjuntos de datos diferentes producen el mismo hash. A medida que aumenta el tamaño del espacio de salida del hash (256 bits para SHA-256 y 512 bits para SHA-512), la probabilidad de colisión disminuye.

Seguridad a largo plazo

A medida que aumentan los avances en la capacidad de computación, los algoritmos criptográficos se vuelven vulnerables con el tiempo. SHA-256 y SHA-512 se consideran más seguros a largo plazo que algoritmos más antiguos como SHA-1, que han mostrado debilidades frente a ataques teóricos. Por lo tanto, se prefieren para aplicaciones que requieren una seguridad a largo plazo.

Pruebas

Políticas de pruebas sobre sistemas de integración

DIR_30 Pruebas unitarias

OBLIGATORIO Se realizarán suficientes pruebas unitarias para cubrir el mínimo porcentaje exigido de código, validando todos los componentes elementales y sus distintas rutas lógicas.

Las pruebas unitarias son la primera línea de defensa en la detección de errores, por lo que es muy importante que cubran la mayor parte de la lógica de forma aislada del resto.

DIR_31 Pruebas de integración

OBLIGATORIO Se realizarán las pruebas necesarias para comprobar que todos los componentes de la arquitectura de interoperabilidad se integran de manera correcta.

DIR_32 Pruebas de rendimiento

OBLIGATORIO Se realizarán pruebas de rendimiento (carga, picos y estrés) en entornos no productivos para validar que la solución de interoperabilidad implementada es capaz de responder a las necesidades para las que ha sido creada.

Anexo: estándares

Definición de servicios y eventos

Open API

Open API es un estándar para la descripción de las API. La especificación OpenAPI define un formato de descripción abierto e independiente de los fabricantes para los servicios de API. En particular, OpenAPI puede utilizarse para describir, desarrollar, probar y documentar las API compatibles con REST.

• https://www.openapis.org/
• https://swagger.io/specification/ 

Async API

La especificación AsyncAPI es un proyecto que se utiliza para describir API basadas en mensajes en un formato legible por máquina. Es independiente del protocolo, por lo que puede usarlo para API que funcionan con cualquier protocolo (por ejemplo, AMQP, MQTT, WebSocket, Kafka, STOMP, HTTP, Mercure, etc.).

La especificación AsyncAPI define un conjunto de campos que se pueden usar en un documento AsyncAPI para describir la API de una aplicación. El documento puede hacer referencia a otros archivos para obtener detalles adicionales o campos compartidos, pero normalmente es un documento principal único que encapsula la descripción de la API.

El documento AsyncAPI DEBE describir las operaciones que realiza una aplicación.

• https://www.asyncapi.com/en
• https://www.asyncapi.com/docs/reference/specification/v3.0.0

XML Schema

XSD (XML Schema Definition) es un lenguaje de esquema utilizado para describir la estructura y las restricciones de los contenidos de los documentos XML de una forma muy precisa, más allá de las normas sintácticas impuestas por el propio lenguaje XML. Se consigue así una percepción del tipo de documento con un nivel alto de abstracción. Fue desarrollado por el World Wide Web Consortium (W3C) y alcanzó el nivel de recomendación en mayo de 2001.

Los tipos de datos especiales se incluyen en el archivo WSDL en forma de XML Schema. 

• https://www.w3schools.com/xml/schema_intro.asp

Comunicaciones

API RESTful

API RESTful es un estilo arquitectónico basado en HTTP que permite a los clientes acceder y manipular recursos a través de una interfaz uniforme y predefinida. Utiliza los métodos estándar de HTTP, como GET, POST, PUT y DELETE, para realizar operaciones CRUD (Crear, Leer, Actualizar y Eliminar) en los recursos. Las respuestas se devuelven generalmente en formatos como JSON o XML y siguen los principios de statelessness, cacheability, client-server, layered system, code on demand y uniform interface.

GraphQL

GraphQL es un lenguaje de consulta para API y un runtime para completar esas consultas con sus datos existentes. GraphQL proporciona una descripción completa y comprensible de los datos de su API, brinda a los clientes el poder de solicitar exactamente lo que necesitan y nada más, facilita la evolución de las API con el tiempo y habilita potentes herramientas para desarrolladores.

gRPC

Es un protocolo de comunicación de código abierto desarrollado por Google, diseñado para permitir la comunicación eficiente y confiable entre servicios distribuidos. Se basa en HTTP/2 para la comunicación de datos y utiliza el Protocolo de Buffers de Google (protobuf) como su mecanismo de serialización. Este protocolo ofrece características avanzadas como llamadas de procedimiento remoto (RPC) de bajo costo, streaming de datos bidireccional y soporte integrado para autenticación y autorización. Es ampliamente utilizado en aplicaciones distribuidas y sistemas de microservicios debido a su eficiencia, escalabilidad y facilidad de uso.

WebSockets

Es un protocolo de comunicación bidireccional y full-duplex que se ejecuta sobre TCP, diseñado para habilitar una comunicación en tiempo real entre un cliente y un servidor a través de una única conexión persistente. Permite que los datos se transmitan de forma eficiente en ambas direcciones.

Server-Sent Events (SSE)

Es un protocolo basado en HTTP que permite a un servidor enviar eventos de forma asíncrona al cliente a través de una conexión HTTP persistente. SSE es unidireccional (del servidor al cliente) y está orientado principalmente a la transmisión de datos desde el servidor al cliente en tiempo real, como actualizaciones de estado, notificaciones o feeds de noticias. SSE utiliza el formato de texto plano y se integra bien con la infraestructura web existente, lo que lo hace fácil de implementar y compatible con una amplia gama de tecnologías cliente. 

Seguridad

HTTPS/SSL

HTTPS permite la autenticación del cliente y del servidor mediante certificados. 

SSL es un protocolo que transmite las comunicaciones por Internet en formato cifrado. De esta manera se garantiza que la información se envíe sin cambios al servidor deseado. Es posible aplicar servicios web HTTPS a todos los tipos de clientes, incluidos los clientes Java EE y los clientes Java independientes. 

En la actualidad, HTTPS con certificados del servidor constituye la configuración más habitual de la Web. En esta configuración, el servidor debe presentar su certificado al cliente para determinar la identidad del servidor. El cliente no necesita presentar su certificado al servidor para que este determine la identidad de aquel. En otras palabras, el cliente puede autenticar al servidor, pero el servidor no puede autenticar al cliente. Sin embargo, también es posible usar HTTPS junto con la autenticación básica, que permite al servidor autenticar al cliente o establecer un mecanismo de autenticación Mutual SSL donde hay un intercambio de certificados entre servidor y cliente.

OAuth2

OAuth2 es un protocolo de autorización que permite a terceros (clientes) acceder a contenidos propiedad de un usuario (alojados en aplicaciones de confianza, servidor de recursos) sin que éstos tengan que manejar ni conocer las credenciales del usuario. Es decir, aplicaciones de terceros pueden acceder a contenidos propiedad del usuario, pero estas aplicaciones no conocen las credenciales de autenticación. Por tanto, en OAuth podemos identificar tres entidades: 

• Propietario de recursos. Es una entidad capaz de dar acceso a recursos protegidos. Cuando es una persona nos referiremos a él como usuario final. 
• Cliente. Es la aplicación hace peticiones a recursos protegidos en nombre de un propietario de recursos con la autorización del mismo. 
• Proveedor 
  • Servidor de recursos. Es la entidad que tiene los recursos protegidos. Es capaz de aceptar y responder peticiones usando un access token que debe venir en el cuerpo de la petición.
  • Servidor de autorización. En muchos casos el servidor de autenticación es el mismo que el Servidor de Recursos. En el caso de que se separen, el servidor de autenticación es el responsable de generar tokens de acceso y validar usuarios y credenciales. 

OAuth2 tiene dos grandes ventajas, soluciona el problema de la confianza entre un usuario y aplicaciones de terceros, y a su vez permite a un proveedor de servicios/API facilitar a aplicaciones de terceros a que amplíen sus servicios con aplicaciones que hacen uso de los datos de sus usuarios de manera segura y dejando al usuario la decisión de cuándo y a quién, revocar o facilitar acceso a sus datos, creando así un ecosistema de aplicaciones alrededor del proveedor de servicios/API. Esto está directamente relacionado con el concepto de los API Manager.

Json Web Token (JWT)

JSON Web Token (JWT) es un estándar abierto que define una forma compacta y autocontenida de transmitir información de forma segura entre partes como un objeto JSON, consta de tres partes: encabezado, payload (carga útil) y firma. Esta información puede ser verificada y confiable porque está firmada digitalmente. Los JWT pueden ser firmados utilizando un secreto (con el algoritmo HMAC) o un par de clave pública/privada utilizando RSA o ECDSA.