ATLAS MANUAL DE USUARIO Servicios Web

Transcripción

1 ATLAS MANUAL DE USUARIO Servicios Web Versión 1.4 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.4 Fecha Versión 11/07/2013 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio Área de Aplicaciones Especiales 1.0 Versión inicial del documento y Arquitectura de Software 18/10/2011 Nuevo modelo de seguridad. Apartados 3.3 y 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. 1.2 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. Área de Aplicaciones Especiales 24/02/2012 y Arquitectura de Software Área de Aplicaciones Especiales 25/10/2012 y Arquitectura de Software 2 de 69

3 Versión Causa del Cambio Responsable del Cambio Fecha del Cambio Añadido apartado 7 con nuevas configuraciones de seguridad Apartado Obligación de parametrizar el endpoint del servicio. Cambiada referencia AsfService por CryptService. Se decide que la seguridad en los servicios Área de Aplicaciones Especiales 1.3 web se implementará mediante WS Security y Arquitectura de Software 20/12/2012 en los servicios web 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 1.4 configuración de proxy. Área de Aplicaciones Especiales Modificado apartado para incluir el caso y Arquitectura de Software de que el wsdl no sea autogenerado si no que 27/05/2013 se parta de un wsdl predeterminado 3 de 69

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: Levantar el Servidor Paso 6: Obtener el wsdl del Servicio Paso 7: Creación del Cliente Paso 8: Configuración del Cliente Paso 9: 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 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) UTILIDADES MÓDULO DE LOG DE MENSAJES CONFIGURACIÓN DE PROXY CREACION DE TESTS UNITARIOS PARA SOAPUI Proyecto SoapUI sin seguridad Proyecto SoapUI con seguridad https 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 de 69

5 7.2. 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 ENLACES RELACIONADOS de 69

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 69

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 69

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 ultimo 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. 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 69

9 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 area 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 69

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 69

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 69

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. A continuación se muestra el código de alguno de estos objetos: Clase lib/src/main/java/xxxx/domain/datosentrada.java 12 de 69

13 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. 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"; } 13 de 69

14 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. 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="miprimerservicio"> <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> </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. 14 de 69

15 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: 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 6: Obtener el wsdl del Servicio Para obtener el wsdl de nuestro servicio web se puede a través de una url del siguiente tipo: 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: MiPrimerServicio.wsdl. 15 de 69

16 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 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" /> 16 de 69

17 <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: [^] [^] Framework Atlas Paso 7: 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 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. ClienteMiPrimerService.java 17 de 69

18 package prueba.client; 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: Definición del método invoke 18 de 69

19 /** * 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 8: 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. A continuación se muestra un ejemplo: 19 de 69

20 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 9: 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): lib/src/test/java/clientemiprimerservicetest.java 20 de 69

21 package prueba.client; import static org.junit.assert.*; 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: lib/src/test/resources/environment.properties 21 de 69

22 # 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. 22 de 69

23 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 23 de 69

24 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: 24 de 69

25 # 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: Servicio con politicawssfirmado 25 de 69

26 <service name="miprimerserviciowssecurity1"> <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> 26 de 69

27 <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 27 de 69

28 <service name="miprimerserviciowssecurity1"> <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> 28 de 69

29 <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 29 de 69

30 encryptionoperation decryptionoperation validationoperation 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: CIFRADO Por defecto: DESCIFRADO Por defecto: VERIFICACION 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. package prueba123.client; ClienteMiPrimerService.java 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; } 30 de 69

31 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> 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. - miprimerservicio.localkey - miprimerservicio.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 31 de 69

32 # 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 [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 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: 32 de 69

33 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. 33 de 69

34 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> <!-- Importar fichero de contexto de la librería --> <!-- contiene definición de bean 'miprimerservicio' --> <import resource="classpath:/conf/applicationcontext-xxxx_ws_lib.xml" /> 34 de 69

35 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 MiPrimerServicio 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 MiPrimerServicio miprimerservicio.endpoint= miprimerservicio.localkey=cliente_ws miprimerservicio.remotekey=servidor_ws_cert Los valores de las variables son los siguientes: Parámetro Descripcion Valor por defecto 35 de 69