MANTENIMIENTO APLICACIONES LOTE 1 - MANUAL DE USUARIO (17-018-01-MDU-FIRE-2021/05/07-v1)
←
→
Transcripción del contenido de la página
Si su navegador no muestra la página correctamente, lea el contenido de la página a continuación
G OBIERNO DEL P RINCIPADO DE A STURIAS Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MANTENIMIENTO APLICACIONES LOTE 1 MANUAL DE USUARIO (17-018-01-MDU-FIRE-2021/05/07-v1)
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 2 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario ÍNDICE ÍNDICE .................................................................................................................................................... 2 1. CONTROL DEL DOCUMENTO ........................................................................................................ 3 1.1. Información general ...................................................................................................................... 3 1.2. Lista de distribución ...................................................................................................................... 3 1.3. Histórico de revisiones .................................................................................................................. 3 1.4. Estado del documento ................................................................................................................... 3 1.5. Versión de FIRe ............................................................................................................................ 3 2. INTRODUCCIÓN ............................................................................................................................... 5 2.1. Descripción de la aplicación ......................................................................................................... 5 2.2. Alcance de la aplicación ................................................................................................................ 5 2.3. Usuarios de la aplicación (roles) ................................................................................................... 6 2.4. Acceso a la aplicación ................................................................................................................... 6 3. INTEGRACIÓN................................................................................................................................... 7 3.1. Administración de FIRe ................................................................................................................ 7 3.2. Operaciones del componente distribuido ...................................................................................... 7 3.2.1. Flujos de operación ................................................................................................................ 7 3.2.2. Integración componente distribuido Java ............................................................................. 12 3.2.3. Configuración ....................................................................................................................... 12 3.2.4. Operaciones .......................................................................................................................... 15 4. EJEMPLOS DE FIRMA .................................................................................................................... 57 4.1. Firma de un documento ............................................................................................................... 57 4.2. Firma de varios documentos ....................................................................................................... 62 5. PARÁMETROS NECESARIOS A PROPORCIONAR POR LAS EMPRESAS............................. 66 D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 3 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 1. CONTROL DEL DOCUMENTO 1.1. Información general Título Manual de usuario FIRe Creado por: Ricoh A revisar por: A aprobar por: 1.2. Lista de distribución Nombre Puesto Correo electrónico Unidad o Departamento / Empresa Observaciones 1.3. Histórico de revisiones Versión Fecha Autor Unidad o Departamento / Empresa Observaciones Rodrigo González 1.0 Ricoh Versión inicial Díaz Se añade información sobre la versión Rodrigo González 1.1 Ricoh de FIRe Díaz utilizada y sobre los clientes .Net y PHP 1.4. Estado del documento Versión Estado Fecha Responsable Firma 1.5. Versión de FIRe La versión de FIRe que se va a utilizar es la 2.3 que se puede encontrar en https://github.com/ctt- gob-es/fire/tree/v2.3 D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 4 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 5 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 2. INTRODUCCIÓN 2.1. Descripción de la aplicación FIRe es un sistema para la generación de firmas electrónicas con certificado de usuario. Las aplicaciones web que deseen integrar la firma electrónica de datos como parte de su flujo de operación pueden utilizar FIRe para tal fin. FIRe permite el uso tanto de certificados locales del usuario, como el uso de los certificados de proveedores de firma en la nube, como es el caso de Cl@ve Firma. Gracias a eso, al integrar el API de FIRe en una aplicación, se consigue que el usuario pueda usar certificados locales y remotos sin necesidad de crear un flujo de trabajo distinto para cada uno de ellos. FIRe se componen principalmente de un componente “centralizado” servidor encargado de la firma electrónica de documentos con certificados de usuario y un API “distribuido” para la integración de aplicaciones con ese componente centralizado. Las aplicaciones que deseen utilizar las funcionalidades de firma de FIRe sólo tendrán integrar que utilizar este API. Las funcionalidades de firma ofrecidas por el API de FIRe son: • Firma electrónica individual: o Firma o multifirma electrónica de un documento • Firma de lotes o Firma o multifirma de múltiples documentos simultáneamente. Para que el componente central atienda las peticiones de nuestra aplicación, esta debe haberse registrado previamente. Este registro puede hacerlo un administrador a través del módulo de administración de FIRe, mediante el cual dará de alta la nueva aplicación, establecerá el certificado con el que deberá autenticarse y obtendrá como resultado el código alfanumérico que deberá utilizar el componente distribuido como identificador de aplicación (AppId). A partir de entonces, podrá realizar peticiones a FIRe utilizando este certificado e identificador de aplicación. 2.2. Alcance de la aplicación Aquellas aplicaciones del nuevo marco de trabajo del Principado de Asturias que quieran realizar firmas de documentos deberán hacerlo a través de la integración con FIRe. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 6 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 2.3. Usuarios de la aplicación (roles) 2.4. Acceso a la aplicación Las Urls donde está presente el componente central de FIRe con el que se comunican las aplicaciones son las siguientes: • Desarrollo: https://172.30.0.24:10543/fire-signature/fireService • Integración: https://integ73.asturias.es/fire-signature/fireService • Producción: https://www73.asturias.es/fire-signature/fireService D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 7 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 3. INTEGRACIÓN En el presente punto se explican las modificaciones necesarias a realizar en el componente de administración de FIRe (FIRE-ADM), en el Backend y en el Frontend de las aplicaciones para la integración de las mismas con FIRe. 3.1. Administración de FIRe La aplicación FIRE-ADM es la que se encarga de administrar las aplicaciones que están dadas de alta en FIRe para realizar firmas. Para dar de alta una nueva aplicación se debe proporcionar al administrador de FIRe el nombre de la aplicación y un certificado digital (*.cer), que será el mismo certificado que tendrá que enviar la aplicación cliente es sus comunicaciones con FIRe. Al dar de alta una aplicación se generará un identificador que el administrador deberá proporcionar a las aplicaciones cliente y que estas tendrán que configurar para sus comunicaciones con FIRe. 3.2. Operaciones del componente distribuido 3.2.1. Flujos de operación FIRe permite a las aplicaciones integrar 2 flujos de operación distintos: • Firma de un único documento: o Siguiendo este flujo de operación una aplicación puede enviar a firmar un documento indicando la configuración de firma que desea utilizar (operación de firma, algoritmo, formato, configuración específica del formato y formato avanzado al que actualizar la firma) y seguidamente obtener la firma resultante. • Firma de un lote de documentos o Siguiendo este flujo de operación una aplicación puede crear un lote de firma indicando la configuración de firma que desea utilizar (operación de firma, algoritmo, formato, configuración específica del formato y formato avanzado al que actualizar la firma). Seguidamente puede agregar tantos documentos como desee al lote de firma, indicando opcionalmente si debe aplicarse una configuración de firma distinta a la del lote y finalmente puede ordenar la firma de todo el lote. Una vez hecho puede recuperar el resultado de la firma del lote y a continuación puede recuperar cada firma individual. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 8 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 3.2.1.1. Firma de un único documento Para la firma de un único documento una aplicación deberá seguir la siguiente secuencia de pasos: 1. Llamar al método sign del componente distribuido. o A este método deberemos proporcionarle: Identificador de nuestra aplicación frente al componente central. Este identificador nos lo deberá pasar el administrador después de dar de alta nuestra aplicación en el componente central. Identificador de usuario. Comúnmente el DNI. Si se restringe el uso para sólo utilizar certificados locales, puede indicarse cualquier valor. Configuración de firma. Esto es la operación criptográfica, el algoritmo, formato y la configuración del formato. Datos a firmar. La configuración del conector con el proveedor de firma. Aquí se debe indicar in-formación como las URL de las páginas o servicios de su aplicación web a las que redirigir al usuario en caso de que la operación tenga éxito o falle, el origen de los certificados, etc. Como resultado se obtendrá un objeto con el identificador de la transacción y una URL de redirección. 2. Redirigir al usuario a la URL de redirección obtenida que será la de una página web del componente central. o A partir de ese momento la aplicación perderá el control de la navegación del usuario que pasará a navegar por las páginas del componente central y de la GISS hasta completar la operación de firma. o Una vez finalizada la operación, el usuario será redirigido automáticamente a la página de éxito o a la página de error de nuestra aplicación, según haya terminado la operación. Estas direcciones son las que debieron definirse a través del parámetro de configuración que indicamos en la llamada al método sign del API. 3. En la página resultante, se deberá llamar al método apropiado del API para recoger el resultado de la operación: o En caso de ser redirigidos a la página de éxito, se deberá llamar al método recoverSignResult proporcionándole: Identificador de nuestra aplicación frente al componente central. Este identificador nos lo deberá pasar el administrador después de dar de alta nuestra aplicación en el componente central. Identificador de la transacción. Este deberá ser el identificador proporcionado como resultado de la llamada al método sign. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 9 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario Formato al que actualizar la firma electrónica por medio de la Plataforma @firma. Este nos devolverá un objeto con la firma resultante de la operación o, en caso de encontrarse un error en el último momento, el error detectado. o En caso de ser redirigidos a la página de error, se deberá llamar al método recoverErrorResult. Este método nos devolverá un objeto con el error detectado. 4. Una vez tenemos el resultado de la operación, continuaremos con nuestro flujo de trabajo habitual. 3.2.1.2. Firma de un lote de documentos Para la firma de un lote de documentos una aplicación deberá seguir la siguiente secuencia de pasos: 1. Llamar al método createBatchProcess del componente distribuido. o A este método deberemos proporcionarle: Identificador de nuestra aplicación frente al componente central. Este identificador nos lo deberá pasar el administrador después de dar de alta nuestra aplicación en el componente central. Identificador de usuario. Comúnmente el DNI. Si se restringe el uso para sólo utilizar certificados locales, puede indicarse cualquier valor. Configuración de firma. Esto es la operación criptográfica, el algoritmo, formato, la configuración del formato y el formato al que mejorar la firma. Configuración de los conectores con los proveedores de servicios firma. Aquí se debe indicar información como las URL de las páginas o servicios de su aplicación web a las que redirigir al usuario en caso de que la operación tenga éxito o falle, el origen de los certificados, etc. o Como resultado se obtendrá un objeto con un identificador de transacción. 2. Llamar al método addDocumentToBatch para agregar un documento al lote de firma. o A este método deberemos proporcionarle, al menos: Identificador de nuestra aplicación frente al componente central. Este identificador nos lo deberá pasar el administrador después de dar de alta nuestra aplicación en el componente central. Identificador de la transacción. Este deberá ser el identificador proporcionado como resultado de la llamada al método createBatchProcess. Identificador de los datos a firmar. Este identificador puede ser cualquier cadena alfanumérica compuesta por caracteres ASCII básicos imprimibles, además de D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 10 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario los caracteres guion (‘-’) y guion bajo (‘_’). La firma del documento se devolverá identificada mediante esta misma cadena para que se sepa a qué datos corresponde. No se puede usar un mismo identificador más de una vez en el mismo lote. Datos a firmar. Configuración de los conectores con los proveedores de servicios firma. o Opcionalmente, se podría llamar a otra versión del método en el que se incorporase una nueva configuración de firma (a excepción del algoritmo de firma). En caso de usarse esta versión del método, se aplicará la configuración de firma indicada en él en lugar de la indicada durante la creación del lote para la firma de los datos proporcionados. o Este método no devuelve ningún resultado. 3. Repetir el paso anterior por cada documento que se desee agregar al lote. 4. Llamar al método signBatch para iniciar el proceso de firma del lote. o A este método deberemos proporcionarle: Identificador de nuestra aplicación frente al componente central. Este identificador nos lo deberá pasar el administrador después de dar de alta nuestra aplicación en el componente central. Identificador de la transacción. Este deberá ser el identificador proporcionado como resultado de la llamada al método createBatchProcess. Indicador de si deseamos que, una vez detectado un error en una de las firmas del lote, se detengan las operaciones de firma del lote que no hayan finalizado todavía. o Como resultado se obtendrá un objeto con el identificador de la transacción (el mismo que se tenía de la operación de crear lote) y una URL de redirección. 5. Redirigir al usuario a la URL de redirección obtenida que será la de una página web del componente central. o A partir de ese momento la aplicación perderá el control de la navegación del usuario que pasará a navegar por las páginas del componente central y de la GISS hasta completar la operación de firma. o Una vez finalizada la operación, el usuario será redirigido automáticamente a la página de éxito o a la página de error de nuestra aplicación, según haya terminado la operación. Estas direcciones son las que debieron definirse a través del parámetro de configuración que in-dicamos en la llamada al método sign del API. 6. En la página resultante, se deberá llamar al método apropiado del API para recoger el resultado de la operación: D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 11 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario o En caso de ser redirigidos a la página de éxito, se deberá llamar al método recoverBatchResult proporcionándole: Identificador de nuestra aplicación frente al componente central. Este identificador nos lo deberá pasar el administrador después de dar de alta nuestra aplicación en el componente central. Identificador de la transacción. Este deberá ser el identificador proporcionado como resultado de la llamada al método createBatchProcess. Este método nos devolverá un objeto con un XML del que se obtiene el listado de identificadores de los documentos agregados al lote, el resultado de la operación y, si falló esa firma concreta, una descripción del error detectado. En caso de encontrarse un error general en el último momento, el objeto se incluirá el error detectado. o En caso de ser redirigidos a la página de error, se deberá llamar al método recoverErrorResult. Este método nos devolverá un objeto con el error detectado. 7. Una vez sabemos cómo ha terminado cada una de las firmas del lote, podemos llamar al método recoverBatchSign para recuperar las firmas del lote que finalizaron correctamente. o A este método deberemos proporcionarle: Identificador de nuestra aplicación frente al componente central. Este identificador nos lo deberá pasar el administrador después de dar de alta nuestra aplicación en el componente central. Identificador de la transacción. Este deberá ser el identificador proporcionado como resultado de la llamada al método createBatchProcess. Identificador del documento del que queramos recuperar la firma. Este será alguno de los identificadores que utilizamos al agregar los documentos al lote mediante la llamada al método addDocumentToBatch y que hemos confirmado mediante el resultado obtenido por el método recoverBatchResult que la firma se generó correctamente. o La llamada a este método sólo funcionará con los identificadores de los documentos que se firmaron correctamente y sólo la primera vez que se llame para cada uno de esos identificadores. o No es posible recuperar una firma de un lote, sin haber recuperado previamente el resultado del lote. 8. Una vez hemos recuperar el resultado de todas las firmas que deseábamos obtener, podemos continuar con el flujo de trabajo de nuestra aplicación. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 12 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 3.2.2. Integración componente distribuido Java La implementación Java del componente distribuido está desarrollada para la integración de aplicaciones JSP. El componente se distribuye en forma de archivo JAR, al que deben acompañar otros dos (para el soporte de JSON) que son dependencias de este. El JAR del componente distribuido se entrega firmado para asegurar su integridad. Las bibliotecas son: • Componente distribuido Java: o fire-client-2.3.jar • Dependencias para el soporte de ficheros JSON: o javax.json-api-1.0.jar o javax.json-1.0.4.jar • Biblioteca para la escritura de logs: o slf4j-api-1.7.25.jar o (Biblioteca puente del sistema de log que se desee) Estas bibliotecas deben estar dentro del CLASSPATH de la aplicación que desee realizar las operaciones de firma en la nube. Todas las llamadas al API se realizan por medio de la clase: es.gob.fire.client.FireClient 3.2.2.1. Otros clientes Además del cliente Java explicado en este manual, existen también clientes .NET y PHP. Para más información sobre la integración con esos clientes se puede acudir al manual de integrador disponible en https://administracionelectronica.gob.es/ctt/fire 3.2.3. Configuración Para la configuración del componente distribuido Java se deberá construir el objeto FireClient con el identificador de la aplicación y un Properties con las propiedades a configurar. Las propiedades que se permiten configurar son: • fireUrl o URL del servicio del componente central. • javax.net.ssl.keyStore (Opcional) o Ruta del almacén de claves para la autenticación mediante certificado con el componente central. Este certificado debe estar dado de alta en la base de datos del componente central, asignado al identificador de la aplicación cliente en la que se esté integrando el componente distribuido. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 13 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario o Si se omite este parámetro se usará la configuración establecida a nivel global en la JRE. • javax.net.ssl.keyStorePassword (Opcional) o Contraseña del almacén de claves de autenticación SSL. • javax.net.ssl.keyStoreType (Opcional) o Tipo del almacén de claves del certificado de autenticación SSL: “JKS” (almacén de Java) o “PKCS12” (almacén PKCS12/PFX). o Por defecto, se considera que el almacén es de tipo JKS. • javax.net.ssl.trustStore (Opcional) o Ruta del almacén de certificados de confianza SSL. Esto se usa cuando el certificado con el que se ha montado el SSL del componente central no está en el almacén de confianza de Java y se desea establecer un almacén de confianza alternativo. o En caso de querer desactivar la comprobación del certificado SSL del servidor, se puede configurar el valor “all”. o Si se omite este parámetro se usará la configuración establecida a nivel global en la JRE. Por defecto, se confiará en los certificados dados de alta en el almacén “cacerts”. • javax.net.ssl.trustStorePassword (Opcional) o Contraseña del almacén de confianza. • javax.net.ssl.trustStoreType (Opcional) o Tipo del almacén de confianza: “JKS” (almacén de Java) o “PKCS12” (almacén PKCS12/PFX). o Por defecto, se considera que el almacén es de tipo JKS. Ejemplo de fichero de propiedades de configuración en formato yml: application: fire: client-config: fireUrl: https://integ73.asturias.es/fire-signature/fireService keyStore: "/opt/jboss/WEBAPPS/services/exampleApp/config/client_ssl.jks" keyStorePassword: ****** keyStoreType: JKS trustStore: "/opt/jboss/WEBAPPS/services/exampleApp/config/keystore_fire.jks" trustStorePassword: ****** trustStoreType: JKS Ejemplo de clase que se encarga de obtener los valores de esas propiedades en Spring Boot: package es.princast.mntpa.back.fire.config; import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 14 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario import org.springframework.context.annotation.Configuration; import org.springframework.validation.annotation.Validated; @Configuration @ConfigurationProperties(prefix = "application.fire.client-config") @Validated @Data public class ClientConfigProperties { private String fireUrl; private String keyStore; private String keyStorePassword; private String keyStoreType; private String trustStore; private String trustStorePassword; private String trustStoreType; public String getFireUrl() { return fireUrl; } public void setFireUrl(String fireUrl) { this.fireUrl = fireUrl; } public String getKeyStore() { return keyStore; } public void setKeyStore(String keyStore) { this.keyStore = keyStore; } public String getKeyStorePassword() { return keyStorePassword; } public void setKeyStorePassword(String keyStorePassword) { this.keyStorePassword = keyStorePassword; } public String getKeyStoreType() { return keyStoreType; } public void setKeyStoreType(String keyStoreType) { this.keyStoreType = keyStoreType; } public String getTrustStore() { return trustStore; } public void setTrustStore(String trustStore) { this.trustStore = trustStore; } public String getTrustStorePassword() { return trustStorePassword; } D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 15 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario public void setTrustStorePassword(String trustStorePassword) { this.trustStorePassword = trustStorePassword; } public String getTrustStoreType() { return trustStoreType; } public void setTrustStoreType(String trustStoreType) { this.trustStoreType = trustStoreType; } } 3.2.4. Operaciones Aquí se listan todas las operaciones disponibles a través del componente distribuido. Estas operaciones son compartidas por todos los componentes distribuidos de FIRe, independientemente de la implementación (Java, PHP o .NET) pero la implementación que aquí se detalla es Java. Gran parte de las operaciones indicadas a continuación forman parte de los flujos de operación descritos en el apartado anterior. En este apartado se mostrará, para cada operación, un ejemplo de implementación en Java construido con Spring-Boot para el Backend y Angular para el Frontend. 3.2.4.1. Construcción del cliente La clase FireClient dispone de dos constructores: • public FireClient(String appId, Properties config) o Construye el objeto con el que realizar las llamadas al componente central. o Parámetros: appId • Identificador de aplicación con el que debe autenticarse frente al componente central. config • Propiedades de configuración. • En este parámetro deberían ir las propiedades definidas en el fichero de configuración que se detalló en el apartado 3.2.3 de este manual o Lanza: es.gob.fire.client.ClientConfigFilesNotFoundException: Si no se han proporcionado las propiedades necesarias. • public FireClient(String appId) o Construye el objeto con el que realizar las llamadas al componente central. En este caso donde no se proporcionan las propiedades como parámetro, el cliente de FIRe se D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 16 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario encarga de buscar un fichero de nombre ‘client_config.properties’ en la ruta definida por una variable de sistema de nombre ‘fire.config.path’ o Parámetros: appId • Identificador de aplicación con el que debe autenticarse frente al componente central. o Lanza: es.gob.fire.client.ClientConfigFilesNotFoundException: Si no se han proporcionado las propiedades necesarias. 3.2.4.1.1. Backend Ejemplo de construcción del cliente en un Backend construido con Spring Boot. Utiliza la primera versión del constructor con las propiedades como parámetro: @Autowired @Lazy public FireService( ClientConfigProperties clientConfigProperties, AppConfigProperties appConfigProperties) { try { this.clientConfigProperties = clientConfigProperties; this.appConfigProperties = appConfigProperties; Properties properties = new Properties(); properties.setProperty("fireUrl", this.clientConfigProperties.getFireUrl()); properties.setProperty("javax.net.ssl.keyStore", this.clientConfigProperties.getKeyStore()); properties.setProperty( "javax.net.ssl.keyStorePassword", this.clientConfigProperties.getKeyStorePassword()); properties.setProperty( "javax.net.ssl.keyStoreType", this.clientConfigProperties.getKeyStoreType()); properties.setProperty( "javax.net.ssl.trustStore", this.clientConfigProperties.getTrustStore()); properties.setProperty( "javax.net.ssl.trustStorePassword", this.clientConfigProperties.getTrustStorePassword()); properties.setProperty( "javax.net.ssl.trustStoreType", this.clientConfigProperties.getTrustStoreType()); fireClient = new FireClient(this.appConfigProperties.getAppId(), properties); } catch (Exception e) { log.info( "No se ha podido cargar la configuración para FIRe. Falta algún parámetro necesario"); } } 3.2.4.1.2. FrontEnd En la parte Front no es necesario realizar la construcción del cliente. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 17 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 3.2.4.2. Firma de datos El API distribuido Java dispone de dos métodos de firma equivalentes. Estos métodos nos permiten enviar a firmar datos indicando la configuración de firma a aplicar mediante cadenas de texto (muy útil para usar campos obtenidos externamente a Java (como formularios Web) o en base a constantes enumeradas que nos permiten establecer los valores sin riesgo de error durante la codificación. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 18 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario Los métodos de firma que se incluyen en el API de FIRe son los siguientes: Firma a partir de enumerados public static SignOperationResult sign( String subjectId, HttpSignProcessConstants.SignatureOperation op, HttpSignProcessConstants.SignatureFormat ft, HttpSignProcessConstants.SignatureAlgorithm algth, Properties prop, byte[] d, Properties config ) throws java.io.IOException, es.gob.fire.client.HttpNetworkException, es.gob.fire.client.HttpForbiddenException, es.gob.fire.client.HttpOperationException Inicia una operación de firma proporcionando los datos a firmar y la configuración de firma que debe aplicarse. • Parámetros: o subjectId: Identificador del titular de los certificados. o op: Tipo de operación a realizar (firma, cofirma o contrafirma). o ft: Formato de firma. o algth: Algoritmo de firma. o prop: Propiedades extra a añadir a la firma (puede ser null). o d: Datos a firmar. o config: Configuración a indicar al servicio remoto. Su uso depende de la implementación del conector que utilice el componente centralizado. • Retorno: o Objeto con el identificador de transacción y URL a la que re direccionar al usuario. • Lanza: o java.io.IOException: Si hay problemas en la llamada al servicio de red. o es.gob.fire.client.HttpForbiddenException: Cuando no se tiene acceso al servicio remoto. o es.gob.fire.client.HttpNetworkException: Cuando se produce un error de red. es.gob.fire.client.HttpOperationException: Si se produce un error en el servicio remoto. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 19 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario Firma a partir de cadenas de texto public static SignOperationResult sign( String subjectId, String op, String ft, String algth, String propB64, String dataB64, Properties config ) throws java.io.IOException, es.gob.fire.client.HttpForbiddenException, es.gob.fire.client.HttpNetworkException, es.gob.fire.client.HttpOperationException, Carga datos e inicia una operación de firma en el para ser posteriormente firmados. • Parámetros: o subjectId: Identificador del titular de los certificados. o op: Tipo de operación a realizar (firma, cofirma o contrafirma). o ft: Formato de firma. o algth: Algoritmo de firma. o propB64: Propiedades extra en base 64 que aplicar a la firma (puede ser null). o dataB64: Datos a firmar en base 64. o config: Configuración a indicar al servicio remoto. Su uso depende de la implementación del conector que utilice el componente centralizado. • Retorno: o Objeto con el identificador de transacción y URL a la que re direccionar al usuario. • Lanza: o java.io.IOException: Si hay problemas en la llamada al servicio de red. o es.gob.fire.client.HttpForbiddenException: Cuando no se tiene acceso al servicio remoto. o es.gob.fire.client.HttpNetworkException: Cuando se produce un error de red. o es.gob.fire.client.HttpOperationException: Si hay problemas con el servicio remoto. D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 20 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario 3.2.4.2.1. Backend Ejemplo de llamada a este método en un servicio REST construido con Spring Boot. Utiliza la versión que proporciona los parámetros como cadenas de texto: FireResource.java @Api( hidden = true, tags = {"Fire"}) @RestController @RequestMapping("/public/fire") @Slf4j public class FireResource { private static final HeadersBuilder R404 = ResponseEntity.notFound(); @Autowired private FireService srv; // *********** FIRMAR @ApiImplicitParams({ @ApiImplicitParam( name = "Authorization", value = "Authorization token", required = false, dataType = "string", paramType = "header") }) @Consumes({"multipart/form-data"}) @PostMapping("/sign") public ResponseEntity sign( @RequestParam(name = "subjectId", required = true) String subjectId, @RequestParam(name = "op", required = true) String op, @RequestParam(name = "ft", required = true) String ft, @RequestParam(name = "algth", required = true) String algth, @RequestParam(name = "extraParams", required = false) String extraParams, @RequestParam(value = "file") final MultipartFile file) { if (log.isDebugEnabled()) log.debug("Comienzo del metodo FireResource:sign"); return ofNullable(srv.sign(subjectId, op, ft, algth, extraParams, file)) .map(ResponseEntity::ok) .orElseGet(() -> R404.build()); } FireService.java /** * Devuelve un objeto con el identificador de la transaccion y la url del componente central a la * que redirigir, pasandole los parametros necesarios para realizar la firma * @param subjectId Identificador del titular de los certificados * @param op Tipo de operacion a realizar (firma, cofirma o contrafirma) * @param ft Formato de firma * @param algth Algoritmo de firma * @param extraParams Propiedades extra que aplicar a la firma (puede ser null) * @param file Datos a firmar en base 64 */ public SignOperationResult sign( String subjectId, D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 21 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario String op, String ft, String algth, String extraParams, MultipartFile file) { // Se crean las propiedades de la aplicacion cliente Properties confProperties = createAppConfig(); // Se codifica en Bae64 el parametro extraParams String extraParamsB64 = !StringUtils.isEmpty(extraParams) ? Base64.encode(extraParams.getBytes(), true) : null; // Utilizamos el cliente distribuido para solicitar la operacion de firma SignOperationResult signResult; try { signResult = fireClient.sign( subjectId, op, ft, algth, extraParamsB64, Base64.encode(file.getBytes(), true), confProperties); } catch (HttpForbiddenException e) { log.error("No se tiene acceso al servicio remoto", e); // $NON-NLS-1$ return null; } catch (HttpNetworkException e) { log.error("Se ha producido un error de red", e); // $NON-NLS-1$ return null; } catch (HttpOperationException e) { log.error("Se ha producido un error en el servicio remoto", e); // $NON-NLS-1$ return null; } catch (IOException e) { log.error("Hay problemas en la llamada al servicio de red", e); // $NON-NLS-1$ return null; } catch (Exception e) { log.error("Error general durante la operacion de firma", e); // $NON-NLS-1$; return null; } return signResult; } 3.2.4.2.2. FrontEnd firma.component.ts (no está la implementación completa, solamente lo relativo a la llamada a sign) import { Component, EventEmitter, Input, OnChanges, OnDestroy, OnInit, Output, Simple Changes } from '@angular/core'; import { FormBuilder, FormGroup, Validators } from '@angular/forms'; import { Subscription } from 'rxjs'; import { Firma } from './Firma'; import { FirmaService } from './firma.service'; import { SignOperationResult } from './SignOperationResult'; import { TransactionResult } from './TransactionResult'; D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 22 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario import { ActivatedRoute } from '@angular/router'; import { AlertException, DefaultException, CriticalException, Exception } from 'src/app/common/exception/Excepti on'; import { ExceptionService } from '../exception/exception.service'; import { environment } from 'src/environments/environment'; import { AuthService } from '../../project/auth/auth.service'; import { SweetAlertService } from 'src/app/ui/sweet‐alert/sweet‐alert.service'; @Component({ selector: 'pas‐firma', templateUrl: './firma.component.html', styleUrls: ['./firma.component.scss'] }) export class FirmaComponent implements OnInit, OnChanges, OnDestroy { constructor( private activatedRoute: ActivatedRoute, public firmaService: FirmaService, public fb: FormBuilder, private exceptionService: ExceptionService, private authService: AuthService, private sweetAlertService: SweetAlertService ) { this.firmaDataForm = this.fb.group({ subjectId: [''], operacion: ['', Validators.required], algoritmo: ['', Validators.required], formato: ['', Validators.required], upgrade: ['', Validators.required], extraParams: ['mode=implicit\nfilters=keyusage.nonrepudiation:true'], file: [''] }); } sign() { if (this.firmaDataForm.valid) { // Guardamos los datos de la firma en sesion this.setFirma(); if (this.firma.file !== undefined || this.nombreFichero !== undefined) { // Se llama al servicio de firma D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 23 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario const formData = new FormData(); formData.append('subjectId', this.currentFirma.subjectId); formData.append('op', this.currentFirma.operacion.id); formData.append('algth', this.currentFirma.algoritmo.id); formData.append('ft', this.currentFirma.formato.id); formData.append('extraParams', this.currentFirma.extraParams); formData.append('file', this.currentFirma.file); this.firmaService.sign(formData).subscribe(signOperationResult => { this.signOperationResult.transactionId = signOperationResult.transactionId; this.signOperationResult.redirectUrl = signOperationResult.redirectUrl; // Se guarda en localStorage el transactionId para posteriormente saber de donde recuperar la firma localStorage.setItem('transactionId', this.signOperationResult.transactionId); // Se redirige a FIRe para realizar la firma window.location.href = this.signOperationResult.redirectUrl; }, err => { const excepcionContenedora = new AlertException(DefaultException.fromState(err.status)); excepcionContenedora.add(new CriticalException(err.error)); this.exception = new Exception(excepcionContenedora); this.exceptionService.save(this.exception); }); } else { this.sweetAlertService.showError('', 'Debes añadir un fichero para firmar'); } } } } firma.service.ts (no está la implementación completa, solamente lo relativo a la llamada a sign) import { Injectable } from '@angular/core'; import { ApiService } from 'src/app/project/api/api.service'; import { environment } from 'src/environments/environment'; import { map } from 'rxjs/operators'; import { Observable } from 'rxjs'; @Injectable({ providedIn: 'root' }) export class FirmaService extends ApiService { D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 24 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario baseUrl = environment.api + '/public/fire/'; userId: string; op: string; ft: string; algth: string; propB64: string; dataB64: string; sign(formData: FormData): Observable { return this.http.post(this.baseUrl + 'sign', formData). pipe(map(items => items)); } } 3.2.4.3. Recuperación de firma Este método nos permite completar la construcción y actualización de la firma solicitada anteriormente y recuperar la propia firma y el proveedor de certificados utilizado. public static TransactionResult recoverSignResult( String transactionId, String subjectId, String upgrade ) throws java.io.IOException, es.gob.fire.client.HttpForbiddenException, es.gob.fire.client.HttpNetworkException, es.gob.fire.client.HttpOperationException, es.gob.fire.client.InvalidTransactionException Completa un proceso de firma haciendo uso del servicio de firma en la nube. • Parámetros: o transactionId: Identificador de la transacción. o subjectId: Identificador del titular de los certificados. o upgrade: Formato al que queremos mejorar la firma (puede ser null). D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 25 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario • Retorno: o Objeto TransactionResult con la firma electrónica generada y, si es posible, el nombre del proveedor de certificados seleccionado por el usuario. Si se seleccionó un certificado lo-cal, el nombre de proveedor será “local”. • Lanza: o java.io.IOException: Si hay problemas en la llamada al servicio de red. es.gob.fire.client.HttpForbiddenException: Cuando no se tiene acceso al servicio remoto. o es.gob.fire.client.HttpNetworkException: Si hay problemas en la llamada al servicio de red. o es.gob.fire.client.HttpOperationException: Si hay problemas con el servicio remoto. o es.gob.fire.client.InvalidTransactionException: Cuando la transacción no existe o está caducada. 3.2.4.3.1. Backend Ejemplo de llamada a este método en un servicio REST construido con Spring Boot. FireResource.java // *********** RECUPERAR FIRMA @ApiImplicitParams({ @ApiImplicitParam( name = "Authorization", value = "Authorization token", required = false, dataType = "string", paramType = "header") }) @PostMapping("/recoverSignResult") public ResponseEntity recoverSignResult( @RequestParam(name = "transactionId", required = true) String transactionId, @RequestParam(name = "subjectId", required = true) String subjectId, @RequestParam(name = "upgrade", required = false) String upgrade) { if (log.isDebugEnabled()) log.debug("Comienzo del metodo FireResource:recoverSignResult"); return ofNullable(srv.recoverSignResult(transactionId, subjectId, upgrade)) .map(ResponseEntity::ok) .orElseGet(() -> R404.build()); } FireService.java /** * Devuelve un objeto con la firma resultande de la operacion o, en caso de un error en el ultimo * momento, el error detectado. * * @param transactionId Identificador de la trasaccion obtenido como resultado del allamada a sign * @param subjectId Identificador del titular de los certificados D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
MANTENIMIENTO Proyecto APLICACIONES LOTE 1 Página 26 de 66 17-018 GOBIERNO DEL PRINCIPADO DE ASTURIAS Proceso Construcción Consejería de Empleo, Industria y Turismo Dirección General de Tecnologías de la Información y las Comunicaciones MDU Documento Manual de Usuario * @param upgrade Formato al que actualizar la firma electronica por medio de la Plataforma @firma */ public TransactionResult recoverSignResult( String transactionId, String subjectId, String upgrade) { if (log.isDebugEnabled()) log.debug("Comienzo del metodo FireService:recoverSignResult"); // FireClient fireClient = createFireClient(); // Utilizamos el cliente distribuido para obtener el resultado de la firma TransactionResult transactionResult; try { transactionResult = fireClient.recoverSignResult(transactionId, subjectId, upgrade); } catch (HttpForbiddenException e) { log.error( "El usuario no esta dado de alta o no tiene permisos para ejecutar la operacion", e); // $NON-NLS-1$ return null; } catch (HttpNetworkException e) { log.error("Se ha producido un error de red", e); // $NON-NLS-1$ return null; } catch (HttpOperationException e) { log.error("Hay problemas con el servicio remoto", e); // $NON-NLS-1$ return null; } catch (InvalidTransactionException e) { log.error("La transaccion no existe o esta caducada", e); // $NON-NLS-1$ return null; } catch (IOException e) { log.error("Hay problemas en la llamada al servicio de red", e); // $NON-NLS-1$ return null; } catch (Exception e) { log.error("Error durante la recuperación de del error de la firma", e); // $NON-NLS-1$ return null; } if (log.isDebugEnabled()) { log.debug("Resultado FireService:recoverSignResult"); log.debug("TransactionResult.errorCode: " + transactionResult.getErrorCode()); log.debug("TransactionResult.errorMessage: " + transactionResult.getErrorMessage()); log.debug("TransactionResult.providerName: " + transactionResult.getProviderName()); log.debug("TransactionResult.result: " + transactionResult.getResult()); log.debug("TransactionResult.resultType: " + transactionResult.getResultType()); log.debug("TransactionResult.state: " + transactionResult.getState()); } return transactionResult; } 3.2.4.3.2. Frontend firma.component.ts (no está la implementación completa, solamente lo relativo a la llamada a recoverSignResult) import { Component, EventEmitter, Input, OnChanges, OnDestroy, OnInit, Output, SimpleChanges } from '@angular/co re'; import { FormBuilder, FormGroup, Validators } from '@angular/forms'; import { Subscription } from 'rxjs'; D. G. de Tecnologías de la Información y 17-018-01-MDU-FIRE-2021/07/05-v1 10/05/2021 las Comunicaciones
También puede leer