AGESIC Gerencia de Proyectos

AGESIC Gerencia de Proyectos Tutorial sobre configuración del componente Conector de la PGE Historial de Revisiones Fecha 10/11/2011 Versión 1.0 Descripción Versión inicial Autor Marcelo Caponi Aprobado Por Nombre actual del archivo: AGESIC-Plataforma-Tutorial-ConectorPGE_v2.0.odt Andes 1365 piso 7º Montevideo Uruguay Tel./Fax: (+598) 2901.2929* Email: contacto@agesic.gub.uy www.agesic.gub.uy

Índice de contenido 1 Introducción...3 2 Instalación y configuración...5 2.1 Configuración básica...5 2.2 Configuración como servicio...7 2.3 Ejecución...7 3 Administración de Conectores...9 3.1 Acceso...9 3.2 Nuevo Conector...11 3.3 Ver Conector...17 3.4 Editar Conector...18 3.5 Eliminar Conector...19 3.6 Ver WSDL...20 3.7 Exportación de Conector...21 3.8 Importación de Conector...22 4 Backup y Restore...24 5 Configuración avanzada...24 [ Nombre del documento] Pág2de 2 Pág. 2 de 5

1 Introducción Cuando un organismo desea consumir un servicio web expuesto en la Plataforma de Gobierno Electrónico (PGE), hay varios aspectos que deben considerarse. Entre éstos, podemos mencionar el marco legal y técnico, intercambio seguro de información, y por último, participación en una arquitectura orientada a servicios (SOA). Estos aspectos requieren de cierto grado de madurez tecnológica, que muchas veces no se tiene en los organismos. A continuación, se listan las tecnologías necesarias según los aspectos antes mencionados para invocar un servicio pasando por la PGE. Marco legal y técnico SAML Firma digital Certificados digitales Intercambio seguro de información WS-Trust WS-Security SSL Arquitectura SOA Web services WS-Addressing Para facilitar el procesos de invocación, se cuenta con librerías provistas por AGESIC tanto para la plataforma Java como para.net. De todas formas, se ha detectado que muchos organismos notan cierta complejidad al intentar invocar. Debido a esto, y para facilitar aún más el proceso de consumo, se desarrolló un aplicativo que hace transparente la complejidad de invocar servicios en la PGE. Este aplicativo es denominado Contector PGE o simplemente Conector. Página 3 de 25

El Conector ejecuta en la infraestructura del cliente y básicamente su propósito es actuar como proxy de la invocación a servicios en la PGE. Por cada servicio expuesto en la PGE, se podrá configurar un servicio virtual en el Conector que represente al servicio real. De esta manera, los clientes invocarán al servicio virtual en el Conector, éste tomará los pedidos, enriquecerá el mensaje con lo requerido por la PGE e invocará al servicio final. Una vez obtenido el resultado, el Conector lo retornará al cliente como si fuese el servicio final. Un diagrama de la arquitectura general se ilustra en la Figura 1. Figura 1: Diagrama de Arquitectura del Conector PGE Para que pueda darse la comunicación, el Conector debe configurarse adecuadamente, y para ello, se cuenta con una consola web de administración. La sección 3, se centra básicamente en detallar cómo configurar un conector para su posterior uso. El propósito de este documento es presentar detalladamente cómo configurar el Conector para invocar servicios expuestos en la PGE. Dado que su uso es muy simple, el tutorial se centrará en la configuración de un servicio en particular, el serivicio de Timestamp provisto por la PGE. El resto del documento se organiza de la siguiente manera, en la sección 2 se muestra como instalar y configurar el Conector. Por último, en la sección 3 se presenta como configurar servicios proxy en el Conector para accceder a servicios expuestos en la PGE. Pág. 4 de 25

2 Instalación y configuración El paquete de instalación del Conector PGE es un archivo de nombre: conector-pge.zip que empaqueta dos carpetas, java y jboss-as. La carpeta java incluye el JDK 1.6 para Windows y Linux, en caso de instalarse en otra plataforma se requiere el JDK correspondiente. La carpeta jboss-as incluye el servidor JBoss ESB en el cual ejecutará el conector. El proceso de instalación del conector consiste en extraer el archivo conectorpge.zip en el directorio deseado. Debe tenerse en cuenta que la única restricción al elegir el directorio es que éste no debe contener espacios en el nombre. Para el resto del documento se asume que la ruta de instalación seleccionada es: /conector-pge. El archivo conector-pge.zip así como los archivos de configuración necesarios para configurar el servicio Timestamp de este tutorial, pueden ser obtenidos de la siguiente ruta: ftp://soporte.agesic.gub.uy/conectorpge. Para acceder se deberá especificar el usuario/password: agesic/publico. En la ruta antes mencionada se encontrará el archivo conector-pge.zip así como una carpeta de nombre archivos tutorial en donde se encontrarán los archivos que se necesitarán para el desarrollo del tutorial. Estos son: Timestamp_wsdl.xml Timestamp_ssl.keystore Timestamp_ssl.truststore Timestamp_organismo.keystore 2.1 Configuración básica Para configurar el conector se deberá abrir el archivo de extensión properties ubicado en la siguiente ruta: /conector-pge/jboss-as/server/default/conf/connector-pge/connectorpge.properties La Figura 2 ilustra las propiedades de este archivo las cuales son explicadas a continuación. Figura 2: Archivo de configuración del Conector PGE Pág. 5 de 25

BASIC_PATH: Configura el path en el file system donde se van a guardar los archivos que necesitan los conectores. En particular, archivos de wsdl y keystores de los conectores que serán discutidos más adelante en el documento. Si la propiedad está comentada, tal cual se ve en la Figura 2, los archivos se guardan por defecto bajo el directorio data de JBoss : /conector-pge/jboss-as/server/default/data HOST: Indica el nombre o dirección IP del equipo donde se instaló el conector. Esta propiedad se utiliza cuando desde la consola de administración se entrega el link al WSDL que representa el servicio a consumir. PORT_TEST: Puerto en donde el conector escucha invocaciones a servicios publicados en la PGE (ambiente de test). En caso de no entrar en conflicto con ningún otro puerto, se recomienda dejar esta propiedad en su valor por defecto, 9800. PORT_PROD: Puerto en donde el conector escucha invocaciones a servicios publicados en la PGE (ambiente de producción). En caso de no entrar en conflicto con ningún otro puerto, se recomienda dejar esta propiedad en su valor por defecto, 9700. stsurl.production: Url en donde se encuentra el servicio de STS para producción. stsurl.test: Url en donde se encuentra el servicio de STS para testeo. Pág. 6 de 25

2.2 Configuración como servicio Es recomendable que el servidor JBoss utilizado por el Conector sea configurado como servicio, para permitir que levante automáticamente cuando se inicia el sistema operativo, a continuación se presentan las páginas que contienen la información de cómo configurar un servidor JBoss como servicio en plataformas Linux o Window. Estas instrucciones se pueden aplicar perfectamente al servidor JBoss incluido en la distribución: Linux Windows 2.3 Ejecución Luego de instalado el conector y configurado como se ilustró en la sección 2.1, para ejecutar el mismo es necesario posicionarse en la carpeta: conector-pge/jboss-as/bin Suponiendo que la IP de la máquina en donde se está ejecutando el conector es: 192.168.10.202, se deberá ejecutar en una terminal el siguiente comando dependiendo de la plataforma subyacente, sea esta Linux o Windows: Linux: "./run.sh -b 192.168.10.202" Windows: "run.bat -b 192.168.10.202" Cuando el servidor es ejecutado de esta manera, puede ser detenido con la combinación de teclas Ctrl-C en la consola donde está siendo ejecutado. Una vez ejecutado el comando anterior, deberá verse un la terminal un log similar al de la Figura 3, donde se resalta que los componentes relativos al conector quedaron instalados, el servidor queda ejecutando, y sin excpeciones de ningún tipo. Pág. 7 de 25

Figura 3: Inicio de servidor JBoss conteniendo al Conector PGE Para confirmar que el conector quedó bien iniciado, se puede confirmar entrando a su consola de administración, la cual puede accederse a través de la siguiente URL: http://192.168.10.202:8080/conector-pge/1 Accediendo a esta URL se deberá ver la interfaz gráfica de la consola de administración tal como se ilustra en la Figura 4. Figura 4: Página inicial de la consola de administración del Conector PGE 1 Cabe aclarar que la URL que se presenta depende de la IP configurada, que para el caso del ejemplo es: 192.168.10.202, en caso de utilizarse otra, debe sustituirse en la URL. Pág. 8 de 25

3 Administración de Conectores En las siguientes subsecciones se detalla el uso de la consola de administración del Conector para configurar servicios proxy que accedan a servicios publicados en la PGE. Se comenzará creando un servicio proxy para acceder al servicio Timestamp, se ilustrará paso a paso su configuación, y a partir de éste luego se ilustrará cómo realizar operaciones de mantenimiento sobre el mismo (edición, eliminación, exportación, etc). 3.1 Acceso Para acceder al Conector una vez instalado y configurado como se especificó en la sección 2, se debe acceder a la consola de administración que se presentó en la Figura 4. Se debe proporcionar usuario/password para acceder. Por defecto, se puede acceder con usuario/password igual a conector/conector. Por detalles de cómo cambiar el usuario y las formas de autenticación, se puede consultar la sección 5. Al acceder al conector se desplegará una pantalla tal como se ilustra en la Figura 5 en donde puede apreciarse el listado de conectores. Figura 5: Listado de Conectores para ambiente de producción Pág. 9 de 25

Cada línea en el listado representa un proxy a un servicio (conector), esto es, un punto de acceso a un servicio en un organismo a través del Conector. Se puede apreciar que la pantalla tiene un filtro por tipo de conector. Esto debe ser tenido en cuenta dado que al definir un conector se deberá especificar si éste invocará a un servicio final en ambiente de test o producción. En caso de querer tener un conector para un servicio en producción y además para el mismo servicio en test, se deberán crear dos conectores independientes cada uno para su respectivo ambiente. Para poder visualizar los conectores definidos para los diferentes ambientes, "Test" o "Producción" bastará con filtrar por el campo Tipo, ubicado en la esquina superior izquierda. Por cada conector se permiten varias acciones como ser: Ver, Editar, Borrar, obtener el WSDL, y obtener el xml de exportación. Estás aparecen representadas de izquierda a derecha con botones en la columna acciones respectivamente. En la figura 6 se detallan los botones de acciones. Figura 6: Botones de acción para los conectores A continuación, en las siguientes subsecciones se detalla el funcionamiento de cada una de estas acciones. Pág. 10 de 25

3.2 Nuevo Conector Para crear un conector presionamos el botón Nuevo Conector que aparece en la pantalla inicial y cargamos la totalidad de los campos dado que éstos son requeridos. En el ingreso de datos, si no se ingresa alguno de los campos requeridos al momento de presionar el botón salvar, se volverá a mostrar la misma página indicando cual es el campo en el cual no se ingresaron datos. La combinación "Nombre" - "Tipo" tiene que ser única en el sistema, así como también la combinación "Path" "Tipo". Es importante tener esto en cuenta dado que si no se desplegará una validación que indicará que no es posible dar de alta un conector. Lo mismo se da en la importación si se quiere dar de alta un conector con la combinación similar antes mencionada. En la Figura 7 se ilustra la pantalla que se desplega una vez que se presiona el botón Nuevo Conector, una explicación detallada de los campos se presenta más abajo. Figura 7: Pantalla de creación de nuevo Conector Pág. 11 de 25

Como se mencionó anteriormente, el conector que se creará será un proxy al servicio Timestamp. A continuación, se detalla la semántica de los campos y el valor correspondiente que deben tomar para este caso particular del servicio Timestamp. Nombre: Nombre del Servicio. Se usa como identificación interna del servicio y junto con el Tipo deben ser únicos. Este valor es elegido por el usuario e independiente del servicio, en el caso del ejemplo ingresamos: Timestamp. Tipo: El tipo de servicio identifica si el servicio que se desea consumir pertenece al ambiente de Test o de Producción. En el caso del ejemplo seleccionamos Test dado que deseamos consumir un servicio del ambiente de Test. Descripción: Información descriptiva del servicio sin uso operativo. Este valor también es definido por el usuario, en el caso del ejemplo ingresamos: Servicio Timestamp de Test. Path: El campo Path es una parte de la url en donde quedará disponible el WSDL del servicio proxy que se está dando de alta. Los WSDLs quedaran disponibles en una URL compuesta de tres partes: host, puerto y Path. El valor de host es el nombre de la maquina, el puerto es 9800 y 9700 para test y producción respectivamente, y Path es el valor que se coloca en este campo. De esta manera, la URL en donde se desplegará el WSDL del servicio virtual a construir serán de la siguiente forma: http://server_host:9800/path?wsdl (producción) http://server_host:9700/path?wsdl (test) Es el path relativo en donde queda publicado el servicio. Para el caso del ejemplo, definimos el siguiente path: /Test/Timestamp Una vez terminada la publicación, cuando presionemos la acción ver WSDL, éste será desplegado en la url: http://server_host:9800/test/timestamp. Los puertos 9800 y 9700 para producción y test respectivamente son los que se eligieron en el archivo de configuración ilustrado en la Figura 2. wsa:to: Este dato se agrega como Header del mensaje SOAP. Corresponde a un endpoint lógico, indica cual es el Web Service que se quiere invocar a través de la plataforma. Este daro es proporcionado por AGESIC cuando se brinda el formulario con la información necesaria para invocar al servicio. Para el caso del ejemplo, colocamos el siguiente valor: http://test.pge.red.uy/timestamp Pág. 12 de 25

Username: Es el usuario dentro del organismo que desea acceder al servicio final, este dato es utilizado para la firma del mensaje SOAP. Debe ser proporcionado por el organismo consumidor. Cabe mencionar que no se hará ninguna validación sobre este campo, pero es necesario colocar un valor que tenga sentido para el organismo a efectos de auditoría de transacciones. En este caso se especifica el valor: usuarioorganismo. Organismo: Es el nombre que representa al organismo consumidor, este dato es utilizado también para la firma del mensaje SOAP. Y tiene el mismo propósito que el campo anterior. En este caso se especifica el valor: Organismo. Tipo de Token: Dato utilizado para la firma del SOAP. En el caso de Test, el valor de este campo debe ser: urn:tokensimple. En el caso de Producción debe ser: urn:std15. Como estamos intentando consumir un servicio del ambiente de Test, se define en este caso el valor: urn:tokensimple. Alias del Keystore Organismo: El valor de este campo tiene el alias con el que se va a obtener el certificado de organismo dentro del keystore. El keystore de organismo se encuentra en el archivo cargado en el campo el "Keystore Organismo". En el ejemplo se especifica el valor: 0f026f823ca3597ced3953188b1628de_be45dff3-4f56-4728-8332-77080b0c1c08 Password Keystore Organismo: Este campo representa al password del "Keystore Organismo". En el ejemplo, se debe de especificar: agesic. Password Keystore SSL: Este campo representa al password del "Keystore SSL". Este password es utilizado para acceder al certificado del keystore para el acceso por https. En el ejemplo, se debe de especificar: agesic. Password Truststore: Este campo representa al password que es utilizado para acceder al certificado del trustore para el acceso por https. En el ejemplo, se debe de especificar: agesic. WSDL: En este campo se debe cargar el WSDL del servicio final. Cabe mencionar que en éste WSDL, el campo address debe tener en su atributo location la url del servicio final a invocar. El Conector tomará esta url del WSDL para realizar la invocación. Debe tenerse esto presente para configurar adecuadamente el WSDL antes de cargarlo en el contector que se está dando de alta. El valor de la url tomado desde el WSDL podrá verse una vez cargado el conector y que se presione la acción Ver/Modificar. Pero no será un campo editable dado que siempre será tomado del WSDL. En el ejemplo, se carga el archivo: Timestamp_wsdl.xml. Pág. 13 de 25

Keystore Organismo: En este campo se debe cargar el archivo de keystore de organismo utilizado para la firma del mensaje SOAP. En el ejemplo, se carga el archivo: Timestamp_organismo.keystore. Keystore SSL: En este campo se debe cargar el archivo de keystore utilizado para la comunicación HTTPS. En el caso del ejemplo, se carga el archivo: Timestamp_ssl.keystore. Truststore SSL: En este campo se carga el archivo de truststore utilizado para la comunicación HTTPS (autenticación mutua). En el caso del ejemplo, se carga el archivo: Timestamp_ssl.truststore. Figura 8: Pantalla de alta de un conector con los campos ya cargados En la figura 8 se ilustra una imagen con los campos ya cargados, para continuar con la carga, se debe presionar el botón refrescar que está a la derecha del campo WSDL. Este botón (resaltado en rojo, lo que hace es cargar los archivos seleccionados, y a su vez, parsear las operaciones del WSDL. Por lo tanto, una vez presionado, se carga automaticamente la sección Rol Operación con una tabla para que se carguen por cada operación del WSDL, los campos Rol y wsa:action. Pág. 14 de 25

El resultado luego de presionar el botón mencionado puede apreciarse en la figura 9. Figura 9: Sección Rol-Operación habilitada luego de que fueron parseadas las operaciones en el WSDL Los campos que deberán ahora cargarse son Rol y wsa:action por cada una de las operaciones del WSDL. A continuación se explica el cometido de cada uno de éstos así como el valor que deben tomar para la configuración del conector para el servicio de Timestamp. Pág. 15 de 25

Rol: El rol es utilizado para autorizar el acceso a los servicios, es proporcionado por AGESIC para cada una de las operaciones que se desea invocar. En el caso del ejemplo, cargar con el siguiente valor: OU=TEST_TUTORIAL,O=TEST_PE. wsa:action: Este campo determina el método que se va a invocar en el servicio final. Es un dato que viene en el WSDL dentro del tag operation, atributo soapaction. En el caso del ejemplo, cargar con el siguiente valor: http://test.pge.red.uy/timestamp/gettimestamp. Una vez finalizada la carga, se presiona el botón Salvar, y se ha terminado de crear el conector. Para confirmar que todo se ha cargado correctamente, se puede apreciar una pantalla similar a la de la figura 10. Si ustede llegó a este paso sin problemas, ha dado de alta satisfactoriamente un conector que accede al servicio Timestamp. En las siguientes subsecciones se mostrará como realizar operaciones de mantenimiento sobre este conector. Figura 10: Pantalla que se desplega luego de dar de alta un conector Pág. 16 de 25

3.3 Ver Conector Una vez creado un conector podrá visualizarse el mismo presionando sobre éste la acción Ver Conector que se representa con un ícono similar a una lupa. De esta manera, podrán verse la totalidad de los campos del conector. Se permite además, la posibilidad de borrar o editar el conector presionando el botón correspondiente que aparece en el pie de la pantalla (Editar, Borrar). Un ejemplo de la pantalla que se desplega luego de seleccionar la acción Ver Conector se ilusta en la Figura 11. Figura 11: Pantalla de modificación de un conector Pág. 17 de 25

3.4 Editar Conector Para editar un conector, se podrá acceder a la pantalla de edición desde todas las pantallas. Desde el listado de conectores se accede a través de la acción Editar Conector. En el resto de las pantallas se podrá acceder a través del botón Editar que se ubica en el pie de la pantalla. Como se ilustra en la figura 12 se podrán editar todos los campos exceptuando Nombre, Tipo y Url. Pág. 18 de 25

Figura 12: Pantalla de modificación de un Conector 3.5 Eliminar Conector Se podrá borrar un conector desde el listado de conectores presionando la acción Borrar Conector. A su vez, en el resto de las pantallas se podrá acceder a través del botón Borrar que se ubica en el pie de la pantalla. En todos los casos que se desee borrar un conector, se pedirá confirmación tal como se ilustra en la figura 13. Pág. 19 de 25

Figura 13: Confirmación de eliminación de un conector 3.6 Ver WSDL Para ver el WSDL generado para un conector, se debe presionar la acción WSDL que se ilustra resaltada en la figura 14. Figura 14: Acción ver WSDL Pág. 20 de 25

Luego se puede ver como en la figura 15 el WSDL generado. Dicho WSDL es el que se debe consumir para acceder al servicio publicado en plataforma, en esta caso particular el servicio de Timestamp. Es interesante destacar el formato de la url generada, la misma respeta lo mencionado en la sección 3.2. Figura 15: WSDL generado para el servicio de Timestamp 3.7 Exportación de Conector Para exportar un conector, se podrá acceder desde el listado de conectores seleccionando la acción exportar, o desde cualquier pantalla presionando el link exportar que se encuentra en el pie de pantalla, en la esquina inferior derecha. Una vez presionada la acción de exportar nos aparece la opción para guardar la exportación en un archivo xml. En la figura 16 se ilustra la pantalla de exportación luego de iniciar tal acción. Pág. 21 de 25

Figura 16: Pantalla de exportación de conector A continuación, en la figura 17 se ilustra el XML generado en la exportación. Este podrá posteriormente ser importado. Pág. 22 de 25 Figura 17: XML de exportación

3.8 Importación de Conector Para importar un conector, existe un área de importación en donde se debe seleccionar un archivo XML exportado previamente. En la sección 3.7 se presentó el procedimiento de exportación. En la figura 18 se ilustra la sección de importación. Figura 18: Sección de importación de conectores Luego de seleccionar un archivo y realizar la importación se desplegará una pantalla como la de la figura 19, presionando el botón Volver, se retorna a la pantalla principal con el listado de conectores, y se puede ver el nuevo conector importado. Pág. 23 de 25

Figura 19: Pantalla luego de importar un conector Debe tenerse en cuenta al importar que la combinación "Nombre" - "Tipo" tiene que ser única en el sistema, así como también la combinación "Path" "Tipo". Por lo tanto, en caso de que exista un conector ya en el sistema que entre en conflicto según lo antes mencionado, se desplegará una validación que impedirá la importación. 4 Backup y Restore La Base de Datos del conector se encuentra representada a través de una carpeta en el file system, ubicada en la ruta: Pág. 24 de 25

/conector-pge/jboss-as/server/default/data/derby/connectorpgedb Por lo tanto, el Backup se basa en respaldar tal carpeta, y el Restore en sustituirla por otra que haya sido respaldada. Debe considerarse que para realizar las maniobras de Backup y Restore el servidor debe estar bajo porque se pueden presentar inconsistencias. 5 Configuración avanzada El mecanismo de autenticación y autorización del Conector es a través de archivos. En caso de querer cambiar los usuarios y los roles que accedan al sistema, se deberá acceder a la carpeta: /conector-pge/jboss-as/server/default/conf/props. En esta carpeta se encuentran dos archivos de configuración para llevar a cabo tal propósito. Estos son: connector-pge-users.properties connector-pge-roles.properties Si se desea cambiar el método de autenticación, y que éste no sea más a partir de archivos se deberá configurar especificar el nuevo mencanismo en el archivo login-config.xml que se encuentra en: /conector-pge/jboss-as/server/default/conf/. En tal archivos se podrá seleccionar la nueva policy usada para la autenticación y autorización como ser LDAP, Base de Datos, etc. Pág. 25 de 25