4.- Integración con MFE
INDICE DEL CONTENIDO
1. MFE - Módulo de identificación
En este apartado se va a indicar cómo una aplicación debe integrarse con MFE para utlizar su funcionalidad de identificación
1.1 Requisitos Previos
Para comenzar a utlizar MFE – Módulo de Identificación son necesarios los siguientes pasos.
1.1.1.- Configuración de identificación en MFE.
Para poder integrarse con el Modulo de Firma Electrónica la aplicación debe estar dada de alta en MFE con un código de aplicación y nombre de aplicación y la configuración que se le quiere dar a la aplicación para la identificación de usuarios:
Configuración general de identificación:
Métodos de identificación: se deben de indicar los métodos o tipos de identificación que se requiera que aparezcan al usuario y qué configuración se le desea dar a cada uno. Estos son los métodos de identificación que actualmente tiene MFE: Cl@ve · Nivel de calidad de autentificación (QAA): Nivel de calidad que debe pasar la autenticación con el método elegido. Puede tener cuatro valores que corresponden con los siguientes cuatro niveles: ▪ Nivel 1: No hay ninguna, o hay una confianza mínima, en la identidad alegada. Las credenciales de identidad se aceptan sin ningún tipo de verificación. ▪ Nivel 2: Hay una validación de que las identidades corresponden a personas reales, y los tokens de identificación se entregan con ciertas garantías ▪ Nivel 3: (Por defecto) El registro de la identidad se realiza con métodos que proporcionan una alta certeza sobre la identidad de la persona que la declara, y las credenciales electrónicas son robustas. ▪ Nivel 4: Se requiere un registro presencial al menos una vez, y la credencial electrónica se entrega como certificado hardware criptográfico. · Métodos de validación del certificado : Cl@ve denomina "método de validación del certificado" a los sub-tipos de identificación que su plataforma ofrece a los usuarios para la identitifcación. Se pueden seleccionar varios dando al usuario varias opciones de identificación. ▪ aFirma: (Por defecto): Método de identificación donde al usuario se le muestran los certificados electrónicos de su navegador (o tarjeta criptográfica) para identificarse. Internamente clave valida éste certificado contra @firma. ▪ AEAT - Cl@vePin: Método de identificación donde el usuario para su identificación introduce un pin de corta duración proporcionado por la Agencia Tributaria. ▪ SS - Cl@vePermante: Método de identificación donde el usuario para su identificación introduce un pin de corta duración proporcionado por la Seguridad Social. ▪ Stork - Ciudadano de la Unión Europea: Validación del certificado mediante el sistema STORK. STORK es un proyecto europeo para homogeneizar el acceso a las distintas administraciones europeas SSLogin |
1.1.2 Permisos en PAU para invocar al método de MFE.
Durante el proceso de identificación, una vez que el usuario ha realizada la identificación en el portal, la aplicación integradora debe validar en servidor el token jwt devuelto por MFE resultado de la identificación del usuario.
Para ello la aplicación integradora deberá tener permisos en la “Plataforma de Autorización de Usuarios y aplicaciones“ (PAU) para invocar al método ''validateJwt' del servicio “IdentificationValidationServices” de la aplicación MFE.
En el caso de que la aplicación integradora desee realizar la validación del token JWT generado sin la necesidad de invocar a MFE, es necesario que posea permisos en PAU para invocar al método "getJwtCertificatePublicKey" del servicio "IdentificationValidationServices" de la aplicación MFE. Esto permite a la aplicación integradora la descarga de la clave pública del certificado utilizado para la firma del token JWT con la que podrá realizar su validación
Si la aplicación integradora desea hacer tener la posibilidad de obtener una nueva pareja de tokens JWT, acceso y refresco, deberá tener permisos para invocar al método "refreshToken" del servicio "IdentificationValidationServices" de la aplicación MFE
1.2 Integración de la aplicación
Para integrar una aplicación con la identificación del MFE debe realizar los siguientes pasos en la página de login.
1.2.1 Etiqueta compatibilidad Internet Explorer
Internet Explorer 11 soporta diferente modos de compatibilidad de documentos que habilitan o inhabilitan diferentes características y puede afectar al funcionamiento. Para evitar que cambie la versión si el usuario
tiene activado el modo compatibilidad, se debe incrustar el siguiente metadato en la cabecera de la página.
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
1.2.2 Archivos javascript
Se debe incluir los archivos javascript donde está parte de la lógica necesaria para realizar la identificación.
<script type="text/javascript" src="http://[URL_SERV]/mfe_core/js/sslssso.js"></script>
1.2.3 Iframe para incrustar los métodos de identificación
Incrustar el iframe donde aparecerán los métodos de identificación ofrecidos al usuario. Es muy importante que su identificador sea ”mfe_iframe”.
Este iframe llamará a un servicio REST de MFE donde se tendrá que indicar como parte del recurso los siguientes parámetros:
-APPLICATION_ID
Identificador con el que la aplicación se ha dado de alta en MFE
-APPLICATION_URL_REDIRECT
Url de login del propio portal codificada en Base64.
Una vez gestionada la identificación en la plataforma que proceda, se volverá a la url de inicio del portal
El resultado debería ser como el siguiente:
<iframe id="mfe_iframe" src="http://[URL_SERV]/mfe_core/rest/identification/[APPLICATION_ID]/[APPLICATION_URL_REDIRECT]"> </iframe>
Iframe con estilos DESY
Las medidas recomendadas del iframe con estilos DESY son las siguientes:
Anchura: 1024px para que se visualice el spinner de las pantallas de carga correctamente
Altura:
Si la aplicación tiene únicamente un método de identificación se recomienda una altura de 520 px.
Si la aplicación tiene varios métodos de identificación se recomienda una altura de 630px.
Además de estas medidas, si se desea que el iframe se redimensione automáticamente según su contenido una vez cargado, se debe incluir en la cabecera de la página padre lo siguiente.
<script src="https://cdnjs.cloudflare.com/ajax/libs/iframe-resizer/4.3.2/iframeResizer.contentWindow.min.js" integrity="sha512-14SY6teTzhrLWeL55Q4uCyxr6GQOxF3pEoMxo2mBxXwPRikdMtzKMYWy2B5Lqjr6PHHoGOxZgPaxUYKQrSmu0A==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
Esto supondrá que el iframe cambie de altura automáticamente para que se pueda visualizar correctamente el contenido si éste supera la altura por defecto del iframe.
1.2.4 Método javascript 'onIdentification'
Crear la función 'onIdentification' para recibir el token de identificación JWT. Esta función no necesita ser invocada desde ninguna parte del código. De forma transparente para el integrador, será llamada por MFE
cuando detecte que un usuario se ha identificado.
function onIdentification(operation) { // Token jwt de identificación operation.jwt; // Token de refresco jwt (en caso de tener habilitado el tipo JWT "JWT titular/certificado/puesto") operation.refreshJwt; }
-
En este momento tenemos un usuario identificado y el portal continuará con la lógica de negocio comunicándose con la parte servidor haciéndole llegar el token jwt.
-
1.2.5 Validación del token jwt
Para obtener los datos de identificación del usuario, se debe validar este jwt contra un servicio REST (POST) de MFE. De esta forma la aplicación asegura la procedencia de la identificación.
URL | PARAMETRO |
---|---|
http://[URL_SERV]/mfe_core/rest/identificationValidation/[APPLICATION_ID]?jwt=__JWT__ | Parámetro jwt (token jwt de la identificación) |
-
Como respuesta de la validación devolverá un json con los siguientes datos:
En el caso que la aplicación esté configurada para hacer uso del JWT Titular/Certificado, además de los campos anteriores el JSON incluirá:
En el caso que la aplicación esté configurada para hacer uso del JWT titular/certificado/puesto, incluirá los campos del JWT titular y JWT titular/certificado y además, incluirá unos campos extra que son los siguientes:
IMPORTANTE
En el momento en que MFE invoca al método 'onIdentification' (punto 4) el usuario ya tiene su identificación SSO aunque, en caso de una identificación incorrecta, el portal no le diese acceso.
En el tratamiento de los diversos estados de la validación del token jwt que requieran volver a identificarse (ERROR y NOT_VALID, NOT_VALID_SSO) se deberá invocar al cierre de sesión o
logout (explicado en el siguiente punto) para eliminar su identificación del SSO.
También es importante realizar un correcto tratamiento de posibles errores durante el proceso de “login” dentro del portal, para que ante un posible error que vuelva a la página de inicio se realice un cierre de sesión o logout del usuario para que éste pueda volver a identificarse.
-
1.2.6 Cierre de sesión (logout)
La identificación con MFE tiene implementado un sistema de autenticación única (SSO - Single Sign On) es decir, habilita al usuario para acceder a todos los sistemas integrados con MFE con una sola instancia de identificación.
Este sistema tiene una duración determinada y persiste en el navegador durante este tiempo. Por ello es importante implementar en el portal donde se haya identificado el usuario un cierre de sesión adecuado.
Para ello bastaría con incluir en la lógica de negocio de cierre de sesión implementada en la aplicación, una invocación a un servicio REST (GET) de MFE indicando en el recurso de la url los siguientes parámetros:
· APPLICATION_ID: Identificador con el que la aplicación se ha dado de alta en MFE.
· URL_LOGIN_APLICACION_B64: url de login del propio portal codificada en Base64. Una vez terminado el logout en MFE, redireccionará a esta url.
· IDENTIFICATION_METHOD_ID: Método con el que se identificó el usuario. (devuelto en el json de identificación
NOTA: en el punto "5.- casos de uso de ejemplo", tiene un ejemplo de integración de MFE - Identificación en un portal del empleado.
1.2.7 Obtención de clave pública del certificado que firma jwt
Para obtener la clave pública del certificado que firma los token jwt, se debe invocar a un servicio REST (GET) de MFE. Se debe indicar el id de aplicación con el que la aplicación se ha dado de alta en MFE por motivos de seguridad.
La url de invocación es la siguiente:
http://[URL_SERV]/mfe_core/rest/identificationValidation/[APPLICATION_ID]
Los parámetros a rellenar en la url son los siguientes:
- URL_SERV: URL del servidor al cual se va a invocar
APPLICATION_ID: Identificador con el que la aplicación se ha dado de alta en MFE
Como respuesta se devolverá un json con los siguientes datos:
CAMPO | DESCRIPCIÓN | POSIBLES VALORES |
---|---|---|
value | Valor de la clave pública del certificado en base64. Importante: No es el .cer, es la clave pública del .cer | |
httpStatusCode (solamente si se produce un error) | Código de estado de respuesta HTTP |
|
errorMessage (solamente si se produce un error) | Mensaje del error | |
errorCode (solamente si se produce un error) | Código del error | |
alg | Algoritmo de la clave pública del certificado |
A continuación, se indican unos ejemplos de respuesta json:
Respuesta correcta:
Respuesta errónea por identificador de aplicación incorrecto:
Respuesta errónea por identificador de aplicación vacío:
Respuesta errónea por error interno al intentar obtener la clave pública del certificado:
1.2.7 Renovar token JWT
Para renovar el token JWT, se debe invocar a un servicio REST (POST) de MFE. Se debe indicar el id de aplicación con el que la aplicación se ha dado de alta en MFE por motivos de seguridad y el token JWT de refresco que se había obtenido en una identificación.
La url de invocación es la siguiente:
http://[URL_SERV]/mfe_core/rest/identificationValidation/[APPLICATION_ID]/refreshToken
Los parámetros a rellenar en la url son los siguientes:
URL_SERV: URL del servidor al cual se va a invocar
APPLICATION_ID: Identificador con el que la aplicación se ha dado de alta en MFE
En el body de la petición, se debe rellenar un json con el token de refresco (refreshToken). El json debe tener la siguiente estructura:
{ "refreshToken": "VALOR_TOKEN" }
Como respuesta se devolverá un json con los siguientes datos:
CAMPO | DESCRIPCIÓN | POSIBLES VALORES |
---|---|---|
httpStatusCode | Código de estado de respuesta HTTP |
|
accessToken | Token de acceso | |
refreshToken | Token de refresco | |
errorCode (solamente si se produce un error) | Código del error | Tendrá un tiempo de caducidad mayor al token de acceso |
errorMessage (solamente si se produce un error) | Mensaje del error |
A continuación, se indican unos ejemplos de respuesta json.
Respuesta correcta:
Respuesta errónea por identificador de aplicación incorrecto:
Respuesta errónea por identificación de aplicación vacío:
Respuesta errónea por token no válido:
Respuesta errónea por un error interno inesperado:
1.2.8 Cambio de organismo JWT
Para cambiar de organismo renovando el token JWT, se debe invocar a un servicio REST (POST) de MFE. Se debe indicar el id de aplicación con el que la aplicación se ha dado de alta en MFE, el token JWT de refresco que se había obtenido en una identificación anterior y el código de organismo al cual se desea cambiar.
La url de invocación es la siguiente:
http://[URL_SERV]/mfe_core/rest/identificationValidation/[APPLICATION_ID]/changeOrganism
Los parámetros a rellenar en la url son los siguientes:
URL_SERV: URL del servidor al cual se va a invocar
APPLICATION_ID: Identificador con el que la aplicación se ha dado de alta en MFE
En el body de la petición, se debe rellenar un json con el token de refresco (refreshToken) y el código de organismo al que se quiere cambiar (organismCode). El json debe tener la siguiente estructura:
{ "refreshToken": "VALOR_TOKEN" "organismCode": "CODIGO_ORGANISMO" }
Como respuesta se obtendrá un json con los siguientes datos:
CAMPO | DESCRIPCIÓN | POSIBLES VALORES |
---|---|---|
httpStatusCode | Código de estado de respuesta HTTP |
|
accessToken | Token de acceso | |
refreshToken | Token de refresco. Tendrá un tiempo de caducidad mayor al token de acceso | |
errorCode (solamente si se produce un error) | Código del error | |
errorMessage (solamente si se produce un error) | Mensaje del error |
1.2.9 Uso de MFE en dominio cruzado ( Modalidad PRETOKEN )
Tras las últimas actualizaciones de seguridad en los navegadores modernos ( Octubre - 2023 ), el método de identificación ya no es compatible con aplicaciones integradoras que no están alojadas bajo el dominio de aragon.es.
Para estos casos se ha implementado lo modalidad con pretoken como medida temporal ( esta modalidad se puede solicitar activar o desactivar ), mientras se trabaja en una solución definitiva.
El uso de esta modalidad no implica cambios en la integración, solo solicitar su activación en el portal de Administración de MFE.
2. MFE - Módulo de Firma Cliente
En este apartado se va a indicar cómo una aplicación debe integrarse con MFE para utlizar su funcionalidad de firma cliente
2.1 Requisitos Previos
Para comenzar a utlizar MFE – Módulo de firma son necesarios los siguientes pasos.
2.1.1.- Configuración de firma en MFE.
Para poder integrarse con el Modulo de Firma Electrónica la aplicación debe estar dada de alta en MFE con un código de aplicación y nombre de aplicación y la configuración que se le quiere dar a la aplicación para la firma. El concepto de MFE es que toda la configuración de firma esté en el propio MFE, de forma que las aplicaciones integradoras se abstraigan de ésto. Para ello las aplicaciones integradoras utilizan operaciones de firma y solicitan su alta y configuración en MFE. A la hora de integrarse (como se explicará más adelante) las aplicaciones utilizan estas operaciones ya configuradas para firmar documentos.
Los datos que se deben de proporcionar para la configuración de la aplicación en MFE son:
Por cada tipo de firma que se desee realizar: Operación de firma 1:
◦ Firma simple (por defecto): se realiza una sola firma sobre un documento. ◦ Multi-firma en paralelo: Se añadirá una nueva firma a un documento que ya contiene una firma previa. Esta firma será paralela, es decir, se firma solo el documento original y no el conjunto del documento y la firma anterior. ◦ Firma en bloque: se envían varios documentos a firmar en una sola vez. Conceptualmente esta firma es un conjunto de firmas simples o paralelas así que no se indicará ninguna propiedad de firma (formato de firma, algoritmo y modo) solo el componente. ◦ Firma en cascada: Se añadirá una nueva firma a un documento que ya contiene una firma previa. Esta firma será en cascada, es decir, se firma solo el conjunto del documento y las firma anteriores.
CadES-BES ◦ Enveloped ◦ Detached XadES-BES ◦ Enveloping FacturaE (conforme a la especificación 3.1 del estándar) ◦ Enveloped PAdES-Básico ◦ Enveloped PadES-BES ◦ Enveloped Modo de firma: indica cómo se guardará la firma: ◦ Detached: El documento y su firma están separados, en ficheros distintos. Importante, para estas firmas se enviará a firmar solo el resumen hash del documento en vez de el documento completo. ◦ Enveloped: El documento final incluye el documento original y su firma electrónica. Algoritmo de firma: Algoritmo que se utilizará para generar la firma electrónica. ◦ SHA1withRSA Filtrado de certificados por usuario identificado. Dentro de los certificados que se le mostrarán al usuario para la firma, se podrán filtrar para que muestre solo aquellos que pertenezcan al usuario identificado. Los valores son: ◦ NO (por defecto): al usuario se le mostrarán todos los certificados que tenga instalados en su navegador para poder firmar. La aplicación integradora tendrá dos modos para proporcionar a MFE el identificador del usuario a filtrar: usuario identificado mediante MFE o filtrado por un usuario distinto al identificado en el login. Ésto depende de la integración realizada y se explicarán en el apartado 3.2 Integración de la aplicación - Filtrado de certificados del navegador o firma mediante Cl@veFirma. Componente de firma: métodos para firmar que se le proporcionará al usuario para que firme. Se puede y recomendamos, seleccionar más de uno. Componente @firma utiliza los certificados locales a la hora de firmar. Para poder firmar de esta manera será necesario el uso de AutoFirm@, una aplicación nativa que el usuario deberá tener instalada en el sistema (http://firmaelectronica.gob.es/Home/Descargas.html ).
|
Ejemplo de altas en MFE - firma client (estos datos estarán volcados en al excel de alta )
Código de aplicación: SNT Nombre de aplicación: Sistema de Notificaciones Telefónicas. Dominio: https://aplicaciones.aragon.es Operación 1 Nombre: 'firmaCades' Tipo de operación de firma: simple Formato firma: CAdES-BES Modo firma: Detached Algoritmo: SHA1withRSA Fltrado de certifados: NO Componte: Cliente @firma y Cl@ve Firma Operación 2 Nombre: 'firmaJusficanteXades' Tipo de operación de firma: simple Formato firma: XAdES-BES Modo firma: Enveloping Algoritmo: SHA1withRSA Filtrado de certifados: SI Componte: Cliente @firma y Cl@ve Firma Operación 3 Nombre: 'firmaMasivaNotificaciones' Tipo de operación de firma: firma en bloque Filtrado de certifados: NO Componte: Cliente @firma. |
2.2.- Integración de la aplicación
2.2.1.- Firma simple o multi-firma (en paralelo o en cascada).
Para realizar firma cliente simple o multi-firma en paralelo con MFE se debe implementar los siguientes pasos en la página de firma de la aplicación:
1) Etiqueta para compatibilidad con Windows 8 y superiores
El Cliente @firma no es compatible con Internet Explorer 10 y superiores en su versión “Metro” y debe ser ejecutado con la versión de escritorio de Internet Explorer. Para automatizar en cierta manera el cambio de Internet Explorer desde Metro hasta el escritorio clásico de Windows 8 se debe incluir la siguiente meta-información en la cabecera de la página.
<meta http-equiv="X-UA-Compatible" content="requiresActiveX=true"/>
-
2) Archivos javascript de firma
Se debe incluir los archivos javascript donde incluye parte de la lógica necesaria para realizar la identificación.
<script type="text/javascript" src="http://[URL_SERV]/mfe_core/js/mfe_clientSignature.js"></script>
-
3) Iframe para incrustar los métodos de firma
Incrustar el iframe donde aparecerán los componentes de firma ofrecidos al usuario. Es muy importante que su identificador sea ”mfeClientSignatureIframe” . Este iframe llamará a un servicio REST de MFE donde se tendrá que indicar como parte del recurso los siguientes parámetros:
· APPLICATION_ID: Identificador con el que la aplicación se ha dado de alta en MFE.
· OPERATION_NAME: operación de firma que se va a realizar
<iframe id="mfeClientSignatureIframe" src="[http://..URL_SERV]/mfe_core/rest/clientSignature/[APPLICATION_ID]/[OPERATION_NAME]"> </iframe>
-
4) Etiqueta con los datos a firmar
4.1) FIRMAS SIMPLES
Incrustar etiqueta con identificador “mfeDataToSign” con los datos a firmar
<input type="hidden" id="mfeDataToSign" value="JVBERi0xLjcKjp2jtMXW5/gKMiAw0Jhc2...">
A) Firma en modo detached. Los datos a firmar serán el resumen hash en base64 del documento, utilizando el mismo algoritmo que se indicó en la configuración de la firma. Es decir, si se indicó que la firma se realizase con SHA1withRSA, el hash debe estar calculado utilizando SHA1
B) Firma en modo enveloping/enveloped. Los datos a firmar serán el documento completo codificado en base64.
4.2) MULTI-FIRMAS
En caso de realizarse multi-firmas, además de los datos originales a firmar se debe indicar la firma previa realizada en otra etiqueta con identificador “mfeSignature”. Esta etiqueta tendrá los datos de la firma en base64 a la cual se añadirá la nueva firma a realizada.
<input type="hidden" id="mfeDataToSign" value="JVBERi0xLjcKjp2jtMXW5/gKMiAw0MgXQp..."> <input type="hidden" id="mfeSignature" value="MIIXZgYJKoZIhvcNAQcCoIIXVzCCF1NVzCC...">
5) firma mediante Cl@veFirma o filtrado de certificados del navegador con Cliente @firma
Tanto para filtrar los certificados del navegador como para realizar la firma mediante Cl@veFirma, se le debe indicar a MFE el identificador del usuario a firmar. Hay dos formas de proporcionar dicho identificador de usuario:
A) Usuario identificado mediante MFE. Si el portal está utilizando la identificación mediante MFE para realizar el login, MFE detectará el usuario identificado y filtrará por éste. En este caso el integrador no debe realizar ninguna implementación extra.
B) Usuario no identificado mediante MFE. Si el firmante es otro usuario distinto al identificado o el portal no realiza identificación mediante MFE, se le indicará el idUser mediante un tag cuyo identificador sea “mfeIdUser”. Dicho tag debe quedar fuera del <iframe> tal y como se indica en el apartado 3.3.2 Multifirma paralela Cades-Bes y filtrado de usuario (distinto al identificado en el sistema)
<input type="hidden" id="mfeIdUser" value="99999999R" />
-
6) Método javascript 'signatureSuccess'
Crear la función 'signatureSucess' para recibir la firma en base64. Esta función no necesita ser invocada desde ninguna parte del código, de forma transparente para el integrador será llamada por MFE cuando la firma haya terminado.
function signatureSuccess(signatureB64) { console.log("[APP] signatureSuccess!!"); // Firma del documento en base64 signatureB64 }
-
7) Método javascript 'signatureError'
Crear la función 'signatureError' para recoger el error en caso de que haya sucedido algún problema durante la firma. Esta función no necesita ser invocada desde ninguna parte del código, de forma transparente para el integrador si sucede algún problema durante la firma, MFE invocará a esta función en vez de a 'signatureSuccess'.
function signatureSuccess(signatureB64) { console.log("[APP] signatureSuccess!!"); // Firma del documento en base64 signatureB64 } function signatureError(type, message) { // Mensaje y tipo de error sucedido durante la firma. console.error("[APP] signatureError. Message: " + message + ", type: " + type); }
-
2.2.2 Firma en bloque de varios documentos.
La firma en bloque es una sucesión de firmas de varios documentos donde el usuario firmará todos de vez y donde cada documento puede tener unas propiedades de firma distintas.
Para realizar este tipo de firma se debe tener configurado en MFE una operación de tipo firma en bloque y tantas operaciones de firma simple o multifirma por cada tipo de firma que se desee realizar.
Por ejemplo, para una firma en bloque donde el usuario (y solo el usuario identificado) firmaría de vez dos documentos en cades-detached uno cades-detached multi-firma paralela y un facturae tendríamos que tener configurado en MFE:
Operación “firmaBloque” de tipo firma en bloque con Cliente @Firma.y con filtro de certificados
Operaciones que ya utilizábamos previamente para firmar los documentos de uno en uno y necesitaremos para la firma en bloque:
Operación “firma_cades_detached” (firma simple, cades-bes, detached, SHA1withRSA, componentes: Cliente @firma y Cl@veFirma y filtro de certificados)
Operación “firma_facturae” (firma simple, facturae, enveloped, SHA1withRSA, componentes: Cl@veFirma y NO filtro de certificados)
Operación “firma_cades_multisigns” (multi-firma paralela, cades, detached, SHA1withRSA, componentes: Cl@veFirma y NO filtro de certificados)
Las propiedades de la firma en bloque de componentes de firma y filtro de certificados, se antepone a la configuración de las firmas simples. Para realizar firma en bloque de varios documentos con MFE se deben implementar los siguientes pasos en la página de firma:
1) Etiqueta para compatibilidad con Windows 8 y superiores
El Cliente @firma no es compatible con Internet Explorer 10 y superiores en su versión “Metro” y debe ser ejecutado con la versión de escritorio de Internet Explorer. Para automatizar en cierta manera el cambio de Internet Explorer desde Metro hasta el escritorio clásico de Windows 8 se debe incluir la siguiente meta-información en la cabecera de la página.
<meta http-equiv="X-UA-Compatible" content="requiresActiveX=true"/>
-
2) Archivos javascript de firma
Se debe incluir los archivos javascript donde incluye parte de la lógica necesaria para realizar la identificación.
<script type="text/javascript" src="http://[URL_SERV]/mfe_core/js/mfe_clientSignature.js"></script>
-
3) Iframe para incrustar los métodos / componentes de firma
Incrustar el iframe donde aparecerán los métodos de firma ofrecidos al usuario. Es muy importante que su identificador sea ”mfeClientSignatureIframe” . Este iframe llamará a un servicio REST de MFE donde se tendrá que indicar como parte del recurso los siguientes parámetros:
APPLICATION_ID: Identificador con el que la aplicación se ha dado de alta en MFE.
OPERATION_BLOCK_NAME: nombre de la operación en bloque que se va a realizar.
-
<iframe id="mfeClientSignatureIframe" src="[http://..URL_SERV]/mfe_core/rest/clientSignatureBlock/[APPLICATION_ID]/[OPERATION_NAME]"> </iframe>
-
4) Etiqueta con los datos a firmar
Incrustar etiqueta con identificador “mfeDataToSign” con los datos a firmar.
<input type="hidden" id="mfeDataToSign" value="jsonDatosAFirmar">
-
Como datos a firmar se enviará un json indicando las siguientes propiedades para cada documento a firmar:
internalId: Identificador del documento para el integrador. Tiene que ser una cadena ANSI con una longitud máxima de 80 carácteres.
operationName: operación simple o multi-firma que se realizará sobre el documento. Esta operación debe estar dada de alta en MFE para la aplicación integradora.
dataToSign: documento a firmar en base64. En caso de realizarse firma detached, debe ser el hash del documento (mismo algoritmo que en la firma) en base64.
signature: en caso de realizar multi-firma en paralelo, indicar la firma en base64 donde se añadirá esta nueva firma.
-
[ { "internalId": "1111", "operationName": "firma_cades_detached", "dataToSign": "LQkAAVILmHgrbNYyAFy0/J/bbqvqel5/d1Ima5rfS3Z23AnB1PcMlIS3gp4jhmQe7g==(...)" }, { "internalId": "2222", "operationName": "firma_facturae", "dataToSign": "PDdmVyc2lvbj0iMS4wIiBZGluZz0iVVRGLTgiPz4KPGZlOkZhY3R1cmFlIHhtbG5SJodH(...)" }, { "internalId": "3333", "operationName": "firma_cades_multiSign", "dataToSign": "zwCo4E2x4YxGLQkt7t7iWsCxVILmHgrbNYyAFy0/J/bbqvqel5/id1Ima5rfS3(...)", "signature": "MIIXZgYJKoZIhvcNAQcCoIIXVzCCF1MCAQExDzANBglghkgBZQMEAgMFADALBgkqhkiG0B(...)" } ]
-
5) Filtrado de certificados del navegador
Para filtrar los certificados del navegador al firmar mediante el Cliente @Firma (la firma en bloque no está permitida con Cl@veFirma) se le debe proporcionar a MFE el identificador del usuario a firmar. Al igual que para las firmas simples o multi-firmas, hay dos formas de proporcionar dicho identificador de usuario:
A) Usuario identificado mediante MFE. Si el portal está utilizando la identificación mediante MFE para
realizar el login, MFE detectará el usuario identificado y filtrará por éste. En este caso el integrador no
debe realizar ninguna implementación extra.
B) Usuario no identificado mediante MFE. Si el firmante es otro usuario distinto al identificado o el
portal no realiza identificación mediante MFE, se le indicará el idUser mediante un tag cuyo identificador
sea “mfeIdUser”. Dicho tag debe quedar fuera del <iframe> tal y como se indica en el apartado 3.3.2 Multifirma paralela Cades-Bes y filtrado de usuario (distinto al identificado en el sistema)
<input type="hidden" id="mfeIdUser" value="99999999R" />
-
6) Método javascript 'signatureSuccess'
Crear la función 'signatureSucess' para recibir el resultado de las firmas. Esta función no necesita ser invocada desde ninguna parte del código, de forma transparente para el integrador será llamada por MFE cuando la firma haya terminado. El resultado es un json donde por cada documento se indican los siguientes datos:
internalId: Identificador del documento para el integrador.
status: (SUCCESS | ERROR). Indica si la firma se ha realizado correctamente o no.
errorMensaje. En caso de error, mensaje informativo del error.
signatureB64: en caso firma correcta, resultado de la firma en base64.
function signatureSuccess(signatureBlockResult){ console.log("[APP] signatureSuccess"); // Firma del documento en base64 signatureBlockResult[index].internalId signatureBlockResult[index].status signatureBlockResult[index].errorMessage signatureBlockResult[index].signatureB64 }
-
7) Método javascript 'signatureError'
Crear la función 'signatureError' para recoger el error en caso de que haya sucedido algún problema durante la firma y no se haya podido ni comenzar con el proceso. Esta función no necesita ser invocada desde ninguna parte del código, de forma transparente para el integrador si sucede algún problema durante la
firma, MFE invocará a esta función en vez de a 'signatureSuccess'.
function signatureError(type, message) { // Mensaje y tipo de error sucedido durante la firma. console.error("[APP] signatureError. Message: " + message + ", type: " + type); }
2.3.- Integración de la aplicación sin IFRAME
Es posible realizar la integración con MFE sin el iframe utilizando las mismas etiquetas y funciones de recogida de resultados ya descritos. Para ello será necesario seguir los siguientes pasos:
Se debe incluir en la cabecera de la página el script que incluye la parte de la lógica necesaria para realizar la firma ( sustituye al script mfe_clientSignature.js )
<script type="text/javascript" src="http://[URL_SERV]/mfe_core/js/mfe_signature.js"></script>
El elemento de integración que sustituye al IFRAME es un botón al cual el integrador podrá aplicar los estilos que crea oportunos. Para indicar los datos de la aplicación y la operación que se quiere realizar se utilizarán los siguientes campos:
Propiedad | Descripción | Valores aceptados |
---|---|---|
id | Identificador obligatorio del elemento | mfe_signature_button |
data-application | Identificador de la aplicación integradora | Lo elige el integrador al realizar el alta en MFE |
data-operation | Nombre de la operación que se realizará, esta operación debe estar dada de alta previamente en MFE | Lo elige el integrador al realizar el alta en MFE |
data-mode | Indica si la operación de firma será simple o en bloque | simple / block |
Ejemplo de una operación de firma simple:
<button id="mfe_signature_button" data-application="TEST_APPLICATION" data-operation="firma_cades_detached" data-mode="simple">Firmar Documento</button> // Datos a firmar <input type="hidden" id="mfeDataToSign" value="RG9jdW1lbnRvIGRlIHBydWViYSBkZSBmaXJtYSBlbGVjdHLDs25pY2E="> // Identificador del usuario que va a firmar <input type="hidden" id="mfeIdUser" value="99999999R" />
Ejemplo de una operación de firma en bloque:
<button id="mfe_signature_button" data-application="TEST_APPLICATION" data-operation="firmaBloque" data-mode="block">Firmar Documento</button> // Datos a firmar en bloque <input type="hidden" id="mfeDataToSign" value="jsonDatosAFirmar"> // Identificador del usuario que va a firmar <input type="hidden" id="mfeIdUser" value="99999999R" />