ATLAS MANUAL DE USUARIO Servicios Web

Transcripción

1 ATLAS MANUAL DE USUARIO Servicios Web Versión 1.7 Arquitectura de Software

2 Hoja de Control Título Documento de Referencia Responsable Manual de Usuario Invocador de Servicios NORMATIVA ATLAS Arquitectura de Software Versión 1.7 Fecha Versión 03/12/2014 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha 1.0 Versión inicial del documento Arquitectura de Software 18/10/ Nuevo modelo de seguridad. Apartados 3.3 y Arquitectura de Software 24/02/ Migracion a Axis Apartado 3.1.1: nuevo submódulo test Apartados y 3.3.1: ejemplos de solicitud y respuesta de alta en ASF. Apartado 3.2.2: la edición del fichero de Spring ya no es necesaria Apartados y 3.3.3: aclaración sobre operaciones en ASF. Apartado 3.2.4: aclaración sobre código de ejemplo. Apartado 3.2.6: paso no necesario. Apartado 3.3.2: la edición del fichero de Spring ya no es necesaria. Apartado 3.6: cambiado ejemplo generado. Apartado 3.6.3: cambiada definición de servicio. Desaparece la capa de fachada Apartado 3.6.4: la edición del fichero de Spring ya no es necesaria. Cambiada definición de servicio. Apartado 3.6.5: nuevo apartado. Apartado 3.7: nuevo apartado. Apartado 3.8: nuevo apartado. Arquitectura de Software 25/10/ de 82

3 Versión Causa del Cambio Responsable del Cambio Fecha Añadido apartado 7 con nuevas configuraciones de seguridad Apartado Obligación de parametrizar el endpoint del servicio. Cambiada referencia AsfService por CryptService. 1.3 Se decide que la seguridad en los servicios web se implementará mediante WS Security en los servicios web Arquitectura de Software 20/12/2012 desarrollados con Atlas. Esto implica modificación del arquetipo de servicio web para que tenga solamente ejemplo de WS y las correspondientes modificaciones de este documento debidas a estos cambios. Nuevo apartado 5.2 con instrucciones para la configuración de proxy. 1.4 Modificado apartado para incluir el caso de que el wsdl Arquitectura de Software 27/05/2013 no sea autogenerado si no que se parta de un wsdl predeterminado Cambiado nombre de miprimerservicio a miservicioweb para distinguirlo del servicio que lo invoca y arreglados los 1.5 ejemplos del apartado Unidad de Arquitectura 24/9/2013 Añadido aviso para cifrar contraseñas en apartados 4.2.6, y Añadida nota de modificación de weblogic.xml en apartado Añadido apartado 8 para documentar errores más comunes Unidad de Arquitectura 07/04/2014 Nuevo parámetro de configuración en apartado Añadido apartado 5.3 Añadido punto Paso 5: Cambio del namespace del servicio (si se necesita) Añadido punto Paso 5: Eliminar Namespaces, Elements y Atributos (si se necesita) 1.7 Añadido punto 7.4: Error al ejecutar Peticiones a Servicios Unidad de Arquitectura 09/12/2014 Web Seguro desde entorno local Añadido punto y para llamara un servicio web a traés de un proxy y también establecer un timeout a un cliente. 3 de 82

4 Índice 1. INTRODUCCIÓN AUDIENCIA OBJETIVO CONOCIMIENTOS PREVIOS DESCRIPCIÓN DESARROLLO DE UN SERVICIO WEB CREACIÓN DE UN SERVICIO WEB Paso 1: Creación del módulo partiendo del Arquetipo de servicio web Paso 2: Creación de la Interfaz del Servicio y clases para los parámetros Paso 3: Implementación del Servicio Paso 4: Configuración del Servicio Paso 5: Cambio del namespace del servicio (si se necesita) Paso 6: Eliminar Namespaces, Elements y Atributos (Si se necesita) Paso 7: Levantar el Servidor Paso 8: Obtener el wsdl del Servicio Paso 9: Creación del Cliente Paso 10: Configuración del Cliente Paso 11: Test Unitarios del Cliente IMPLEMENTACION DE SEGURIDAD CON WS SECURITY Paso 1: Alta de la aplicación en la plataforma ASF Paso 2: Configuración del Servicio Paso 3: Actualización de configuración en el fichero services.xml Paso 4: Modificar Cliente Paso 5: Configuración del Cliente Acceso al certificado de cliente DESARROLLO DE UN CLIENTE DE SERVICIO WEB CLIENTE DE UN SERVICIO ATLAS Paso 1: Inclusión de la dependencia Paso 2: Configuración del contexto de Spring Paso 3: Configuración del endpoint en environment.properties Paso 4: Inclusión de Seguridad: WS Security CLIENTE DE UN SERVICIO NO ATLAS Paso 1: Incluir fichero wsdl en el proyecto Paso 2: Inclusión de la dependencia y configuración del plugin Paso 2: Generación de la clases del Cliente Paso 3: Configuración y uso del Cliente Paso 4 (Opcional): Llamara a un Servicio Web a través de un Proxy Paso 5 (Opcional): Agregar un timeout a un cliente de servicio web Paso 4a: Inclusión de Seguridad; WS Security (sólo para servicios seguros) Paso 4b: Inclusión de Seguridad a nivel de transporte (sólo para servicios seguros) Llamadas a Servicios Web Con Usuario y Password usando HHTP Basic EN ESTE CONSTRUCTOR, OBSERVAREMOS EL SIGUIENTE CÓDIGO: UTILIDADES MÓDULO DE LOG DE MENSAJES CONFIGURACIÓN DE PROXY PERSONALIZACIÓN DE MENSAJES DE ERROR Especificación SoapFault SCSPv CREACION DE TESTS UNITARIOS PARA SOAPUI Proyecto SoapUI sin seguridad Proyecto SoapUI con seguridad https de 82

5 Proyecto SoapUI con seguridad firmado/cifrado OTRAS CONFIGURACIONES DE SEGURIDAD SERVICIO WEB CON FIRMADO DE MENSAJE Y AUTENTICACIÓN HTTPS Servicio web Cliente ATLAS Cliente NO ATLAS Tests de SoapUI IMPLEMENTACION DE SEGURIDAD A NIVEL DE TRANSPORTE Paso 1: Configuración de la aplicación en el entorno ASF Paso 2: Activar los servicios de comunicación con ASF Paso 3: Configuración de la seguridad en el fichero services.xml Paso 4 (Opcional): Obtención del certificado de cliente Paso 5: Inclusión de la seguridad en la librería cliente: Extender otra clase Paso 6: Inclusión de la seguridad en la librería cliente: Definir propiedades ERRORES MÁS COMUNES NO SE ENCUENTRA EL FICHERO WSDL DE UN SERVICIO (NO AUTOGENERADO) NO SE RECONOCE EL MÉTODO EN UN CLIENTE DE AXIS2 EN LA LLAMADA A UN SERVICIO DE AXIS ERROR AL GENERAR UN CLIENTE DE AXIS2 A PARTÍR DEL WSDL DEL SERVICIO ERROR AL EJECUTAR PETICIONES A SERVICIOS WEB SEGURO DESDE ENTORNO LOCAL ENLACES RELACIONADOS de 82

6 1. INTRODUCCIÓN En algunas ocasiones es necesario que las aplicaciones ofrezcan determinados Servicios Web tanto a otras aplicaciones de la Comunidad de Madrid como a agentes externos. Por otra parte muchas de las aplicaciones que se desarrollan para la Comunidad de Madrid necesitan acceder a Servicios Web (tanto servicios que se han desarrollado específicamente para la tramitación electrónica como otros servicios web que incluso pueden estar fuera de los entornos de ICM). En este manual se describe cómo crear servicios web con el framework ATLAS, así como invocar a servicios web existentes (creados con ATLAS o no). El manual incluye documentación sobre la creación/invocación de servicios web con seguridad o sin ella. Para aislar la complejidad de la amplia variedad de tipos de servicios web que nos podemos encontrar y los distintos tipos de seguridad que nos pueden requerir los citados servicios web se ha desarrollado el componente Invocador de Servicios de Atlas. Este componente facilita la creación de los clientes de acceso a los servicios securizados, a través de una sencilla configuración que pueda incluir los requisitos de seguridad requeridos Audiencia objetivo Este documento está orientado a desarrolladores java que quieran invocar a un servicio web desde un aplicativo que se desarrolla con Atlas o que quieren generar un servicio web Conocimientos Previos Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes tecnologías: - Spring Framework. - Servicios Web - Axis2 y Rampart - Seguridad (uso básico de certificados) 6 de 82

7 2. DESCRIPCIÓN La invocación y generación de servicios web de ATLAS se basa en los siguientes elementos: Axis2 Módulo de seguridad Rampart Módulo de seguridad para webservices de ATLAS Para la creación de nuevos servicios web se partirá de un arquetipo específico para servicios web. Los servicios web desarrollados implementaran además del propio servicio web una librería cliente para dicho servicio que facilitará la integración de este servicio web en otros proyectos Atlas. Para implementar un servicio web es necesario: Definir la interfaz del Servicio (Como una clase Java) Implementar en el servicio web dicha interfaz Implementar un cliente del servicio web A continuación se muestra un diagrama de clases para un ejemplo de un servicio llamado MiPrimerService: 7 de 82

8 Para el desarrollo de un cliente de un servicio web se van a distinguir dos casos: Servicios web desarrollados con Atlas Servicios web externos o no desarrollados con Atlas. En este último caso se utiliza el cliente dinámico de Axis2, que está basado en la clase RPCServiceClient y permite hacer llamadas a servicios web de forma sencilla, sin necesidad de generación de clases compiladas (a través del descriptor WSDL del servicio y las herramientas de Axis2). En los servicios web podemos distinguir los distintos tipos de accesos: Acceso público Servicio de acceso libre. No se realiza ningún tipo de control sobre el cliente. El canal de comunicación no está cifrado. Cliente WS Servidor WS HTTP Acceso público securizado Servicio de acceso libre. No se realiza ningún tipo de control sobre el cliente. Canal cifrado de comunicación. Para establecer la comunicación el cliente debe confiar en el certificado del servidor. Cliente WS Servidor WS HTTPS Trusted CA SSL Server Acceso privado con certificado digital cliente Servicio de acceso restringido. Se realiza control de acceso sobre el cliente identificado por el certificado digital requerido. Canal cifrado de comunicación. Para establecer la comunicación el cliente y servidor deben confiar en sus respectivos certificados. Es habitual que el cliente utilice un tipo de certificado cliente denominado de componente (no personal). 8 de 82

9 Cliente WS Servidor WS HTTPS SSL Client Client trusted Server trusted SSL Server Server trusted de la CAM Servidores Web Caché WS-Security: Mensaje SOAP firmado y cifrado El mensaje SOAP se firma y cifra para garantizar la integridad de los datos enviados. Se puede realizar el control de acceso sobre el cliente que ha firmado el mensaje. Al cifrar el mensaje no es necesario cifrar el canal de comunicación. Dentro del framework Atlas se soportan todos estos tipos de accesos y en este documento se describirán como implementarlos tanto en la parte cliente como en la servidora. Cualquier otro tipo de acceso o de seguridad que se requiera implementar que sea distinto de los anteriores ha de ser autorizado previamente por el área de arquitectura de ICM. Este documento se divide en dos partes bien diferenciadas: - Desarrollo de un servicio web - Desarrollo de un cliente de un servicio web 9 de 82

10 3. DESARROLLO DE UN SERVICIO WEB En este apartado se muestra cómo crear un servicio web con el framework ATLAS, así como el procedimiento para aportar seguridad al servicio web (integrándose con la plataforma ASF). Para el desarrollo de servicios web el framework se apoya en las siguientes tecnologías: Axis 2: Framework java para desarrollo de servicios web de la ASF (Apache Software Foundation). Rampart: Módulo de seguridad de Axis 2. Wss4j: Implementación estándar de seguridad en servicios web. Xmlsec: Estándar de seguridad para ficheros XML en que se basa el estándar WSS (Web Services Security). Además de esto, el framework ATLAS aporta los siguientes elementos propios: Arquetipo de generación de proyectos de tipo servicio web. La generación de proyectos para servicios web es muy sencilla a través del arquetipo ATLAS destinado a tal efecto. En este manual se muestra cómo crear un servicio web a partir del arquetipo. Módulo de seguridad para integración con la plataforma de seguridad ASF 5. En este documento también se muestra cómo configurar un arquetipo para integrarse con dicha plataforma. 10 de 82

11 3.1. CREACIÓN DE UN SERVICIO WEB En los siguientes sub-apartados se muestra cómo crear un servicio web con el framework Atlas Paso 1: Creación del módulo partiendo del Arquetipo de servicio web El framework ATLAS tiene disponible un arquetipo preconfigurado y preparado para la creación de proyectos de servicios web. El uso de este arquetipo genera una primera versión de proyecto con clases demostrativas del uso y funcionalidad. Para la creación de proyecto de servicio web partiendo de un arquetipo consultar el manual ATLAS_MUS_Arquetipo_WebService. Una vez generado el arquetipo según se indica en este manual, proseguir con los pasos indicados en este apartado. ATENCION La creación de servicios web debe ser realizada siempre en base al arquetipo atlasfrmarquetipos-generador-servicioweb, según se explica en el manual ATLAS_MUS_Arquetipo_WebService El arquetipo de servicio web de ATLAS generará un proyecto modular, que contiene tres módulos: - web: El servicio web expuesto. - test: tests de SoapUI para el servicio web. - lib: Librería (jar) que contiene las clases que definen el interfaz del servicio web a exponer, así como los objetos de dominio. Se han separado estas clases en una librería aparte porque esta librería podrá ser utilizada en otros proyectos para invocar al servicio web. El arquetipo de servicio web contiene un ejemplo de servicio web llamado EjemploServicio. ATENCION Las clases de servicio que se van a crear son las mismas que las que se definen en la capa de servicios de la normativa de Atlas, por lo tanto les aplica la misma normativa Paso 2: Creación de la Interfaz del Servicio y clases para los parámetros La interfaz del servicio debe ser creada dentro del módulo lib, de esta forma es compartido por el servicio web y por la aplicación cliente del servicio web. El módulo web contiene una dependencia del módulo lib de forma que las clases del módulo lib estarán accesibles desde el web. 11 de 82

12 ATENCION La creación de las clases que representan la interfaz del servicio web se realizará dentro del módulo lib del proyecto. Por ejemplo nos creamos la interfaz siguiente: Clase lib/src/main/java/xxxx/services/miprimerservice.java package prueba123.services; import atlas.core.exceptions.serviceexception; public interface MiPrimerService { String getfechastring() throws ServiceException; } Tal y como indica la normativa de Atlas con respecto a los servicios todos los métodos deben lanzan ServiceException cuando ocurre algún problema. Si la interfaz del servicio incluye parámetros que no son tipo básicos hay que crear una clase para cada uno de los parámetros. En la interfaz EjemploServicio que se incluye de ejemplo en el arquetipo, se define un objeto de entrada llamado DatosEntrada y un objeto de salida, llamado DatosSalida. Estos objetos de datos tienen que ser creados en el módulo lib del cliente ya que serán usados tanto por el cliente y por el servicio web. ATENCION La creación de las clases que representan los objetos de entrada/salida del servicio web se realizará dentro del módulo lib del proyecto. Además estos objetos no pueden ser objetos de dominio de Hibernate sino simples POJOS y serializables. 12 de 82

13 A continuación se muestra el código de alguno de estos objetos: Clase lib/src/main/java/xxxx/domain/datosentrada.java public class DatosEntrada implements Serializable { private static final long serialversionuid = L; String cadena1; Integer limite = -1; public String getcadena1() { return cadena1; } public void setcadena1(string cadena1) { this.cadena1 = cadena1; } public Integer getlimite() { return limite; } public void setlimite(integer limite) { this.limite = limite; } } Paso 3: Implementación del Servicio Una vez creada la interfaz del servicio, debemos proceder a crear la clase que implementa dicha interfaz. La implementación del servicio web tendrá las siguientes características: Se creará en el módulo web del proyecto. Residirá en el mismo paquete que la interfaz del servicio en el módulo de cliente. Su nombre será el de la interfaz de servicio acabado en Impl siguiendo la normativa de creación de servicios de ATLAS. Incluirá la ATENCION La creación de las clases que implementan el servicio web se realizará dentro del módulo web del proyecto, y pertenecerán al mismo paquete que las interfaces que implementan. 13 de 82

14 A continuación mostramos una implementación de ejemplo: Clase lib/src/main/java/xxxx/services/miprimerserviceimpl.java package prueba123.services; import org.springframework.stereotype.service; import public class MiPrimerServiceImpl implements MiPrimerService{ public String getfechastring() throws ServiceException { return "fecha"; } Paso 4: Configuración del Servicio Para que el servicio web esté accesible será necesario realizar dos configuraciones: Definir un bean en el contexto de Spring para la clase implementada del Servicio en el fichero web/src/main/resources/conf/applicationcontext-services.xml, Fichero web/src/main/resources/conf/applicationcontext-services.xml <?xml version="1.0" encoding="utf-8"?> <beans> <bean id="miprimerservice" class="ejpl.services.miprimerserviceimpl" /> </beans> Definir el servicio en el fichero de axis web/src/main/webapp/web-inf/services.xml. 14 de 82

15 En el fichero service.xml están todas las definiciones de servicios web que necesita Axis2. Cada tag <service> define un webservice diferente. Fichero web/src/main/webapp/web-inf/services.xml <service name="miservicioweb"> <parameter name="serviceobjectsupplier" locked="false"> org.apache.axis2.extensions.spring.receivers.springservletcontextobjectsupplier </parameter> <parameter name="springbeanname" ocked="false">miprimerservice</parameter> <parameter name="serviceclass" locked="false">prueba123.services.miprimerservice </parameter> <messagereceivers> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcmessagereceiver" /> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcinonlymessagereceiver" /> </messagereceivers> </service> Se ha de incluir un tag de service como el que se muestra de ejemplo modificando los siguientes parámetros: SpringBeanName: nombre del bean que se definió en el fichero applicationcontext-services.xml. ServiceClass: Nombre de la clase (con su paquete correspondiente) que representa el interfaz del servicio (se utiliza para la construcción del descriptor WSDL) Paso 5: Cambio del namespace del servicio (si se necesita) Si se quiere modificar el namespace del servicio web generado por defecto se hace modificando las propiedades xmlns:ns y targetnamespace y añadiendo el tag <schema schemanamespace=""/> Por ejemplo para cambiarlo a Fichero web/src/main/webapp/web-inf/services.xml <service name="miservicioweb" xmlns:ns=" targetnamespace=" <schema schemanamespace=" </service> 15 de 82

16 Paso 6: Eliminar Namespaces, Elements y Atributos (Si se necesita) Framework Atlas ATENCION Para hacer los cambios propuestos en este punto se deberá pedir una autorización excepcional a Arquitectura explicando la necesidad de usarlo, ya que un cambio en la respuesta XML de un Web Service puede hacer que los clientes no puedan leerla correctamente Si se quiere modificar cualquier parte del xml de respuesta que se envía como respuesta del servicio se deberá hacer uso del patrón message exchange pattern (MEP) creando una clase que implemente la clase abstracta AtlasInOutMessageReceiver y hacer un Override del método modificarrespuesta, esta clase se deberá indicar en el Services.xml en a nivel de todo el servicio o solo a nivel de una operación, a continuación se ponen ambos ejemplos: Fichero web/src/main/webapp/web-inf/services.xml  <service name="ejemploservice">... <messagereceivers> <messagereceiver mep=" class="ws128.services.miinterceptor" /> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcinonlymessagereceiver" /> </messagereceivers> </service> Fichero web/src/main/webapp/web-inf/services.xml  <service name="ejemploservice">... <messagereceivers> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcmessagereceiver" /> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcinonlymessagereceiver" /> </messagereceivers> <operation name="alterar"> <messagereceiver class="ws128.services.miinterceptor"/> </operation> </service> 16 de 82

17 La clase MiInterceptor sería de la siguiente forma: package ws128.services; MiInterceptor.java import atlas.clientews.client.atlasinoutmessagereceiver; public class MiInterceptor extends AtlasInOutMessageReceiver public String modificarrespuesta(string respuesta) { //Estos reemplazos son solo de ejemplo respuesta = respuesta.replaceall("<ns:", "<"); respuesta = respuesta.replaceall("</ns:", "</"); respuesta = respuesta.replaceall("xsi:type=\"ax23:datossalida\"", ""); return respuesta; } } Paso 7: Levantar el Servidor Una vez configurado el servicio web, para probarlo deberá ejecutarse el servidor Jetty según se explica en el manual ATLAS_MUS_Arquetipo_WebService. Para comprobar que se ha levantado correctamente y que están disponibles los servicios se puede acceder a la url y nos debe aparecer una pantalla similar a esta: Paso 8: Obtener el wsdl del Servicio Para obtener el wsdl de nuestro servicio web se puede a través de una url del siguiente tipo: 17 de 82

18 Este wsdl se ha de guardar en el módulo test en la carpeta test/src/main/resources/wsdl con el nombre del servicio y la extensión wsdl. Ej: MiServicioWeb.wsdl. En el caso de que el servicio web se construya a partir de un wsdl predeterminado (que no hay sido generada por Axis) al intentar acceder al wsdl se obtiene el siguiente error: <error> <description>unable to generate WSDL 1.1 for this service</description> <reason>if you wish Axis2 to automatically generate the WSDL 1.1, then please set useoriginalwsdl as false in your services.xml</reason> </error> Para poder obtener correctamente el wsdl es necesario realizar lo siguiente: 1. - Si el WSDL predeterminado del servicio es un solo fichero, se ha de hacer lo siguiente: a.- En el fichero WEB-INF/services.xml, en la definición del servicio se coloca el siguiente parámetro: <parameter name="useoriginalwsdl">true</parameter> b.- Para que el fichero WSDL pueda ser localizado y entregado, este ha de dejarse, con el nombre del servicio en el directorio WEB-INF. Un ejemplo, si tengo el servicio 'EjemploServicio', además del parámetro 'useoriginalwsdl' tendrá que haber un fichero: ---->WEB-INF/EjemploServicio.wsdl 18 de 82

19 En este caso el wsdl se obtendría con la URL: Si el WSDL consta de varios ficheros, además del parámetro 'useoriginalwsdl' en la definición del servicio, este ha de generarse en formato aar o 'exploded' (contenido del aar descomprimido). La esctructura en formato 'exploded' sería la siguiente (con EjemploServicioNoSeguro): ---->WEB-INF >services >EjemploServicio >META-INF >services.xml (descriptor del servicio) >service.wsdl >parte1.xsd >parte2.xsd En este ejemplo, el fichero service.wsdl tiene sentencias: <xs:import namespace="..." schemalocation="parte1.xsd" /> <xs:import namespace="..." schemalocation="parte2.xsd" /> En este caso el wsdl se obtendría con la URL: [^] y cada una de los ficheros xsd con la URL: [^] [^] En el caso de tener un WSDL predeterminado para el servicio, además será necesario editar el fichero weblogic.xml y añadir la siguiente línea (marcada en amarillo): Fichero web/src/main/webapp/web-inf/weblogic.xml <wls:container-descriptor> <wls:prefer-web-inf-classes>true</wls:prefer-web-inf-classes> <wls:show-archived-real-path-enabled>true</wls:show-archived-real-path-enabled> </wls:container-descriptor> Paso 9: Creación del Cliente Una vez creado el servicio web ahora vamos a crear el cliente que se distribuirá con una librería para que las aplicaciones que tengan que integrarse con nuestra aplicación lo hagan utilizando esta librería. Los clientes de servicio web ATLAS se caracterizan por que no se generan a partir de un descriptor WSDL del 19 de 82

20 servicio sino que se parte de la clase de la interfaz del servicio y de las clases que representen a los parámetros del mismo. La invocación a los métodos del servicio web va a ser dinámica. Para facilitar esta invocación dinámica dentro del framework Atlas existen dos clases base para la creación de clientes de servicio web. Estas son: AtlasUnsecuredWSClient: esta clase debe utilizarse cuando no hay seguridad definida en la llamada a servicio web. Esta clase también debe utilizarse cuando se usa HTTPS en la comunicación ya que esta seguridad no se aplica al mensaje sino al transporte de este y queda fuera del alcance del framework de webservices. AtlasSecuredWSClient: esta clase debe usarse cuando es necesario aplicar una política de seguridad a la comunicación con el servicio web, y se explicará en el apartado correspondiente a la seguridad. Por lo tanto para un servicio web sin seguridad es necesario crear una clase en nuestra librería que implemente el interfaz del servicio web creado en el apartado anterior, y que extienda la clase AtlasUnsecuredWSClient. 20 de 82

21 package prueba.client; ClienteMiPrimerService.java import java.util.properties; import prueba.services.miprimerservice; import atlas.clientews.client.atlasunsecuredwsclient; import atlas.core.exceptions.serviceexception; public class ClienteMiPrimerService extends AtlasUnsecuredWSClient implements MiPrimerService{ /** Constructor que recibe como parámetro el endpoint del servicio Se le pasará en el fichero de contexto de Spring y lo cogerá del fichero enviroment.properties **/ public ClienteMiPrimerService(String endpoint) { super(endpoint, " } /** Propiedades */ private Properties public String getfechastring() throws ServiceException { return invoke("getfechastring", properties, String.class); } /** * Establece el valor de las propiedades properties las propiedades */ public void setproperties(properties properties) { this.properties = properties; } } La clase cliente a implementar debe cumplir las siguientes condiciones: 1) Se crea en el paquete xxxx.client dentro del módulo lib. 2) Se llama según la siguiente nomenclatura ClienteyyyyService.java. Ejpl: ClienteMiPrimerService. 3) Extiende la clase base a utilizar, en este caso AtlasUnsecuredWSClient. 4) Implementa la interfaz del servicio para proporcionar una implementación de todos los métodos de este. 5) El constructor toma como parámetro la URL del servicio. Dejar el namespace del servicio igual que se ha generado en los ejemplos del arquetipo, no modificar este valor. 6) Los métodos implementados de la interfaz de servicio llevan la para que el compilador pueda detectar posibles errores en el nombre de estos. 7) Las llamadas al servicio web se realizan a través del método invoke con los parámetros definidos en su javadoc: 21 de 82

22 Definición del método invoke /** * Realiza la invocación del servicio web <E> parametrización del tipo de objeto a devolver. methodname método de webservice a llamar serviceproperties propiedades de llamada del servicio web returntype tipo a retornar por la llamada parameters parametros de llamada respuesta del webservice ServiceException si hubo algún tipo de problema en la llamada */ protected <E> E invoke(string methodname, Properties serviceproperties, Class<E> returntype, Object... parameters) throws ServiceException { En caso de que el método de llamada acepte más de un parámetro de entrada, se deberá realizar la llamada al método invoke de la siguiente forma: Llamada al método invoke con varios public DatosSalida alterar(datosentrada entrada1, String entrada2) throws ServiceException { return invoke("alterar", properties, DatosSalida.class, entrada1, entrada2); } 8) Las propiedades del servicio se almacenan en una variable interna de la clase ya que es necesario pasarlas en cada llamada a la clase base AtlasUnsecuredWSClient. Es necesario también que esté implementado el método setproperties tal cuál viene en el ejemplo. En casos generales, no será necesario especificar ningún parámetro en las propiedades del servicio, siempre que no se envíen ficheros adjuntos (en caso afirmativo debe establecerse enablemtom a true ) y no se haga uso de otros módulos de Axis2 como por ejemplo addressing. A continuación se muestran las propiedades que se pueden utilizar: Parámetro Descripcion Valor por Defecto repositoryroot Raíz del repositorio de módulos de Axis2 "./META-INF/" enablemtom Habilitar optimización de envío de binarios. false Paso 10: Configuración del Cliente Para que el cliente pueda conocer la url del servicio web es necesario incluir en el fichero de configuración enviroment.properties el endpoint de dicho servicio. Las propiedades de este tipo tendran la siguiente nomenclatura: <nombredelservicio>.endpoint en el fichero enviroment.properties. 22 de 82

23 A continuación se muestra un ejemplo: enviroment.properties miprimerservice.endpoint= Además es necesario definir en el fichero de contexto de Spring del modulo lib (applicationcontext-xxxx_ws_lib.xml) el bean del cliente con el parámetro del endpoint que recogerá del fichero de configuración. A continuación se muestra un ejemplo: applicationcontext-xxxx_ws_lib.xml <beans> <bean id="miprimerservice" class="prueba123.client.clientemiprimerservice"> <constructor-arg value="${miprimerservice.endpoint}" /> </bean> </beans> Paso 11: Test Unitarios del Cliente Los tests unitarios que habrán de realizarse dentro de la librería deben comprobar la correcta comunicación con el webservice en cada uno de los métodos de llamada de que disponga. Para la creación de dichos tests se utilizará, como es norma en el framework ATLAS, la librería java junit 4. Para facilitar la creación del contexto de Spring las clases de test heredarán de la clase AbstractJUnit4SpringContextTests. NOTA Con el arquetipo recien generado todos los métodos de los test de JUnit incluyen la y no se ejecutarán en el proceso de construcción de la librería cliente (serán ignorados). Una vez creada e instalada la librería en el repositorio local (mvn clean install), se podrá eliminar la de cualquier método que se desee testear, y ejecutar el test con el comando mvn test (el módulo de servidor web debe estar arrancado también para que el test sea correcto). El código de prueba de una clase de test de ejemplo es el siguiente (definida en lib/src/test/java): 23 de 82

24 package prueba.client; import static org.junit.assert.*; lib/src/test/java/clientemiprimerservicetest.java import org.junit.test; import org.springframework.beans.factory.annotation.autowired; import org.springframework.beans.factory.annotation.qualifier; import org.springframework.test.context.contextconfiguration; import org.springframework.test.context.junit4.abstractjunit4springcontexttests; import = {"classpath:/conf/applicationcontext-test.xml"}) public class ClienteMiPrimerServiceTest extends AbstractJUnit4SpringContextTests { } // Autowired solo permitido en clases de private MiPrimerService service; public void setservice(miprimerservice service) { this.service = service; public void testgetfechastring() { assertnotnull("el servicio es nulo", service); String salida = null; try { salida = service.getfechastring(); } catch (Exception e){ e.printstacktrace(); fail("error en la llamada"); } assertnotnull(salida); System.out.println("** Salida: " + salida); } Se ha marcado en color amarillo la llamada al invocador dinámico creado anteriormente. En este ejemplo, se ha creado un test unitario que recoge la instancia del invocador concreto de Spring. A través de Spring también se está pasando una URL concreta de servicio para testear. Además de implementar el test, para probar el cliente es necesario configurar el endpoint en el contexto de Spring de los tests, modificando el fichero lib/src/test/resources//environment.properties, según se muestra en el ejemplo incluido en el arquetipo: 24 de 82

25 lib/src/test/resources/environment.properties # Datos de WS miprimerservice.endpoint= Este test se puede ejecutar desde el propio Eclipse como cualquier test unitario, pero hay que tener en cuenta que hay que tener levantado el servicio web. 25 de 82

26 3.2. IMPLEMENTACION DE SEGURIDAD CON WS SECURITY En los servicios web en los que haya que implementar seguridad utilizaremos WS Security. En este apartado se muestra cómo configurar un servicio web para incluir seguridad de WS-Security que consiste en que la seguridad va dentro del mensaje SOAP. Dentro de este modelo de seguridad existen las siguientes posibilidades: - Firmado digital del mensaje SOAP Garantiza la procedencia del mensaje, integridad de los datos y no repudio. - Cifrado del mensaje SOAP Garantiza la confidencialidad del mensaje. Antes de implementar la seguridad en un servicio web lo primero es crear el servicio web y probar su correcto funcionamiento sin incluir seguridad tal y como se indica en los apartados anteriores. Para cada servicio web al que se quiera incluir seguridad, ha de asociale una política de seguridad. Dentro del arquetipo en el módulo lib podemos encontrarnos dos politicas (lib/src/main/resources/meta-inf): politicawssfirmado.xml politicawssfirmadocifrado.xml En estos ficheros se definen las restricciones de seguridad a aplicar siguiendo los estándares de WS Security- Policy. Alguna de las características de estas politicas son las siguientes: En el intercambio de información se utilizarán claves asimétricas, pares clave pública (certificado) + clave privada. El certificado a usar deberá ser del tipo X509v3 y además deberá contar con una referencia de tipo thumbprint (tags RequireThumbprintReference y WssX509V3Token10). La cabecera de seguridad del mensaje deberá contener una fecha de creación de este (tag IncludeTimestamp). Se firmará digitalmente el cuerpo del mensaje (tag SignedParts/Body). Se cifrará el contenido del cuerpo del mensaje (tag EncryptedParts/Body). El mensaje firmado contendrá una copia del certificado público del firmante (tag X509Token IncludeToken= /Always ). Para las operaciones de firma, cifrado y validación de firma y cifrado se utilizará la plataforma ASF. Suponiendo que ya tenemos un Servicio creado y funcionando pasamos a incorporale WSSecurity Paso 1: Alta de la aplicación en la plataforma ASF 26 de 82

27 Antes de configurar la aplicación, debemos darla de alta en el entorno ASF y configurarla. Para el entorno de desarrollo, esto se debe realizar mediante una consulta a la Unidad de Arquitectura de Aplicaciones en la categoría de ASF a través de la web de soporte. Para el resto de entornos (validación, producción, etc.) se incluye dicha información en la ficha de entrega. La información que se ha de incluir en la solicitud es la siguiente: - operación: WSS - seguridad servicio web - aplicación: Nombre de aplicación que se desea dar de alta en ASF - certificado de servidor a utilizar: Indicar qué certificado de servidor se desea utilizar, o si se quiere utilizar uno genérico. A continuación se muestra un ejemplo de solicitud: Ejemplo de solicitud a la Unidad de Arquitectura de Aplicaciones Operacion: WSS - seguridad servicio web Aplicacion: EJPL_WS_SERVIDOR Certificado de servidor: certificado genérico Como respuesta a la solicitud, la Unidad de Arquitectura de Aplicaciones contestará con un mensaje como este: Ejemplo de respuesta de la Unidad de Arquitectura de Aplicaciones Se han realizado actuaciones en la plataforma ASF 5.0 para definir servidor y cliente del alta solicitada para el módulo "EJPL_WS_SERVIDOR". Los datos para configurar los desarrollos son los siguientes: - SERVIDOR > ID de aplicación ASF: EJPL_WS_SERVIDOR > alias "localkey": servidor_ws - CLIENTE > ID de aplicación ASF: EJPL_WS_CLIENTE > alias "localkey": cliente_ws > alias "remotekey": servidor_ws_cert En la respuesta se mostrarán los datos de configuración necesarios para el servicio web (apartado SERVIDOR) y para las pruebas unitarias del cliente en el módulo lib (apartado CLIENTE) Paso 2: Configuración del Servicio Una vez que se ha dado de alta en ASF y con los de SERVIDOR tenemos que incluir en el fichero src/main/resources/environment.properties lo siguiente: 27 de 82

28 # Ids de aplicacion app.id.asf=ejpl_ws_servidor # Parametros de WS miprimerservice.localkey=servidor_ws src/main/resources/environment.properties El valor de la variable app.id.asf es el identificador de la aplicación en la plataforma ASF (debe ser igual que la aplicación dada de alta en ASF). Este dato se corresponde con el ID de aplicación en el apartado SERVIDOR de la respuesta de la Unidad de Arquitectura de Aplicaciones. Es necesario crear una variable con la siguiente nomenclatura <nombreservicio>.localkey con el valor del alias localkey proporcionado (alias del certificado con el que se va a firmar la respuesta). Ejpl: miprimerservice.localkey. ATENCION Recordar que cada vez que se modifica el valor de una variable en el fichero src/main/resources/environment.properties es necesario también modificar todos los ficheros war/(nombreentorno)/environment.properties Paso 3: Actualización de configuración en el fichero services.xml Para asociar una política de seguridad para un servicio web determinado, hay que incluir una serie de líneas dentro del tag <service> asociado al servicio en el fichero services.xml. En un fichero services.xml podrá haber servicios seguros y servicios no seguros conviviendo sin problemas. Como hemos dicho hay dos políticas por lo tanto dos configuraciones distintas a incluir dependiendo de cual se elija: 28 de 82

29 Servicio con politicawssfirmado <service name="miserviciowebwssecurity1"> <parameter name="serviceobjectsupplier" locked="false"> org.apache.axis2.extensions.spring.receivers.springservletcontextobjectsupplier </parameter> <parameter name="springbeanname" locked="false">miprimerservice</parameter> <parameter name="serviceclass" locked="false"> prueba123.services.miprimerservice </parameter> <messagereceivers> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcmessagereceiver" /> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcinonlymessagereceiver" /> </messagereceivers> <module ref="atlasfrm-clientews-seguridad" /> <wsp:policy wsu:id="politicawssfirmado" xmlns:wsu=" xmlns:wsp=" <wsp:exactlyone> <wsp:all> <sp:asymmetricbinding xmlns:sp=" <wsp:policy> <sp:initiatortoken> <wsp:policy> <sp:x509token sp:includetoken=" <wsp:policy> <sp:requirethumbprintreference /> <sp:wssx509v3token10 /> </wsp:policy> </sp:x509token> </wsp:policy> </sp:initiatortoken> <sp:recipienttoken> <wsp:policy> <sp:x509token sp:includetoken=" <wsp:policy> <sp:requirethumbprintreference /> <sp:wssx509v3token10 /> </wsp:policy> </sp:x509token> </wsp:policy> </sp:recipienttoken> <sp:algorithmsuite> <wsp:policy> <sp:tripledesrsa15 /> </wsp:policy> </sp:algorithmsuite> <sp:layout> <wsp:policy> <sp:strict /> </wsp:policy> </sp:layout> <sp:includetimestamp /> <sp:onlysignentireheadersandbody /> </wsp:policy> </sp:asymmetricbinding> 29 de 82

30 <sp:signedparts xmlns:sp=" <sp:body/> </sp:signedparts> <atlas:asfconfig xmlns:atlas=" <atlas:invokingapp>${app.id.asf}</atlas:invokingapp> <atlas:operationmode>server</atlas:operationmode> <atlas:localkey>${miprimerservice.localkey}</atlas:localkey> <sp:wss10 xmlns:sp=" <wsp:policy> <sp:mustsupportrefkeyidentifier/> <sp:mustsupportrefissuerserial/> </wsp:policy> </sp:wss10> <atlas:wsutslife>300000</atlas:wsutslife> </atlas:asfconfig> </wsp:all> </wsp:exactlyone> </wsp:policy> </service> Servicio con politicawssfirmadocifrado 30 de 82

31 <service name="miserviciowebwssecurity1"> <parameter name="serviceobjectsupplier" locked="false"> org.apache.axis2.extensions.spring.receivers.springservletcontextobjectsupplier </parameter> <parameter name="springbeanname" locked="false">miprimerservice</parameter> <parameter name="serviceclass" locked="false"> prueba123.services.miprimerservice </parameter> <messagereceivers> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcmessagereceiver" /> <messagereceiver mep=" class="org.apache.axis2.rpc.receivers.rpcinonlymessagereceiver" /> </messagereceivers> <module ref="atlasfrm-clientews-seguridad" /> <wsp:policy wsu:id="politicawssfirmadocifrado" xmlns:wsu=" xmlns:wsp=" <wsp:exactlyone> <wsp:all> <sp:asymmetricbinding xmlns:sp=" <wsp:policy> <sp:initiatortoken> <wsp:policy> <sp:x509token sp:includetoken=" <wsp:policy> <sp:requirethumbprintreference /> <sp:wssx509v3token10 /> </wsp:policy> </sp:x509token> </wsp:policy> </sp:initiatortoken> <sp:recipienttoken> <wsp:policy> <sp:x509token sp:includetoken=" <wsp:policy> <sp:requirethumbprintreference /> <sp:wssx509v3token10 /> </wsp:policy> </sp:x509token> </wsp:policy> </sp:recipienttoken> <sp:algorithmsuite> <wsp:policy> <sp:tripledesrsa15 /> </wsp:policy> </sp:algorithmsuite> <sp:layout> <wsp:policy> <sp:strict /> </wsp:policy> </sp:layout> <sp:includetimestamp /> <sp:onlysignentireheadersandbody /> </wsp:policy> </sp:asymmetricbinding> 31 de 82

32 <sp:signedparts xmlns:sp=" <sp:body/> </sp:signedparts> <sp:encryptedparts xmlns:sp=" <sp:body/> </sp:encryptedparts> <atlas:asfconfig xmlns:atlas=" <atlas:invokingapp>${app.id.asf}</atlas:invokingapp> <atlas:operationmode>server</atlas:operationmode> <atlas:localkey>${miprimerservice.localkey}</atlas:localkey> <sp:wss10 xmlns:sp=" <wsp:policy> <sp:mustsupportrefkeyidentifier/> <sp:mustsupportrefissuerserial/> </wsp:policy> </sp:wss10> <atlas:wsutslife>300000</atlas:wsutslife> </atlas:asfconfig> </wsp:all> </wsp:exactlyone> </wsp:policy> </service> La variable incluida en amarillo es la única que hay que configurar. El resto es igual para todos los servicios que necesiten esta politica de firma y cifrado. Se ha de poner el nombre de la variable incluida en el fichero enviroment.properties. Aunque en el listado anterior se han incluido las variables de configuración básicas, si se necesita una configuración avanzada puede utilizarse cualquiera de las variables definidas en la siguiente tabla: Propiedad Descripción Valor invokingapp operationmode Nombre de la aplicación en ASF 5. Parámetro obligatorio. Modo de operación del módulo de seguridad. Solo se admiten dos valores: client o server. Parámetro obligatorio. Ej: EJPL_WS_SERVIDOR Ej: server localkey Nombre del certificado propio a usar en la comunicación segura. Parámetro obligatorio. Este certificado se utilizará para las operaciones de firmado del mensaje de petición y desencriptado del mensaje de respuesta. Ej: servidor_ws wsutslife Tiempo de validez del mensaje en milisegundos. Ej: (5 minutos) signatureoperation Nombre de la operación en ASF para el firmado digital del mensaje. Parámetro no obligatorio. Será comunicado en la respuesta a la solicitud en ASF si es necesario configurarlo Por defecto: FIRMA_SIMPLE 32 de 82

33 encryptionoperation decryptionoperation validationoperation applysecurityonfault Nombre de la operación en ASF para el cifrado del mensaje. Parámetro no obligatorio. Será comunicado en la respuesta a la solicitud en ASF si es necesario configurarlo Nombre de la operación en ASF para el descifrado del mensaje. Parámetro no obligatorio. Será comunicado en la respuesta a la solicitud en ASF si es necesario configurarlo Nombre de la operación en ASF para la validación de la firma de un mensaje. Parámetro no obligatorio. Será comunicado en la respuesta a la solicitud en ASF si es necesario configurarlo Por defecto se aplica la seguridad configurada a todos los mensajes del servicio. En algunos casos (red SARA) es necesario no aplicar seguridad a los mensajes que generan un <soap:fault>. Si se desea este comportamiento se debe configurar un valor false en este parámetro Por defecto: CIFRADO Por defecto: DESCIFRADO Por defecto: VERIFICACION Por defecto: true Paso 4: Modificar Cliente Una vez que hemos configurado la seguridad en el servicio web, tenemos también que modificar la librería cliente que viene en el arquetipo para que acceda al servicio web de forma segura. Para ello, la clase en la librería cliente que implementaba la interfaz del servicio y que extendía de AtlasUnsecuredWSClient debe modificarse para extender de AtlasSecuredWSClient. ClienteMiPrimerService.java 33 de 82

34 package prueba123.client; import java.util.properties; import prueba123.services.miprimerservice; import atlas.clientews.client.atlassecuredwsclient; import atlas.core.exceptions.serviceexception; public class ClienteMiPrimerServiceWSS1 extends AtlasSecuredWSClient implements MiPrimerService{ public ClienteMiPrimerServiceWSS1(String endpoint) { super(endpoint, " } /** Propiedades */ private Properties public String getfechastring() throws ServiceException { } return invoke("getfechastring", properties, String.class); } /** * Establece el valor de las propiedades properties las propiedades */ public void setproperties(properties properties) { this.properties = properties; } Paso 5: Configuración del Cliente Además es necesario modificar en el fichero de contexto de Spring del modulo lib (applicationcontextxxxx_ws_lib.xml) el bean del cliente para añadirles las propiedades relacionadas con la seguridad tal y como se puede ver en este ejemplo: applicationcontext-xxxx_ws_lib.xml <beans> <bean id="miprimerservice" class="prueba123.client.clientemiprimerservice"> <constructor-arg value="${miprimerservice.endpoint}" /> <property name="properties"> <props> <prop key="policypath">meta-inf/politicawssfirmado.xml</prop> <prop key="invokingapp">${app.id.asf}</prop> <prop key="operationmode">client</prop> <prop key="localkey">${miprimerservice.localkey}</prop> <prop key="remotekey">${miprimerservice.remotekey}</prop> <prop key="wsutslife">300000</prop> </props> </property> </bean> </beans> 34 de 82

35 El bloque marcado en amarillo tendrá que añadirse tal cual pero modificando los nombre de las variables: En el campo policypath se ha de indicar el fichero de politica de firma: politicawssfirmado.xml politicawssfirmadocifrado.xml Sustituir las siguientes variables por las correspondientes de nuestro servicio. - miservicioweb.localkey - miservicioweb.remotekey. El siguiente paso es definir las propiedades de ASF indicadas para el CLIENTE en el fichero de configuración del módulo lib para poder hacer las pruebas con los Test Unitarios. Fichero lib/src/test/resources/environment.properties # Ids de aplicacion app.id.asf=ejpl_ws_cliente # Datos de WS miprimerservice.endpoint= miprimerservice.localkey=cliente_ws miprimerservice.remotekey=servidor_ws_cert En amarillo se han marcado las nuevas variables que se han de incluir. A continuación se describen cada una de las variables: Parámetro Descripcion Valor por defecto app.id.asf Nombre de la aplicación en ASF Ej.: EJPL_WS_CLIENTE [nombreservicio].endpoint URL del servicio Ej.: <nombreservicio> [nombreservicio].localkey Alias de la clave del cliente usada para firmar el mensaje. Se corresponde con el alias del certificado dado de alta en asf para la operación de firma. Ej.: cliente_ws 35 de 82

36 [nombreservicio].remotekey Alias del certificado del servidor utilizado para cifrar el mensaje. Se corresponde con el alias del certificado dado de alta en asf para la operación de firma. Ej.: servidor_ws_cert Acceso al certificado de cliente Uno de los requisitos de seguridad que puede tener un servicio web es la obtención del certificado público del cliente con el que se ha realiza la firma digital/cifrado del mensaje. La seguridad aplicada al mensaje solo se encarga de verificar que este no ha sido modificado y que el origen es confiable. Sin embargo, el servicio web puede tener otros requisitos de seguridad respecto del cliente, como por ejemplo la comprobación y registro del cliente conectado, comprobación de permisos para la ejecución de operaciones, etc. Dentro del código del servicio web es sencillo recoger el certificado digital cliente de firma, tal y como se muestra a continuación: Obtención del certificado de cliente del mensaje public class EjemploServicioImpl implements EjemploServicio {... private void getclientcertificate() { try { String cert = AtlasRampartUtils.getSigningCert(); log.info("certificado de firma: \n\n" + cert + "\n\n"); } catch (AtlasSecurityException e) { log.error("error al capturar certificado de firma.", e); } } } En el ejemplo anterior se ha marcado en amarillo la sentencia con la que se recoge el certificado de firma del mensaje del cliente (el resto del código es solo un ejemplo de implementación). Hay que tener las siguientes consideraciones: Si el mensaje no contiene seguridad, se devolverá un valor null. Si se produce algún problema en la exploración del mensaje entrante para la captura del certificado, se devolverá una excepción AtlasSecurityException. Si se desea obtener los datos de este certificado, será necesario realizar las llamadas correspondientes al servicio de ASF de ATLAS (CryptService.getDatosCertificado(String)). Para más información, consultar el documento ATLAS_MUS_Servicio_Certificados.doc. 36 de 82

37 4. DESARROLLO DE UN CLIENTE DE SERVICIO WEB En este documento se diferencian dos formas de acceder a un servicio web. Si queremos acceder a un servicio web creado con ATLAS, es mucho más fácil ya que al crear el servicio web se generó una librería preparada para usarla desde la parte cliente. Si no se trata de un servicio web creado con ATLAS, entonces se tendrá que partir del fichero WSDL que describe el servicio web, y generar las clases a partir de éste CLIENTE DE UN SERVICIO ATLAS Para usar un servicio web creado con ATLAS debemos disponer de la librería que se generó junto con el servicio web. A continuación se describen los pasos para incorporar dicha librería en nuestro proyecto y definir las propiedades de conexión al servicio web Paso 1: Inclusión de la dependencia Para usar la librería generada en nuestro proyecto, será necesario realizar la inclusión de esta dependencia en el fichero pom.xml, según se muestra a continuación: ejemplo de inclusión de dependencia en pom.xml de proyecto <dependencies> <dependency> <groupid>xxxx</groupid> <artifactid>xxxx_ws_lib</artifactid> <version>y.y.y</version> </dependency> </dependencies> Los valores de las distintas variables nos los deben proporcionar los responsables de dicha librería Paso 2: Configuración del contexto de Spring Para usar la librería correctamente debemos modificar el fichero de configuración de Spring de nuestro proyecto denominado applicationcontext-services.xml, incluyendo la línea que importa el fichero de contexto de la librería (modificar xxxx_ws_lib por el nombre del fichero de contexto que aparece dentro de la librería): applicationcontext-services.xml de proyecto <beans>   <import resource="classpath:/conf/applicationcontext-xxxx_ws_lib.xml" /> 37 de 82

38 Paso 3: Configuración del endpoint en environment.properties El último paso para configurar la URL de conexión al servicio web es definir una nueva variable en el fichero src/main/resources/environment.properties de nuestra aplicación, según se muestra a continuación: src/main/resources/environment.properties de proyecto # Definición del endpoint del servicio MiServicioWeb miprimerservice.endpoint= ATENCION Recordar que cada vez que se modifica el valor de una variable en el fichero src/main/resources/environment.properties es necesario también modificar todos los ficheros war/(nombreentorno)/environment.properties para incluir la nueva variable Paso 4: Inclusión de Seguridad: WS Security Si se trata de invocar a un servicio web seguro generado con ATLAS, debemos además activar la seguridad en nuestro cliente. Para ello, lo que hay que hacer es configurar el módulo de seguridad, modificando el fichero src/main/resources/environment.properties, incluyendo las líneas marcadas en amarillo en el siguiente ejemplo: src/main/resources/environment.properties de proyecto # Ids de aplicacion app.id.asf=ejpl_ws_cliente # Definición del endpoint del servicio MiServicioWeb miservicioweb.endpoint= miservicioweb.localkey=cliente_ws miservicioweb.remotekey=servidor_ws_cert Los valores de las variables son los siguientes: Parámetro Descripcion Valor por defecto 38 de 82

39 app.id.asf Nombre de la aplicación en ASF Ej.: EJPL_WS_CLIENTE [nombreservicio].endpoint URL del servicio Ej.: s/miservicioweb [nombreservicio].localkey [nombreservicio].remotekey Alias de la clave del cliente usada para firmar el mensaje. Se corresponde con el alias del certificado dado de alta en asf para la operación de firma. Alias del certificado del servidor utilizado para cifrar el mensaje. Se corresponde con el alias del certificado dado de alta en asf para la operación de firma. Ej.: cliente_ws Ej.: servidor_ws_cert 4.2. CLIENTE DE UN SERVICIO NO ATLAS Los clientes de servicio web NO ATLAS se caracterizan por ser de código generado a partir de un descriptor WSDL. A diferencia del cliente de servicio web ATLAS, este cliente debe generarse en cada proyecto en que se quiera establecer comunicación con un servicio web. Para generar un cliente a partir de un fichero WSDL será necesario hacer uso del módulo maven de ATLAS llamado altasfrm-clientews-wsdl2code-maven-plugin Paso 1: Incluir fichero wsdl en el proyecto El fichero wsdl que nos hayan proporcionado hay que incluirlo en el proyecto en la carpeta src/main/resources/wsdl Paso 2: Inclusión de la dependencia y configuración del plugin Añadir en la siguiente dependencia en el fichero pom.xml del proyecto donde se vaya a generar el cliente compilado: pom.xml 39 de 82

40 <dependency> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-clientews-lib</artifactid> <version>${atlasfrm-clientews-lib.version}</version> <scope>provided</scope> </dependency> Dentro de la sección de plugins del fichero pom.xml de nuestro proyecto es necesario incluir el plugin de Maven atlasfrm-clientews-wsdl2code-maven-plugin. Este plugin generará tanto las clases de cliente del webservice como las clases de tests para las pruebas contra dicho servicio. A continuación se muestra un ejemplo de configuración del plugin: pom.xml  <plugin> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-clientews-wsdl2code-maven-plugin</artifactid> <version>${atlasfrm-clientews-wsdl2code-plugin.version}</version> <configuration> <packagename>xxxx.ws.client</packagename> <servicenameaspackage>true</servicenameaspackage> <overwrite>false</overwrite> </configuration> <executions> <execution> <id>xxxxservice</id> <configuration> <wsdlfile>src/main/resources/wsdl/xxxxservice.wsdl</wsdlfile> </configuration> <goals> <goal>wsdl2code</goal> </goals> </execution> </executions> </plugin> ATENCION Si se ha partido de uno de los arquetipos de Atlas, el plugin se encuentra comentado en el fichero pom.xml del arquetipo, sólo será necesario descomentarlo. Según la configuración anterior a partir del fichero xxxxservice.wsdl se generarán las clases cliente del servicio xxxxservice en el directorio src/main/java en el paquete xxxx.ws.client.xxxxservice (suponiendo que xxxxservice sea el nombre del servicio). También se generará un fichero applicationcontext-xxxxservice.xml en el directorio src/main/resources, para que el cliente esté dado de alta en el contexto de Spring. Puede ser necesario incluir manualmente en los configlocations del fichero web.xml este nuevo archivo de definiciones. 40 de 82

41 Además se generarán los test unitarios del servicio en el directorio src/test/java, en el mismo paquete en que se han generado las clases del cliente. El test unitario contendrá el fichero de definiciones de Spring creado para el servicio. En caso de tener que generar varios clientes de servicio web, se deberán generarse tantos tags <execution> como clientes deban generarse, cada uno con su configuración. Los parámetros que se pueden configurar en este plugin son, además de los propios del plugin wsdl2codemaven-plugin (y que podemos encontrar descrita en la siguiente url: los incluidos en la siguiente tabla: Propiedad Descripción Valor wsdlfile Esta etiqueta indica la ruta dentro del proyecto al fichero de descripción del servicio web del que se va a generar el cliente. Ej: src/main/resources/wsdl/xxxx_ws. wsdl Por defecto: src/main/resources/rservice.wsdl packagename Nombre del paquete base donde se generarán las clases java del cliente de servicio web (en src/main/java) Ej: xxxx.ws.client servicenameaspackage overwrite skipgeneratioin outputdirectory resourceoutputdirectory Si es true se añadirá el nombre del servicio como paquete al final de packagename. El nombre del servicio se modificará para cumplir la normativa de nomenclatura de paquetes. Si es false se comprueba si ya existe el fichero y en caso afirmativo, no se generará de nuevo. Se recomienda siempre este valor para que los ficheros se generen solo una vez y no se pierdan modificaciones manuales en las clases generadas. Si es true el plugin no intentará generar ningún cliente. Se recomienda usar este parámetro cuando se modifiquen los nombres de los ficheros generados, de lo contrario se generarán ficheros nuevos con los nombres originales. Directorio de fuentes donde se generarán las clases del cliente de servicio web Directorio de recursos donde se generarán los ficheros de spring del cliente. Por defecto: true Por defecto: false Por defecto: false Por defecto: src/main/java Por defecto: src/main/resources/conf 41 de 82

42 testoutputdirectory testresourceoutputdirec tory Directorio de fuentes donde se generarán los tests unitarios Directorio de recursos de test donde se generarán los ficheros de configuración de Spring necesarios (si los hubiere) Por defecto: src/test/java Por defecto: src/test/resources/conf syncmode Modo de conexión al webservice Por defecto: sync (síncrono) generatetestcase Indica si generar o no una clase de test para el cliente de webservice. Por defecto: true unpackclasses Genera las clases en distintos ficheros Por defecto: true generateserversideinterf ace unwrap namespacetopackages Genera el intefaz java del servicio web Desempaqueta los parámetros de entrada y salida de los métodos del webservice Lista de Namespaces del fichero WSDL relacionandolos con nombres de paquete para generar en estas ubicaciones los datos asociados a cada Namespace. Por defecto: true Por defecto: true Por defecto: todas las clases se generan en el mismo paquete del cliente del servicio web. Una vez que este plugin está configurado se puede pasar a la generación de las clases del cliente del servicio web Paso 2: Generación de la clases del Cliente La generación a partir del plugin atlas-wsdl2code-maven-plugin se basa en el documento WSDL para generar el cliente. A continuación de muestra un ejemplo de generación en el módulo lib para el servicio MiServicioWeb. La configuración del plugin es: pom.xml <plugin> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-clientews-wsdl2code-maven-plugin</artifactid> <version>${atlasfrm-clientews-wsdl2code-plugin.version}</version> <configuration> <packagename>prueba123.ws.client</packagename> <servicenameaspackage>true</servicenameaspackage> <overwrite>false</overwrite> </configuration> <executions> <execution> <id>miprimerservice</id> <configuration> <wsdlfile>src/main/resources/wsdl/miprimerservice.wsdl</wsdlfile> </configuration> <goals> <goal>wsdl2code</goal> </goals> </execution> </executions> </plugin> 42 de 82

43 Para que se generen las clases del cliente simplemente hay que compilar el proyecto. Para que las clases generadas aparezcan en Eclipse es necesario refrescar el proyecto. A continuación se muestra un ejemplo de los ficheros generados para el servicio MiServicioWeb: Clases del cliente generadas en src/main/java: Paquete base: xxxx.ws.client Nombre del Servicio: MiServicioWeb Nombre de servicio como paquete: Si Interfaz del servicio: MiServicioWeb.java Implementación del cliente: MiServicioWebStub.java Mapeo de datos:paquete.domain. Configuración de Spring generada en src/main/resources: Configuración de Spring: applicationcontext-miservicioweb.xml Clases de test generadas en src/test/java: Test unitario: MiServicioWebTest.java Una vez generadas las clases del cliente, el fichero de Spring y el test unitario, habrá que editar este último para proporcionar datos para las llamadas que reciban parámetros. Si no se modifica el fichero de test para añadir estos datos, el test unitario fallará. En cada método de test en que sea necesario aportar datos para hacer la llamada, se generará un comentario como el siguiente para indicar el sitio donde introducir estos: TestCase.java // TODO : Rellenar aquí los valores de xxxxxxxxxxxxxx // El test unitario no ejecutara correctamente hasta que no se // rellenen valores correctos Es importante revisar los ficheros de contexto de String incluidos en el test a ver si son los correspondientes a los de la aplicación en la que se está generando el cliente para ver si son los correctos y en su caso modificarlos para 43 de 82

44 que funcione correctamente Paso 3: Configuración y uso del Cliente En este apartado se demostrará el uso del cliente generado. Se utilizará como ejemplo el cliente del servicio MiServicioWeb generado en apartados anteriores. La primera modificación que habrá que hacer al código generado será parametrizar el endpoint por defecto en el fichero environment.properties (marcado en amarillo). Para ello habrá de consultarse el fichero de Spring generado para el servicio. En los comentarios de la definición de este servicio se indicará que variable ha de darse de alta: applicationcontext-miservicioweb.xml  <bean id="miservicioweb" class="atlas.clientews.client.clientfactory"...> <constructor-arg value="atlas.ws...miserviciowebstub" /> <constructor-arg type="..." value="${miservicioweb.endpoint}" /> </bean> environment.properties del módulo donde se usará el cliente # Endpoints de webservice miservicioweb.endpoint= ATENCIÓN Es OBLIGATORIO parametrizar el endpoint de servicio en los ficheros environment.properties, independientemente del valor que figure en el descriptor WSDL a partir del que se ha creado el cliente. Los parámetros endpoint han de crearse en TODOS los ficheros environment.properties del proyecto donde se usará la librería cliente, aunque no se sepan las URLs en los distintos entornos. A continuación se ha de incluir la definición del invocador en el contexto de Spring en el proyecto donde se hará uso de la librería cliente. La forma recomendada de cargar el fichero de Spring es mediante una sentencia include en el fichero de servicios. applicationcontext-services.xml 44 de 82

45 <beans> <import resource="applicationcontext-miservicioweb.xml"/> </beans>    En este mismo fichero applicationcontext-services.xml están las definiciones de los servicios del proyecto. Debe añadirse la dependencia como se haría con cualquier otro servicio del proyecto. Una vez añadida, podrán implementarse métodos de uso en esta que utilicen el invocador creado. applicationcontext-services.xml <beans> <import resource="applicationcontext-miservicioweb.xml"/>    <bean id="miservicio" class="atlasfrm...services.miservicioimpl" p:miservicioweb-ref="miservicioweb" /> </beans> public class MiServicioImpl implements MiServicio { private MiServicioWeb miservicioweb; public void setmiservicioweb(miservicioweb miservicioweb) { this.miserviciweb = miservicioweb; } /** * Llamada al WS de Ejemplo String */ public String getfechastring() throws java.lang.exception { } String result = miservicioweb.getfechastring(); // Imprimir el resultado si se necesita comprobacion visual (solo en test) System.out.println("Resultado de la llamada: " + result); assertnotnull(result); return null; 45 de 82

46 ATENCION Para simplificar el uso de clientes compilados, estos pueden ser inyectados en un servicio si requieren de lógicas de proceso y manipulación de los objetos del cliente compilado (objeto DatosEntrada en el ejemplo anterior) Paso 4 (Opcional): Llamara a un Servicio Web a través de un Proxy Para llamar a un servicio web cuando se está detrás de un proxy hay que crear un nuevo constructor en el Stub y pasarle los parametros del proxy (definidos en el environment.properties) como argumentos del constructor en aplicationcontext creado con la generación de código. La primera modificación que habrá que hacer al código generado será parametrizar la variables del proxy en el fichero environment.properties, ingresar los valores correctos para host, puerto, usuario y clave de acceso al proxy: environment.properties del módulo donde se usará el cliente #Propiedades del proxy http.proxyhost=icmupx01.madrid.org http.proxyport=80 http.proxyuser=prueba http.proxypassword=prueba En el fichero aplicationcontext habra que enlazar estos valores del proxy para que entren como argumentos del constructor del stub, a continuación un ejemplo: applicationcontext-miservicioweb.xml  <bean id="miservicioweb" class="atlas.clientews.client.clientfactory"...> <constructor-arg value="atlas.ws...miserviciowebstub" /> <constructor-arg type="..." value="${miservicioweb.endpoint}" /> <constructor-arg type="java.lang.string" value="${http.proxyhost}" /> <constructor-arg type="java.lang.integer" value="${http.proxyport}" /> <constructor-arg type="java.lang.string" value="${http.proxyuser}" /> <constructor-arg type="java.lang.string" value="${http.proxypassword}" /> </bean> 46 de 82

47 A continuación debemos de modificar el constructor del stub (tambíen podemos crearnos otro), lo que hariamos sería agrega los siguientes parametros de entrada al contructor como sigue:. public class MiServicioImpl implements MiServicio { [...] /** * Constructor that takes in a configcontext and useseperate listner */ public MiServicioWebStub(org.apache.axis2.context.ConfigurationContext configurationcontext, String targetendpoint, boolean useseparatelistener, String proxyhost, Integer proxyport, String proxyuser, String proxypassword) throws org.apache.axis2.axisfault { //To populate AxisService populateaxisservice(); populatefaults(); _serviceclient = new org.apache.axis2.client.serviceclient(configurationcontext,_service); _serviceclient.getoptions().setto(new org.apache.axis2.addressing.endpointreference( targetendpoint)); _serviceclient.getoptions().setuseseparatelistener(useseparatelistener); //Set the soap version _serviceclient.getoptions().setsoapversionuri( org.apache.axiom.soap.soap12constants.soap_envelope_namespace_uri); //Configuracion para salir a través de una proxy HttpTransportProperties.ProxyProperties pp = new HttpTransportProperties.ProxyProperties(); pp.setproxyname(proxyhost); pp.setproxyport(proxyport); pp.setusername(proxyuser); pp.setpassword(proxypassword); _serviceclient.getoptions().setproperty(httpconstants.proxy, pp); } [...] Paso 5 (Opcional): Agregar un timeout a un cliente de servicio web Para agregar un timeout a un cliente de un servicio web se deberá agregar dicho tiempo al constructor del stub del servicio web. A continuación se muestra un ejemplo, las lineas que hay que agregar estan resaltadas en color amarillo, concretamente el método settimeoutinmilliseconds. MiServicioImpl.java 47 de 82

48 @Service public class MiServicioImpl implements MiServicio { [...] /** * Constructor that takes in a configcontext and useseperate listner */ public MiServicioWebStub(org.apache.axis2.context.ConfigurationContext configurationcontext, String targetendpoint, boolean useseparatelistener) throws org.apache.axis2.axisfault { //To populate AxisService populateaxisservice(); populatefaults(); _serviceclient = new org.apache.axis2.client.serviceclient(configurationcontext,_service); _serviceclient.getoptions().setto(new org.apache.axis2.addressing.endpointreference( targetendpoint)); _serviceclient.getoptions().setuseseparatelistener(useseparatelistener); //Set the soap version _serviceclient.getoptions().setsoapversionuri( org.apache.axiom.soap.soap12constants.soap_envelope_namespace_uri); //El tiempo se establece en milisegudos, en este ejemplo se establece 5 minutos int timeoutinmilliseconds = ; _serviceclient.getoptions().settimeoutinmilliseconds(timeoutinmilliseconds); } [...] Paso 4a: Inclusión de Seguridad; WS Security (sólo para servicios seguros) Para realizar invocaciones a servicios web seguros partiendo de un cliente NO ATLAS será necesario realizar varias acciones. La primera de ellas es cambiar la definición del cliente en el fichero de Spring donde se define este. Dicho fichero se llamará applicationcontext-[nombreservicio].xml. En la definición del servicio habrá que cambiar la clase ClientFactory por SecureClientFactory. La nueva definición del servicio será así (se marcan en amarillo las partes que cambian): applicationcontext-ejemploservicioseguro.xml <beans> <bean id="miservicioweb" class="atlas.clientews.client.secureclientfactory"> <constructor-arg value="ejpl.services.miserviciowebstub" /> <constructor-arg type="java.lang.string" value="${miservicioweb.endpoint}" /> </bean> </beans> 48 de 82

49 Además de este cambio, también tendrán que definirse las credenciales de seguridad: <beans> applicationcontext-.xml <bean id=" miservicioweb " class="atlas.clientews.client.secureclientfactory"> <constructor-arg value="ejpl.services. MiServicioWebStub " /> <constructor-arg type="java.lang.string" value="${ miservicioweb.endpoint}" /> <property name="properties"> <props> <prop key="policypath">meta-inf/politicawssfirmado.xml</prop> <prop key="invokingapp">${app.id.asf}</prop> <prop key="operationmode">client</prop> <prop key="localkey">${miservicioweb.localkey}</prop> <prop key="remotekey">${miservicioweb.remotekey}</prop> <prop key="wsutslife">300000</prop> </props> </property> </bean> </beans> El bloque marcado en amarillo tendrá que añadirse tal cual pero modificando los nombre de las variables: En el campo policypath se ha de indicar el fichero de politica de firma: politicawssfirmado.xml politicawssfirmadocifrado.xml Sustituir las siguientes variables por las correspondientes de nuestro servicio. - miservicioweb.localkey - miservicioweb.remotekey. Y por último, deberán añadirse al fichero environment.properties las propiedades definidas en el fichero de Spring para el servicio: # Ids de aplicacion app.id.asf=ejpl_ws_cliente src/test/resources/environment.properties # Datos de WS miservicioweb.endpoint= miservicioweb.localkey=cliente_ws miservicioweb.remotekey=servidor_ws_cert Las variables a configurar son: Parámetro Descripcion Valor por defecto 49 de 82

50 app.id.asf Nombre de la aplicación en ASF Ej.: EJPL_WS_CLIENTE [nombreservicio].endpoint URL del servicio Ej.: eservicio> [nombreservicio].localkey Alias de la clave del cliente Ej.: cliente_ws [nombreservicio].remotekey Alias del certificado del servicio Ej.: servidor_ws_cert ATENCION Para poder incluir WS en un cliente de un servicio web es necesario previamente dar de alta la aplicación en ASF tal y como se describe en el apartado 3.2 Los valores de localkey y remotekey serán los alias de los certificados asociados a la aplicación en ASF Paso 4b: Inclusión de Seguridad a nivel de transporte (sólo para servicios seguros) Para realizar invocaciones a servicios web por https partiendo de un cliente NO ATLAS será necesario realizar varias acciones. La primera de ellas es cambiar la definición del cliente en el fichero de Spring donde se define este. Dicho fichero se llamará applicationcontext-[nombreservicio].xml. En la definición del servicio habrá que cambiar la clase ClientFactory por HttpsClientFactory. La nueva definición del servicio será así (se marcan en amarillo las partes que cambian): applicationcontext-miserviciowebhttps.xml <beans> <bean id="miserviciowebhttps" class="atlas.clientews.client.httpsclientfactory"> <constructor-arg value="ejpl.services.miserviciowebhttpsstub" /> <constructor-arg type="java.lang.string" value="${miserviciowebhttps.endpoint}" /> </bean> </beans> Además de este cambio, también tendrán que definirse las credenciales de seguridad: applicationcontext-ejemploserviciohttps.xml 50 de 82

51 <beans> <bean id="miserviciowebhttps" class="atlas.clientews.client.httpsclientfactory"> <constructor-arg value="ejpl.services.miserviciowebhttpsstub" /> <constructor-arg type="java.lang.string" value="${miserviciowebhttps.endpoint}" /> <property name="properties"> <props> <prop key="keystorepath">${https.keystore.path}</prop> <prop key="keystorepassword">${https.keystore.pass}</prop> <prop key="truststorepath">${https.truststore.path}</prop> <prop key="truststorepassword">${https.truststore.pass}</prop> <prop key="secureport">${https.secure.port}</prop> </props> </property> </bean> </beans> El bloque marcado en amarillo tendrá que añadirse sin modificaciones a la definición del cliente. Y por último, deberán añadirse al fichero environment.properties las propiedades definidas en el fichero de Spring para el servicio: # Ids de aplicacion app.id.asf=ejpl_ws_cliente src/test/resources/environment.properties # Definición del endpoint del servicio EjemploServicioHttps miservicioweb.endpoint= https.keystore.path=/usr/aplic_icm/prod/keystores/keystore.keystore https.keystore.pass=ca655c9bb562c d666cfd99b https.truststore.path=/usr/aplic_icm/prod/keystores/truststore.keystore https.truststore.pass=ca655c9bb562c d666cfd99b https.secure.port=443 ATENCION Los valores de los parametros de contraseñas (https.keystore.pass y https.truststore.pass) han de ser cifrados antes de configurarlos en el fichero environment.properties. Las variables a configurar son: Parámetro Descripcion Valor por defecto app.id.asf Nombre de la aplicación en ASF Ej.: EJPL_WS_CLIENTE [nombreservicio].endpoint URL del servicio Ej.: ces/<nombreservicio> 51 de 82

52 https.keystore.path https.keystore.pass https.truststore.path https.truststore.pass Ruta al almacén de certificados con el certificado de cliente de conexión Contraseña de acceso al almacén del certificado de cliente (configurar cifrada) Ruta al almacén de certificados con las Cas admitidas en la conexión HTTPS Contraseña de acceso al almacén de CAs de confianza (configurar cifrada) Ej.: ssl/keystore.keystore Ej.: desarrollo Ej.: ssl/truststore.keystore Ej.: desarrollo https.secure.port Puerto seguro de conexión Ej.: Llamadas a Servicios Web Con Usuario y Password usando HHTP Basic En caso de que dispongamos de la necesidad de llamar a un Servicio Web que requiere una autenticación de usuario y password mediante transporte http Básico, con un cliente NO ATLAS, será necesario modificar el código generado en nuestra clase Stub, de tal manera que al realizar la llamada al constructor desde Spring se incluya la seguridad requerida. Al crear el objeto con Spring, utilizamos el constructor ya autogenerado de 3 parámetros, endpoint, username y password (obtenidos de nuestro enviroment.properties): applicationcontext(nombrews)service.xml =============================================================================== --> <bean id="si_consultasgastos_outservice" class="gtri.client.nexus.si_consultasgastos_outservice.si_consultasgastos_outservicestub"> <constructor-arg type="java.lang.string" value="${si_consultasgastos_outservice.endpoint}" /> <constructor-arg type="java.lang.string" value="${si_consultasgastos_outservice.username}" /> <constructor-arg type="java.lang.string" value="${si_consultasgastos_outservice.password}" /> </bean> Y en la clase autogenerada Stub, localizamos nuestro constructor Clase autogenerada Stub /** * Constructor that takes in a configcontext and useseperate listner */ public SI_ConsultasGastos_OutServiceStub(java.lang.String targetendpoint, java.lang.string username, java.lang.string password) throws org.apache.axis2.axisfault { 52 de 82

53 En este constructor, observaremos el siguiente código: Clase autogenerada Stub /** * Constructor that takes in a configcontext and useseperate listner */ public SI_ConsultasGastos_OutServiceStub(java.lang.String targetendpoint, java.lang.string username, java.lang.string password) throws org.apache.axis2.axisfault { //Resto de codigo } _serviceclient.getoptions().setusername(username); _serviceclient.getoptions().setpassword(password); El cual, debe ser sustituido por lo siguiente para habilitar la autenticación Básica: Clase autogenerada Stub /** * Constructor that takes in a configcontext and useseperate listner */ public SI_ConsultasGastos_OutServiceStub(java.lang.String targetendpoint, java.lang.string username, java.lang.string password) throws org.apache.axis2.axisfault { //Resto de codigo HttpTransportProperties.Authenticator auth = new HttpTransportProperties.Authenticator(); auth.setusername(username); auth.setpassword(password); ArrayList<String> authschemes = new ArrayList<String>(); authschemes.add(httptransportproperties.authenticator.basic); auth.setauthschemes(authschemes); auth.setpreemptiveauthentication(true); _serviceclient.getoptions().setproperty(httpconstants.chunked, false); _serviceclient.getoptions().setproperty(httpconstants.authenticate, auth); } 53 de 82

54 UTILIDADES A continuación se muestran las distintas utilidades del framework para facilitar los desarrollos de servicios web Módulo de log de mensajes Este módulo de log permitirá visualizar en trazas todos los mensajes enviados y recibidos por un cliente o servicio web. A continuación se muestra un ejemplo de la salida de este módulo: salida log consola 13:20:16,625 DEBUG - Servicio creado. Devolviendo instancia. 13:20:16,766 DEBUG - ************************************************* 13:20:16,766 DEBUG - ** Mensaje de SALIDA 13:20:16,766 DEBUG - ** Accion: urn:alterar 13:20:16,766 DEBUG - ** Hacia: Address: 13:20:16,781 DEBUG - ************************************************* 13:20:16,938 DEBUG - <?xml version='1.0' encoding='utf-8'?><soapenv:envelope xmlns:soapenv=" xmlns:ns3=" xmlns:ns2=" de cadena de entrada</ns2:cadena1><ns2:limite xmlns:ns2=" 1</ns2:limite></ns3:args0></ns3:alterar></soapenv:Body></soapenv:Envelope> ATENCION El uso de este módulo solo es recomendable para entornos de desarrollo. En ningún caso se permitirá su uso en entornos productivos. Para poder activar la salida de log tanto en clientes como en servicios web, será necesario realizar las siguientes acciones: Paso 1: incluir la dependencia en el fichero pom.xml (en los arquetipos de servicio web ya está incluida). pom.xml <dependencies> <dependency> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-clientews-message-logger-lib</artifactid> <version>${atlasfrm-clientews-message-logger-lib.version}</version> <type>mar</type> </dependency> </dependencies> 54 de 82

55 Paso 2: activar trazas de debug para el paquete atlas.ws.util.message. Framework Atlas log4j.xml <category name="atlas.ws.util.message" class="atlas.core.log.atlaslogger"> <level value= debug /> </category> Paso 3: solo en el caso del servicio web (los clientes activarán el módulo si está disponible como dependencia), habrá que activar el módulo en el fichero services.xml para cada servicio. services.xml <service name="ejemploservicionoseguro"> <messagereceivers> </messagereceivers> <module ref="atlasfrm-clientews-message-logger" /> </service> 4.4. Configuración de proxy A continuación se detalla la información relativa a la activación del proxy en las llamadas de Axis2. Esta configuración puede ser necesaria en algunos entornos de ICM como puede ser el de desarrollo cuando se realizan llamadas a servicios web externos. El primer paso es asegurarse que se tiene activa la dependencia con la librería atlasfrm-clientews-lib en el fichero pom.xml: pom.xml <dependency> <groupid>atlasfrm</groupid> <artifactid>atlasfrm-clientews-lib</artifactid> <version>${atlasfrm-clientews-lib.version}</version> </dependency> A continuación se deben añadir las propiedades correspondientes en el fichero environment.properties del proyecto que usará el cliente de servicios web. En el caso de proyectos Atlas, se editará el fichero environment.properties del módulo web (aunque el cliente del servicio se haya desarrollado en el módulo lib). 55 de 82

56 environment.properties # Configuración de acceso por proxy aplicacion.proxy.activo=true aplicacion.proxy.host=icmupx01.madrid.org aplicacion.proxy.port=80 aplicacion.proxy.user=xxxx aplicacion.proxy.password=xxxx Si el parámetro aplicacion.proxy.activo vale false o no está configurado, no se utilizará proxy aunque se hayan especificado correctamente los parámetros de acceso. De esta forma se puede activar y desactivar el acceso por proxy con facilidad. Finalmente, se especificarán las propiedades del proxy en las propiedades del cliente de servicio web: applicationcontext-client.xml  <bean id="ejemploservice" class="atlas.test_ws1.client.clienteejemploservice"> <constructor-arg value="${ejemploservice.endpoint}" /> <property name="properties"> <props> <prop key="proxy.activo">${aplicacion.proxy.activo}</prop> <prop key="proxy.host">${aplicacion.proxy.host}</prop> <prop key="proxy.port">${aplicacion.proxy.port}</prop> <prop key="proxy.user">${aplicacion.proxy.user}</prop> <prop key="proxy.password">${aplicacion.proxy.password}</prop> </props> </property> </bean> Para clientes seguros, se añadirán las propiedades del proxy a las de seguridad. El siguiente ejemplo muestra la configuración para un cliente no atlas: applicationcontext-client.xml 56 de 82

57 <bean id="servicedispatcherservice" class="atlas.clientews.client.clientfactory"> <constructor-arg value="test.ws.client.noatlasserservice.servicestub" /> <constructor-arg type="java.lang.string" value="${service.endpoint}" /> <property name="properties"> <props> <prop key="proxy.activo">${aplicacion.proxy.activo}</prop> <prop key="proxy.host">${aplicacion.proxy.host}</prop> <prop key="proxy.port">${aplicacion.proxy.port}</prop> <prop key="proxy.user">${aplicacion.proxy.user}</prop> <prop key="proxy.password">${aplicacion.proxy.password}</prop> </props> </property> </bean> 4.5. Personalización de mensajes de error En algunas situaciones es necesario personalizar los mensajes Soap Fault que se retornan como resultado de un error de aplicación o de seguridad. Las excepciones de seguridad pueden producir mensajes Soap Fault personalizados a las necesidades funcionales con las siguientes instrucciones: 1. Implementar la interfaz atlas.clientews.fault.soapfaultprovider atlas.clientews.fault.soapfaultprovider public interface SoapFaultProvider { } /** * Método al que se llamará desde el Framework cuando se * produzca una excepción * msgctx contexto del mensaje de Axis2 t excepcion producida durante la validación o * procesamiento del mensaje AxisFault */ void processexception(messagecontext msgctx, AtlasSecurityException t) throws AxisFault; Esta interfaz solo contiene un método processexception al que se le pasan dos parámetros: el contexto del mensaje de Axis 2 y la excepción de seguridad lanzada. La implementación de este método deberá lanzar una excepción AxisFault personalizada con la que Axis 2 generará el mensaje Soap Fault. 2. Configurar la implementación de SoapFaultProvider en el fichero services.xml. Para que ATLAS pueda delegar la gestión del error a la implementación de SoapFaultProvider, se deberá 57 de 82

58 configurar el parámetro errortranslator en el fichero services.xml como un parámetro del servicio: services.xml <service name="ejemploservicewss2"> <parameter name="...</parameter>... <parameter name="errortranslator">mi.gestor.de.excepciones</parameter>... <messagereceivers> <messagereceiver mep=" El gestor de errores Soap Fault por defecto del framework es la clase atlas.clientews.fault. DefaultSoapFaultProvider Especificación SoapFault SCSPv3 La especificación SCSPv3 se encarga de definir las comunicaciones de servicios web entre las distintas administraciones públicas. En ATLAS se ha dado soporte a la especificación de Soap Fault a través de la implementación atlas.clientews.fault.scsp3soapfaultprovider. La configuración debe realizarse según el apartado anterior: Configuarción SCSPv3 en services.xml <service name="ejemploservicewss2"> <parameter name="...</parameter>... <parameter name="errortranslator">atlas.clientews.fault.scsp3soapfaultprovider</parameter>... <messagereceivers> <messagereceiver mep=" Con esta configuración, se generarán errores de seguridad con la siguiente forma: Ejemplo de SoapFault SCSPv3 (Soap 1.1) 58 de 82

59 <soapenv:envelope xmlns:soapenv=" <soapenv:body> <soapenv:fault> <faultcode xmlns:wsse=" wss-wssecurity-secext-1.0.xsd">wsse:InvalidSecurity</faultcode> <faultstring>[0302] Certificado caducado</faultstring> <detail> <Atributos xmlns=" <IdPeticion>001_DIR_MINHAP_FNUX0_9CC4</IdPeticion> <NumElementos>1</NumElementos> <TimeStamp> T14:25: </TimeStamp> <Estado> <CodigoEstado>0302</CodigoEstado> <LiteralError>Certificado caducado</literalerror> <TiempoEstimadoRespuesta>0</TiempoEstimadoRespuesta> </Estado> <CodigoCertificado>SDVSTCFWNS10</CodigoCertificado> </Atributos> </detail> </soapenv:fault> </soapenv:body> </soapenv:envelope> 5. CREACION DE TESTS UNITARIOS PARA SOAPUI En la creación de un proyecto de servicio web, se crean tres módulos: el módulo web para generar un servicio web, el módulo lib para la generación del cliente de dicho servicio web, y el módulo test que contiene proyectos de SoapUI para realizar tests del servicio web sin utilizar el cliente Java del módulo lib. En el proyecto de servicio web inicial, se incluyen ejemplos de proyectos sin seguridad, con seguridad https y con seguridad de cifrado y firmado en el mensaje SOAP. A continuación se muestra como crear proyectos nuevos para los servicios web a implementar Proyecto SoapUI sin seguridad En este caso, se importará el proyecto desde el WSDL del servicio web. Para ello, deberá ejecutarse primero el servicio web con el comando: mvn clean install jetty:run Una vez arrancado el servidor Jetty, se accederá a la URL: para listar los servicios disponibles. Pulsar con el botón derecho en el nombre del servicio y guardar el enlace con extensión.wsdl en el módulo test, directorio src/main/resources/wsdl. 59 de 82

60 Una vez guardado el descriptor WSDL del servicio, abrir el programa SoapUI y generar un nuevo proyecto. Project Name: nombre del servicio. Initial WSDL/WADL: buscar el fichero WSDL del servicio guardado. Marcar elementos en rojo en la imagen. Guardar el proyecto en la carpeta soapui. Antes de ejecutar operaciones, comprobar que la URL del servicio está correctamente configurada (puede faltar el puerto). 60 de 82

61 Proyecto SoapUI con seguridad https Generar un proyecto nuevo siguiendo las instrucciones del apartado anterior. Como en el caso anterior, comprobar que las URLs del servicio están correctamente configuradas con el protocolo HTTPS (y el puerto, que en jetty es 9443). Hacer doble click en el nombre del proyecto para abrir sus propiedades. Pulsar en la pestaña WS-Security Configurations y en la pestaña inferior Keystores/Certificates. Pulsar el botón + y añadir el almacen client_ssl.jks (o cualquier otro de que se disponga en el proyecto). Introducir la contraseña del almacén. Una vez hecho esto solo es necesario asignar el almacén de certificados a cada petición y asegurarse que la URL del servicio web es correcta: 61 de 82

62 Proyecto SoapUI con seguridad firmado/cifrado Ya que la configuración de seguridad en este apartado es compleja, a continuación se muestran los pasos necesarios para configurar un proyecto nuevo tomando como referencia el proyecto de EjemploServicioSeguro ya existente. Como en el caso del servicio sin seguridad, ha de guardarse a disco el descriptor WSDL del servicio seguro. A continuación, cargar el proyecto de ejemplo EjemploServicioSeguro-soapui-project.xml en la carpeta src/main/resources/soapui del módulo test. 62 de 82

63 Pulsar con el botón derecho en las entradas Soap11Binding y Soap12Binding y eliminarlas. 63 de 82

64 A continuación, pulsar con el botón derecho en el nombre de proyecto y seleccionar la opción Add WSDL. Seleccionar el fichero WSDL del proyecto guardado y asegurarse de marcar la opción Create sample requests for all operations?. 64 de 82

65 Cambiar el nombre de proyecto por el nombre del servicio web implementado. Por último, solo es necesario seleccionar la seguridad en cada operación del proyecto. Para ello, una vez abierta la pantalla de la operación, pulsar en Aut y establecer los valores de Outgoing WSS e Incoming WSS. 65 de 82

66 En el caso de Outoing WSS, se seleccionara politicawssfirmadocifrado_salida para operaciones Soap12 y politicawssfirmadosoap11_salida para operaciones Soap11. Para Incoming WSS se seleccionará siempre politicawssfirmadocifrado_entrada. Por último solo quedará ejecutar la operación para comprobar que la configuración es correcta. 66 de 82

67 Utilizar otro certificado de cliente En este apartado se mostrarán las modificaciones a la configuración de seguridad del proyecto SoapUI si se quiere utilizar otro certificado de cliente. En el ejemplo mostrado a continuación se utilizará el fichero pf-5m.p12 descargado de la web de certificados de ICM. Abrimos el proyecto SoapUI y hacemos doble click en el nombre para abrir las propiedades y tener acceso a la configuración de seguridad. 67 de 82

68 Seleccionamos la pestaña WS-Security Configurations, y en ella la pestaña Keystores / Certificates. En esta pantalla, añadimos el almacén.p12 que contiene el certificado de cliente que se quiere utilizar. En la pestaña Incoming WS-Security Configurations, en la columna Decrypt Keystore seleccionamos el nuevo almacén que contiene el certificado de cliente. Configuramos la contraseña del almacén. Por último, en la pestaña Outgoing WS-Security Configurations, en cada una de las dos entradas (politicawssfirmadocifrado_salida y politicawssfirmadocifradosoap11_salida), en la pestaña Signature, modificamos las entradas Keystore, Alias y Password con los datos del nuevo certificado cliente. 68 de 82

69 Con estos cambios, el certificado cliente que se utilizará en la seguridad corresponderá al fichero pf-5m.p12 usado para el ejemplo. 6. OTRAS CONFIGURACIONES DE SEGURIDAD 6.1. Servicio web con firmado de mensaje y autenticación HTTPS Para realizar esta configuración habrá que haber realizado antes la del apartado anterior y añadirle los datos de la conexión https Servicio web Una vez realizada la modificación para eliminar el cifrado del mensaje de la política, solo quedará añadir la configuración del plugin https. services.xml 69 de 82

70 <service name="ejemploserviciosegurofirmadohttps"> <parameter name="asfinvokingapp">${app.id.asf}</parameter> <transports> <transport>https</transport> </transports> <module ref="atlasfrm-clientews-seguridad-https" /> <module ref="atlasfrm-clientews-seguridad" /> <wsp:policy wsu:id="politicawssfirmado"...> <sp:signedparts xmlns:sp="..."> <sp:body/> </sp:signedparts> </wsp:policy> </service> De esta forma se activará también el módulo https permitiendo la autenticación del certificado de las conexiones entrantes Cliente ATLAS En el caso de un cliente ATLAS, simplemente habrá que añadir los datos de la conexión https a la configuración de Spring del cliente (después de haber modificado la política de seguridad conforme al apartado 7.1.2). Fichero applicationcontext-xxxx_lib.xml <bean id="ejemploclientesegurofirmadohttps" class="...services.impl.ejemploclienteseguro"> <constructor-arg value="${ejemploclientesegurofirmadohttps.endpoint}" /> <property name="properties"> <props> <prop key="policypath">meta-inf/politicawssfirmado.xml</prop> <prop key="invokingapp">${app.id.asf}</prop> <prop key="operationmode">client</prop> <prop key="localkey">${ejemploclienteseguro.localkey}</prop> <prop key="remotekey">${ejemploclienteseguro.remotekey}</prop> <prop key="wsutslife">300000</prop> <prop key="keystorepath">${https.keystore.path}</prop> <prop key="keystorepassword">${https.keystore.pass}</prop> <prop key="truststorepath">${https.truststore.path}</prop> <prop key="truststorepassword">${https.truststore.pass}</prop> <prop key="secureport">${https.secure.port}</prop> </props> </property> </bean> 70 de 82

71 ATENCION Los valores de los parametros de contraseñas (https.keystore.pass y https.truststore.pass) han de ser cifrados antes de configurarlos en el fichero environment.properties Cliente NO ATLAS En el caso del cliente NO ATLAS la configuración es idéntica a la del apartado anterior. Simplemente hay que añadir la configuración de la conexión HTTPS. <beans> Fichero applicationcontext-xxxx_lib.xml <bean id="ejemploserviciosegurofirmado" class="atlas.clientews.client.secureclientfactory"> <constructor-arg index="0" value="ejpl.services.ejemploserviciosegurostub" /> <constructor-arg index="1" value="${ejemploservicioseguro.endpoint}" /> <constructor-arg index="2"><null/></constructor-arg> <constructor-arg index="3" value="meta-inf/politicawssfirmado.xml" /> <property name="properties"> <props> <prop key="invokingapp">${app.id.asf}</prop> <prop key="operationmode">client</prop> <prop key="localkey">${ejemploservicioseguro.localkey}</prop> <prop key="remotekey">${ejemploservicioseguro.remotekey}</prop> <prop key="wsutslife">300000</prop> <prop key="keystorepath">${https.keystore.path}</prop> <prop key="keystorepassword">${https.keystore.pass}</prop> <prop key="truststorepath">${https.truststore.path}</prop> <prop key="truststorepassword">${https.truststore.pass}</prop> <prop key="secureport">${https.secure.port}</prop> </props> </property> </bean> </beans> ATENCION Los valores de los parametros de contraseñas (https.keystore.pass y https.truststore.pass) han de ser cifrados antes de configurarlos en el fichero environment.properties. 71 de 82

72 Tests de SoapUI Partiendo del proyecto del apartado anterior (7.1.4) simplemente habrá que añadir el almacén de certificados para la conexión y configurarla en cada petición: En primer lugar, se añadirá el nuevo almacén de certificados para la conexión HTTPS: Haciendo doble click en el nombre del proyecto se abrirán las propiedades de este. En la pestaña WS-Security Configurations iremos a Keystores / Certificates y añadiremos el almacén de certificados. Después iremos añadiendo a cada petición el almacén de seguridad, asegurándonos que el endpoint del servicio apunta a una dirección HTTPS: 72 de 82

73 73 de 82