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:

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.

-

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á:

-

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:

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:

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:

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:

Ejemplo de altas en MFE - firma client (estos datos estarán volcados en al excel de alta )

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:

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" />