1

Estrategia de Integración Digital del Estado Guía técnica de integración de Trámites y Servicios a

GOV.CO ANEXO 2. – Recomendaciones técnicas para la integración de

trámites y servicios

2

Ministerio de Tecnologías de la Información y las Comunicaciones Viceministerio de Economía Digital Dirección de Gobierno Digital Equipo de trabajo Sylvia Cristina Constaín Rengifo – Ministra de Tecnologías de la Información y las Comunicaciones Jehudi Castro Sierra - Viceministro de Economía Digital Claudia Patricia Pico Quintero – Directora Gobierno Digital Grace Quintana – Subdirectora de Gobierno Adriana Vargas Tamayo – Equipo GOV.CO Edson Gómez - Equipo GOV.CO Natalia Albañil _ Equipo GOV.CO Rebeca Becerra – Equipo GOV.CO Francisco Moreno – Equipo GOV.CO Alejandro Caballero – Equipo GOV.CO Diana Clavijo – Equipo GOV.CO Juliana Cardona – Equipo GOV.CO Felipe Ramos – Equipo GOV.CO Carolina Escobar – Equipo GOV.CO Luisa Medina – Equipo GOV.CO Carlos León – Equipo GOV.CO Senen Niño – Equipo GOV.CO

Versión Observaciones

Versión 1 Septiembre 2019 Recomendaciones técnicas para la integración de trámites y servicios.

Comentarios, sugerencias o correcciones pueden ser enviadas al correo electrónico: gobiernodigital@mintic.gov.co Manual de Gobierno Digital

Este manual de la Dirección de Gobierno Digital se encuentra bajo una Licencia Creative Commons Atribución 4.0 Internacional.

3

Contenido

1. Introducción ........................................................................................................................ 4

2. Arquitectura de integración a GOV.CO ............................................................................. 4

3. Conectividad ........................................................................................................................ 4 3.1 Conectividad GNAP ............................................................................................................. 5

4. Seguridad ............................................................................................................................. 6 4.1 Seguridad en los servicios WEB ........................................................................................... 6 4.2 Seguridad en el código embebido ....................................................................................... 8

5. Servicios y Trámites ............................................................................................................ 9 5.1 Servicios y trámites con descarga de archivos adjuntos de gran tamaño (> 5Mb) ............. 9 5.2 Servicios con paginación ................................................................................................... 13 5.3 Servicios informativos ....................................................................................................... 14 5.4 Servicios y trámites con pagos PSE – Tarjetas de crédito ................................................. 16

4

1. Introducción El presente documento, Anexo a la Guía técnica de Integración de trámites, define los lineamientos y recomendaciones técnicas generales para que las entidades públicas adelanten el proceso de integración al Portal Único del Estado GOV.CO de los trámites y servicios que ofrecen a los ciudadanos, extranjeros y empresarios buscando así ofrecer a estos una única visión del Estado y una comunicación clara y efectiva que les permita acceder a sus derechos y deberes. Es importante aclarar que los lineamientos definidos en este documento son compatibles con el Marco de interoperabilidad definido actualmente por el Ministerio de Tecnologías de la Información como Servicio Ciudadano Digital y, que las especificaciones que no se encuentren contenidas en este deberán ser consultadas en dicho modelo. Adicionalmente, es un documento que tendrá una actualización dinámica ajustándose según necesidades particulares que se vayan identificando en las diferentes entidades.

2. Arquitectura de integración a GOV.CO Para la integración de trámites y servicios a GOV.CO se ha previsto el uso de una arquitectura orientada a servicios - SOA. Se plantea que la construcción de servicios web haga uso de SOAP-XML o de la tecnología Rest, ya sea content-type multipart form-data o application-json. A continuación, se describen los componentes de la arquitectura:

Componente Descripción GOV.CO Representa la aplicación GOV.CO en dónde se encontrarán integrados y

presentados a los ciudadanos todos los trámites de las entidades públicas.

API – ESB Componente opcional que permite desacoplar, encapsular, transformar, orquestar, proteger, entre otros beneficios, el consumo y exposición de servicios web de las entidades.

WS – Entidad Componente en dónde está implementado el servicio web de la entidad. Base de datos Base de datos alojada en la entidad que contiene los datos a consultar,

registrar, eliminar o actualizar de un servicio web.

3. Conectividad A continuación, se listan las diferentes alternativas para la conectividad entre los servidores de las entidades que desean consumir y exponer servicios web.

Tecnología Ventajas Desventajas GNAP - Seguridad. Al tratarse de una

VPN entre entidades del Estado, - Es orientada a entidades

públicas únicamente. Lo anterior genera restricciones

5

Tecnología Ventajas Desventajas el canal de comunicación es cifrado.

- Velocidad. - Implementación. La

configuración e implementación de la red se realiza por medio de los operadores de telecomunicaciones. Su costo está incluido al adquirir el enlace de internet.

- Obligatoriedad. Las entidades del Estado están en la obligación de utilizar esta red para intercambiar información con otras entidades.

que requieren manejo diferencial para el caso de entidades mixtas o privadas.

VPN - Seguridad - Velocidad - Implementación. Se deberá

realizar un plan de trabajo entre los administradores de los routers y firewall perimetral.

- Cualquier entidad (privada, mixta, pública) podría implementar esta tecnología.

- Administración de gran número de VPN.

Internet - Velocidad - Implementación - Cualquier entidad (privada,

mixta, pública) podría implementar esta tecnología.

- Seguridad

Para el caso en el que se está embebiendo el sitio web de la entidad, no sería necesaria la configuración de canales de comunicación como los antes descritos. Sin embargo, se deberá revisar la sección de Seguridad en el código embebido del presente documento.

3.1 Conectividad GNAP1

GNAP es la red de alta velocidad del Estado colombiano (Network Access Protection de Gobierno). Esta red permite que todas las entidades se conecten entre sí, publiquen y compartan información más rápido y seguro. El funcionamiento de la red es por medio de los operadores quienes prestan el servicio de conectividad de los Acuerdos Marco de Precios (AMP) habilitados por Colombia Compra Eficiente (CCE). Al estar las entidades conectadas físicamente con los operadores antes mencionados, ellos garantizan el canal privado de comunicación entre las entidades por medio del mismo canal utilizado para acceder a internet. De cara a lograr la conectividad en GNAP, las entidades deben contratar, mediante AMP, un canal de conectividad con alguno de los operadores habilitados por Colombia Compra Eficiente (CCE).

1 MINTIC (2015). Recuperado de: https://www.mintic.gov.co/portal/604/w3-article-9098.html

6

Considerando el siguiente diagrama de red de una entidad, los elementos que se deben trabajar y configurar son el router y firewall perimetral como se muestra a continuación.

Gráfica 3.1: Diagrama de red de una entidad

El router perimetral será configurado por el operador habilitado una vez se realicé la contratación del servicio. El firewall perimetral deberá ser configurado por la entidad, definiendo y creando las reglas y políticas de seguridad correspondientes.

4. Seguridad 4.1 Seguridad en los servicios WEB La información aquí presentada corresponde a las mejores prácticas y estándares de reconocimiento mundial y su implementación es opcional la cual debe ser evaluada por cada entidad de acuerdo con el grado de sensibilidad de los datos que se intercambiaran a través de los servicios Web. Tomando como referencia OWASP (Open Web Application Security Project), el cual es un Proyecto a nivel mundial que busca definir buenas prácticas y métodos para mejorar la seguridad del software, se listan a continuación las recomendaciones en la implementación segura de servicios web. 1. La infraestructura que soporta los servicios web se debe encontrar protegida en una Zona

Desmilitarizada (DMZ) 2. Implementar SSL/TLS como protocolo de comunicaciones de los servicios web.

7

3. Implementar el método POST para los formularios en los cuales se intercambia información de negocio. Para los demás casos, por ejemplo, los servicios de mensajes, avisos de tratamiento de datos personales, ver la sección Servicios informativos.

4. Implementar OAuth 2.0 por medio de Json Web Tokens. Esta implementación se efectuará con headers de la siguiente manera: a) Autenticación Haciendo uso del header Authorization Basic base64.Encoded(“usuario: contraseña”). Esta operación retornaría un token implementando JWT con la siguiente estructura:

Ejemplo: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ El primer string (hasta el primer punto), representa el header del token. El string de la mitad representa el payload (carga útil) del token y, por último, la firma digital del token el cual permite validar la integridad del token.

b) Autorización Haciendo uso del header Authorization Bearer JWT-TOKEN La siguiente imagen muestra la interacción, http status code que se deberán retornar y en general el uso de estos componentes.

Gráfica 4.1. Interacción haciendo uso del header Authorization Bearer JWT-TOKEN

NOTA: En la anterior imagen, el Identity Server podría ser el Servicio Ciudadano de Autenticación Digital.

Identity Server

Ws autenticacion: Authorization Basic encoded64(“usuario:contraseña”)

Creación JWT Token

Validación LDAP, AD, DB

Retorna el JWT token creado / si no es exitosa la validación retornaría 401 Anauthorized

Ws autenticacion: Authorization Bearer Token

1

Validación Token

Retorna un http status code 200 o 403 Forbidden

2

8

5. La entidad debe informar a GOV.CO, a través del formato Especificación Técnica del Contrato

del Servicio, cuáles de los datos que se comunicarán a través del servicio son públicos y cuáles sensibles; así como si se genera algún documento que venga cifrado (Ejemplo: Documento en PDF con contraseña).

6. La entidad diligenciará toda la información del Servicio web a través del formato Caracterización de los servicios (Información general, descripción, parametrización y detalle técnico del servicio)

Los formatos están disponibles en la biblioteca de recursos de GOV.CO. 4.2 Seguridad en el código embebido Con el objetivo de embeber el sitio web de una entidad, se deberán considerar las siguientes recomendaciones: ENTIDAD 1. Restricción de acceso configurado en el servidor de la entidad. 2. URL para embeber expuesta en HTTPS 3. Asegurar que se encuentre habilitado el dominio GOV.CO para embeber esta URL, en caso de

estar activo el Same Origin 4. Implementación de un token de acceso que sería parte de la URL y que enviará el sitio que

embebe la URL.

GOV.CO 1. Utilizar el atributo sandbox con la lista de permisos definidos y acordados con las entidades con

cada fragmento embebido. 2. Implementar token de acceso como se muestra en el diagrama.

9

Gráfica 4.2. Embebido de trámites y servicios

La utilización del atributo sandbox por GOV.CO y la URL expuesta en HTTPS debieran constituir la implementación básica cuándo se embebe un sitio web. Los otros puntos son recomendaciones adicionales que agregarían capas de seguridad a la implementación.

5. Servicios y Trámites 5.1 Servicios y trámites con descarga de archivos adjuntos de gran tamaño (> 5Mb) Se recomienda realizar la transferencia de archivos leyendo el archivo como un array de bytes por medio de los objetos de flujo de datos (streams). Al utilizar esta funcionalidad se podrá:

- Transferir y manipular todos los tipos de archivos (pdf, xls, xlsx, doc, etc), ya que no se hace ninguna manipulación a nivel de contenido de los mismos.

- Crear diferentes chunks o pequeños array de bytes para posteriormente enviar la información por el servicio web.

En este punto es importante mencionar que, si bien se está definiendo como límite y tamaño de los chunks 5 MB, este parámetro será configurable y deberá ser validado con cada entidad al momento de realizar el diseño técnico del servicio. En esta validación se considerarán los siguientes elementos para modificar este parámetro:

GOV.COSitio web

entidad/fragmentoweb entidad

Click sobre vínculo

Generar token JWT

Petición GET URL + token

Validar token

Retornar URL

Pintar Iframe

Interacción

10

- Capacidad del canal de comunicación - Capacidad del servidor de la entidad que expone el servicio

La siguiente imagen muestra el diagrama de secuencia de la propuesta de implementación para el manejo de archivos adjuntos de gran tamaño.

Gráfica 5.1. Interacción para manejo de archivos de gran tamaño

Cómo se puede observar, se propone implementar tres servicios web con las características descritas a continuación. Nombre servicio

Tecnologías Objeto request

Objeto response

Descripción

crearArchivoConsulta

- POST SOAP-xml

- POST Rest-Json

POST /entidadContext/ crearArchivoConsulta Content-Type: application/json { “campoNegocio”: “ValorCampoNegocio” }

Content-Type: application/json { "idArchivo": "XXXXX", "numeroPartesTotales":XX (int) }

Por medio de este servicio, la entidad recibirá la petición para crear y partir el archivo en diferentes chunks. Los chunks se recomiendan que tengan un tamaño de 5MB.

obtenerArchivoConsulta

- POST SOAP-xml

- POST Rest-Json

POST / entidadContext

Content-Type: application/json {

Este servicio deberá hacerse tantas veces como chunks o partes se hayan creado y definido en la respuesta del anterior servicio.

GOV.CO Entidad

1

2

descargarArchivo

crearArchivoConsulta Generar archivoy partir

Id, #Parte

string, Id, #Parte/multipart form-data

Id, #PartesTotales

Notify (id, mt) Delete File and parts

ReconstruirArchivo

3

11

Nombre servicio

Tecnologías Objeto request

Objeto response

Descripción

/obtenerArchivo Content-Type: application/json { "idArchivo" : "XXXX", "numeroParte" : XX (int) }

“byteArrayBase64”:”XXXX”, "idArchivo": "XXXXX", "numeroParte": XX (int) }

Sin embargo, por medio de esta implementación, la ejecución de este servicio podrá hacerse de manera asíncrona. Brinda la posibilidad de recuperar o retransmitir chunks que por alguna falla de comunicación no haya podido ser entregada. Una vez se transfieran todos los archivos exitosamente, la entidad consumidora deberá reconstruir el archivo. Para llevar a cabo esta reconstrucción, deberá crear un byte array del tamaño total del archivo y recorrer los chunks, concatenando estos pequeños array de bytes en el grande. Por último, crear un nuevo archivo a partir del array de bytes inicialmente definido. Esta operación es recomendada cuando la tecnología del servicio es SOAP, ya que podrá hacer uso del formato xml para especificar y enviar el archivo como string codificado base 64. Tener en cuenta que al crear el String, el charset (UTF-8, ASCII, ISO) de creación corresponde al charset del archivo.

obtenerArchivoConsulta

- POST Rest-Multipart form-data

POST SOAP MTOM (Message transmission Optimization Mechanism)

POST / entidadContext /obtenerArchivo Content-Type: application/json { "idArchivo" : "XXXX", "numeroParte" : XX (int) }

--iE8XzPLATu3lqF9bmPC50-hXQfBv_23178KS0C Content-Disposition: form-data; name="objJson" Content-Type: application/json Content-Length: 42 {"idArchivo":"Servicios","numeroParte":25} --iE8XzPLATu3lqF9bmPC50-hXQfBv_23178KS0C Content-Disposition: form-data; name="file-chunk" Content-Type: application/octet-stream Content-Length: 5242880

El response del servicio es multipar form-data con dos partes: una application/json y otra octect-stream. La segunda contiene el array de bytes. De cara a tener el tamaño del mensaje lo más pequeño posible, no sería necesario codificar el array de bytes (considerando la implementación de los lineamientos/recomendaciones de la sección Seguridad en los servicios WEB del presente documento), sino en el octect-stream, guardar directamente el array de bytes del archivo. Sin embargo, si la entidad desea cifrar y adicionar una capa de seguridad mayor al mensaje enviado, podría codificar Base 64 el array de bytes y enviarlo en la parte Octect-Stream como un String codificado. Si la entidad desea enviar el archivo como cadena String base 64 del array de bytes, se recomienda revisar la implementación del método antes mencionado. La entidad no debería implementar las dos versiones de este mismo servicio, se recomienda únicamente o Rest-Json o Multipart form-data. Las ventajas de implementar el multipar form-data son: velocidad en la transferencia y menor tamaño del mensaje siempre y cuando se haya implementado la no codificación base64. Si la tecnología a implementar es SOAP, se recomienda la implementación por SOAP-XML descrita en el método anterior del servicio web.

12

Nombre servicio

Tecnologías Objeto request

Objeto response

Descripción

<td>NO</td><td>NO</td><td>SI</td><td>NO</td><td>20171228</td><td></td><td>DHS609166</td><td x:str>01</td><td>Fecha corte REPS: Jun 18 2019 3:10PM</td></tr><tr><td>La Guajira</td><td>RIOHACHA</td><td x:str>4484700671</td><td x:str>4400100671</td><td x:str>05</td><td>IPSI PALAIMA SEDE RIOHACHA</td><td>CALLE 12 N 10 - 08</td><td>3147005134</td><td>ipsipalaima@hotmail.com</td><td>900185729</td><td>9</td><td>JURIDICO</td><td>4</td><td>P�blica</td><td>1</td><td>Instituciones - IPS</td><td>NO</td><td>1</td><td>INDIGENA</td><td>SI</td><td>3</td><td>Consulta Externa</td><td>340</td><td>340-OTORRINOLARINGOLOG�A</td><td>SI</td><td>NO</td><td>NO</td><td>NO</td><td>NO</

13

Nombre servicio

Tecnologías Objeto request

Objeto response

Descripción

--iE8XzPLATu3lqF9bmPC50-hXQfBv_23178KS0C--

notificarResultadoOperacion

- POST SOAP-xml

- POST Rest-Json

POST / entidadContext /notificarResultado Content-Type: application/json { "idArchivo" : "XXXX", "resultado" : 1,0 (int) }

POST / entidadContext /notificarResultado Content-Type: application/json { "idArchivo" : "XXXX", "resultado" : 1,0 (int) }

Si el resultado de la operación indicado en el request del mensaje es 1, indicando éxito en la reconstrucción del archivo, la entidad quien expone, podría eliminar el archivo y sus partes o chunks.

NOTA: Para un mayor entendimiento de esta propuesta de implementación, se dispone en la bibliotca GOV.CO de una demo implementada en java – charset UTF-8. 5.2 Servicios con paginación En esta sección se describe la estructura del objeto que se recomienda implementar cuando se requiere paginación. Si la respuesta del servicio retorna una lista mayor de 100 registros, el servicio sería candidato para realizar paginación.

Gráfica 5.2.1: Objeto request propuesto

Content-type: application/json

{[campos de negocio]….,“paginaActual”: int,

“cantidadRegistrosPagina”:int}

14

Gráfica 5.2.2: Objeto response propuesto

NOTA: Si bien las propuestas están planteadas como objetos Json, se puede modelar en xml. A continuación, se listan las recomendaciones generales en esta implementación: - La paginación en el sistema misional es recomendable realizarse a nivel de base de datos a

través del uso de la sentencia OFFSET o equivalente según motor de base de datos. - Si bien la paginación podría hacerse a nivel de capa lógica y no de base de datos, se recomienda

implementar la opción a nivel de base de datos para un mejor uso de recursos de procesamiento y memoria. Sin embargo, existe la posibilidad de hacerse a nivel de capa lógica, calculando los límites de retorno y haciendo uso de la sentencia BETWEEN en la base de datos o equivalente según el motor de base de datos.

- Si bien se recomienda paginar a partir de 100 registros, esta parametrización estará sujeta a la revisión técnica en el diseño del servicio, analizando las capacidades de cada entidad.

5.3 Servicios informativos En esta sección se describen las recomendaciones, lineamientos para la implementación de servicios que retornan la siguiente información: - Información de ayuda - Textos que describen autorización de tratamiento de datos personales - Textos con hipervínculos

Content-type: application/json

{listaNegocio: [

“objNegocio”: {“campo1”: “valor1”,…..

}…]“paginaActual”: int,

“cantidadPaginas”:int}

15

Gráfica 5.3. Servicios informativos

A continuación, se relacionan las características del servicio y su contenido:

- Servicio tipo multipart form-data con dos partes: - Application/Json. Esta parte siempre deberá venir con la estructura indicada en la anterior

imagen. - Octect Stream. Esta parte será requerida cuando el mensaje contiene una imagen. - Atributos del objeto Json: - entidadID. Representa el identificador de la entidad. - Text. Texto informativo para presentarse en el modal. - Hipervínculo. URL del servicio web a consultar para conocer la información relacionada. Esta

URL hará una petición tipo Rest-GET. - cadenaPalabrasHibervinculo. Indicará las palabras del texto que se muestra, las cuales serán

agrupadas por el tag href. - posicionCadenaPalabras. Campo entero que representa la posición de la cadena de palabras

que serán presentadas como un hipervínculo. Si la cadena de palabras se repite más de una vez en el texto, este campo indicará que solo se agruparán por el tag href, la primera, segunda o tercera, dependiendo la especificación del campo. Si el campo no viene informado y hay las palabras se repiten más de una vez, todas las comparaciones serán mostradas como hipervínculo.

- urlVideo. Campo de texto no obligatorio con la url del video youtube. Si se implementa el este servicio como Rest-MultiPart form-data, teniendo en cuenta la implementación de lineamientos de seguridad de los servicios web especificados en este

Content-type: multipart form-data boundary XXXXXXX

PARTE UNO boundary XXXXXXX

Content-type: application/json

{“entidadId”: (int),“texto”: string,“hipervinculo”: string,“cadenaPalabrasHipervinculo”: string”posicionCadenaPalabras”: int“urlVideo”:string

}

PARTE UNO boundary XXXXXXX

Array de bytes

FIN boundary XXXXXXX

16

documento, se podrían presentar diferentes casos o necesidades adicionales que se describen a continuación. Si la tecnología de implementación del servicio es SOAP, se recomienda implementar SOAP-XML codificando base64 el array de bytes del archivo y enviándolo en un tag como parte del xml. Si se desea enviar el archivo de imagen como un array de bytes y la tecnología de implementación es SOAP, se recomienda implementar SOAP MTOM (Message Transmission Optimization Mechanism). Esta implementación permitiría enviar el archivo como array de bytes. Sin embargo, considerar la implementación descrita en el punto anterior. Si la entidad desea adicionar una capa de seguridad al array de bytes del archivo enviado (la cual no sería necesaria si se tuvieron en cuenta los lineamientos de seguridad de servicios web mencionados en este documento), y desea implementar el servicio como Multipart form-data, podría codificar base 64 el array de bytes y enviarlo como un string en la parte octect-stream. Sin embargo, esta implementación representaría que el tamaño del mensaje es mayor y se recomendaría entonces implementar el servicio como rest-json, enviando el archivo como un atributo más del objeto json, pero string codificado base64. Para el caso de SOAP, tener en cuenta la descripción de la primera consideración.

5.4 Servicios y trámites con pagos PSE – Tarjetas de crédito La siguiente información corresponde a los trámites que requieran en alguno de sus pasos un pago a través de PSE o tarjetas de crédito y ya se encuentra implementado por parte de las entidades. Partiendo de que se iniciará el contacto desde GOV.CO se debe implementar una URL con la información que la entidad requiere enviar a la entidad financiera y así mismo se debe implementar una URL con la información que retornará a GOV.CO una vez se procese el pago.

Gráfica 5.4.1. Servicios y trámites con pagos PSE – Tarjetas de crédito

Para garantizar la integridad de los datos se recomienda que las URL tanto de emisión como de recepción hagan uso de claves asimétricas. Las claves asimétricas corresponden a un método que usa un par de claves para el envío de mensajes. Las dos claves pertenecen a la misma persona que recibirá el mensaje. Una clave es pública y se puede entregar a cualquier persona, la otra clave es privada y el propietario debe guardarla de modo que nadie tenga acceso a ella.

17

A continuación, se presenta un ejemplo sobre cómo funcionan las claves asimétricas.

Gráfica 5.4.2. Ejemplo de uso de claves asimétricas Fuente: Criptografía asimétrica2

2 Criptografía asimétrica. (2019, 11 de julio). Wikipedia, La enciclopedia libre. Recuperado de: https://es.wikipedia.org/w/index.php?title=Criptograf%C3%ADa_asim%C3%A9trica&oldid=11734049