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:

 
  • Código de la aplicación:
  • Nombre de la aplicación:

Configuración general de identificación:

  • Habilitar representación: (SI/NO). Opción para que el usuario, además de poder acceder al portal en nombre  propio, pueda acceder mediante los apoderamientos y habilitaciones que tenga concedidas en el REA y actuar así en nombre de sus apoderados o habilitados.
  • Restringir certificados: (SI/NO). Se activa si para el acceso a la identificación mediante certificado electrónico, se desea restringir solo para un tipo de certificados. En caso de que se desee activar esta restricción se tendrán que indicar a qué tipo de certificados se les permite el acceso:
    • PHYSICAL_PERSON si el certificado usado es de una persona física.
    • JURIDIC_PERSON si el certificado usado es de una persona jurídica.
    • UNRECOGNIZED si el certificado usado no esta reconocido por la entidad validadora.
    • PUBLIC_EMPLOYEE si el certificado usado es de un empleado publico.
    • STAMP si el certificado usado es un certificado cualificado de sello.
    • WEBSITE si el certificado usado es de una sede electrónica.
    • WEBSITE_AUTHENTICATION si el certificado usado es de autentificación de sitio web.
    • TIME_STAMP si el certificado usado es un sello de tiempo.
  • Estilos personalizados: (SI/NO). Opción que permite la personalización del estilo de los iframes, deberá indicar en el alta la URL a la nueva hoja de estilos. La URL deberá ser accesible por la aplicación MFE
  • Juridic2Physical: (SI/NO). Opción que permite acceder a la aplicación como persona jurídica a partir de un certificado de representante de persona jurídica. Durante el proceso de identificación al volver de Cl@ve se mostrará la siguiente imagen. En el caso de selección persona física en el token JWT generado no se guardará información sobre el tipo de certificado con el que se ha realizado la identificación.


  • Tipo JWT: (JWT Titular - JWT Titular/Certificado - JWT Titular/Certificado/Puesto). Opción que permite la obtención de varios tipos de token JWT. La primera opción únicamente ofrece información a cerca del usuario identificado, la opción JWT titular/Certificado, ofrece información del usuario identificado y el certificado utilizado en el proceso de identificación, JWT Titular/Certificado/Puesto, a la información del token anterior le añade el organismo con el que se ha identificado el usuario y los permisos que posee para la aplicación en la que se ha identificado
  • Validación de rol: (SI/NO) Esta opción únicamente se encontrará disponible en le caso de que se seleccione como "Tipo JWT" el valor "JWT Titular/Certificado/Puesto". Permite establecer un control adicional en el proceso de identificación donde se obliga al usuario que se está identificando en la aplicación a poseer permisos para la aplicación a la que está accediendo en el organismo seleccionado para poder finalizar la identificación.
  • Estilos DESY: (SI/NO) Esta opción permite los establecer los estilos DESY para la aplicación.
  • Modalidad con PRETOKEN: (SI/NO) Esta opción debe elegirse para que las aplicaciones que no estén bajo el dominio aragon.es puedan identificarse.


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
Es un sistema orientado a unificar y simplificar el acceso electrónico de los ciudadanos a los servicios públicos (Más información en https://clave.gob.es/clave_Home/clave.html). Las propiedades que tenemos que indicar en el alta para este método de identificación son las siguientes:

· 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
Es un sistema que permite la identificación mediante un certificado digital. No requiere especificar ningún parámetro de configuración. Como resultado se obtiene un token JWT idéntico al obtenido a través de una identificación con el método Cl@ve. 



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.

Metadato compatibilidad con IE
<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 de 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:

Etiqueta Iframe
<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 para redimensionar
<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.

On Identification
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.

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

 Ver campos de respuesta json
CAMPODESCRIPCIÓNPOSIBLES VALORES
status
  • ERROR
  • SUCCESS
  • NOT_VALID
  • NOT_VALID_SSO
errorMessagemensaje de error cuando el estado de la validación no es “SUCCESS”
authenticationQualitynivel de calidad de la autentificación que devuelve la entidad validadora
identificationMethodmétodo de identificación que ha escogido el usuario
eidentifieridentificador del usuario
namenombre y apellidos del usuario
givenNamenombre de pila del usuario
surname1primer apellido del usuario
surname2segundo apellido del usuario
mailCorreo electrónico para el cual ha sido expedido el certificado
certificateType
  • PHYSICAL_PERSON si el certificado usado es de una persona física.
  • JURIDIC_PERSON si el certificado usado es de una persona jurídica.
  • UNRECOGNIZED si el certificado usado no esta reconocido por la entidad validadora.
  • PUBLIC_EMPLOYEE si el certificado usado es de un empleado publico.
  • STAMP si el certificado usado es un certificado cualificado de sello.
  • WEBSITE si el certificado usado es de una sede electronica.
  • WEBSITE_AUTHENTICATION si el certificado usado es de autentificación de sitio web.
  • TIME_STAMP si el certificado usado es un sello de tiempo.
representativeIdentifieridentificador del representante del organismo con el que se accede (solamente para certificados de personas jurídicas)
representativeNamenombre y apellidos del representante del organismo con el que se accede (solamente para certificados de personas jurídicas)
representativeGivenNamenombre de pila del representante del organismo con el que se accede (solamente para certificados de personas jurídicas)
representativeSurname1primer apellido del representante del organismo con el que se accede (solamente para certificados de personas jurídicas)
representativeSurname2segundo apellido del representante del organismo con el que se accede (solamente para certificados de personas jurídicas)
representationTypetipo de representación. Indica si la representación la está realizando un ciudadano (CITIZEN) o un empleado público (EMPLOYEE)
procedureprocedimiento habilitado con el que está accediendo el representante.


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

 Ver campos de respuesta extendidos json
CAMPODESCRIPCIÓNPOSIBLES VALORES
certificateTypeDescDescripción del tipo de certificado
authorityEntidad certificadora
certificateUseUsos del certificado
classificationClasificación del certificado
organizativeUnitDescripción de la unidad organizativa
policyPolítica del certificado
policyVersionVersión de la política del certificado
selectedIdpIdentificador del proveedor de identidades contra el que se desea realizar la autenticación.
  • AFIRMA → Certificado electrónico
  • EIDAS → Credencial europea
  • SEGSOC → Clave permanente
  • PIN24H → Clave PIN
serialNumberNúmero de serie del certificado
validFromDateFecha del comienzo de validez del certificadoEj: 2019-05-02 jue 12:44:40 +0200
validToDateFecha del final de validez del certificadoEj: 2022-05-01 dom 12:44:40 +0200
loginTimeFecha de identificación en milisegundos

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:

 Ver campos de respuesta extendidos json
CAMPODESCRIPCIÓNPOSIBLES VALORES
organismCode

Código de organismo que ha seleccionado el usuario para identificarse en la aplicación


organismName

Nombre del organismo que ha seleccionado el usuario para identificarse en la aplicación


roleCode

Código del cargo que desempeña el usuario en el organismo seleccionado


roleName

Nombre del cargo que desempeña el usuario en el organismo seleccionado


roleAppCode

Código del rol que tiene asignado el usuario para el organismo seleccionado en la aplicación a la cual desea acceder


roleAppName

Nombre del rol que tiene asignado el usuario para el organismo seleccionado en la aplicación a la cual desea acceder


aud

Nombre de aplicación para la cual se genera el token


user_name

Identificador del usuario: NIF de la persona identificada


authorities

Array que contiene los nombres de los roles que tiene el usuario en el organismo seleccionado para la aplicación a la cual está accediendo. Si no tiene ningún rol, el array estará vacío.




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


http://[URL_SERV]/mfe_core/rest/identification/[APPLICATION_ID]/[APPLICATION_URL_REDIRECT/[IDENTIFICATION_METHOD_ID]/logout


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:

Descarga clave pública del certificado
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:

CAMPODESCRIPCIÓ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

  • 400 → Se debe a un error en la petición por parámetros incorrectos. Si por ejemplo el identificador de aplicación es nulo o vacío, se obtendrá este código.

  • 403 → Se obtiene debido a un error de ip no autorizada en PAU o a no tener permiso sobre el método invocado.

  • 500 → Se debe a un error interno de MFE al obtener la clave pública del certificado.

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:

Renovación de token JWT
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:

CAMPODESCRIPCIÓN

POSIBLES VALORES

httpStatusCode

Código de estado de respuesta HTTP

  • 200 → Se obtendrá la respuesta correctamente.

  • 400 → Se obtendrá error. Se debe a un parámetro no informado correctamente en la petición o a que el token indicado no es válido

  • 403 → Se obtendrá error. Se obtiene debido a un error de ip no autorizada en PAU o a no tener permiso sobre el método invocado.

  • 500 → Se obtendrá error. Se debe a un error interno en MFE.

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:

Cambio de organismo JWT
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:

CAMPODESCRIPCIÓNPOSIBLES VALORES
httpStatusCodeCódigo de estado de respuesta HTTP
  • 200 → Se obtendrá la respuesta correctamente.

  • 400 → Se obtendrá error. Se debe a un parámetro no informado correctamente en la petición o a que el token o el organismo indicado no es válido

  • 403 → Se obtendrá error. Se obtiene debido a un error de ip no autorizada en PAU o a no tener permiso sobre el método invocado.

  • 500 → Se obtendrá error. Se debe a un error interno en MFE.

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

  • Código de la aplicación
  • Nombre de la aplicación

Por cada tipo de firma que se desee realizar:

Operación de firma 1:

  • Nombre de la operación: Nombre que el integrador quiera darle a su operación de firma.
  • Tipo de operación:  los tipos de operación de firma que se pueden realizar son los siguientes:

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.


  • Formato de firma:  forma en que se genera la firma y cómo se guarda o estructura la información de la firma en el documento generado:

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.
EnvelopingLa firma electrónica contiene el documento.

        ◦ EnvelopedEl 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
◦ SHA256withRSA 
◦ SHA384withRSA 
◦ SHA512withRSA 

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.
SI : al usuario solo se le mostrarán los certificados del propio usuario 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 ).


Cl@ve Firma es un sistema de firma para los usuarios común a todo el Servicio Publico Estatal. Este sistema provee con la posibilidad de realizar la firma mediante certificados electrónicos centralizados, es decir: certificados generados y custodiados por la Administración Publica dentro de su sistema. Estos certificados centralizados permiten al usuario firmar documentos electrónicos desde cualquier dispositivo con conexión a Internet y sin ningún equipamiento o programa adicional

 


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.

Metadato compatibilidad con IE
<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
<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
<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.

Metadato compatibilidad con IE
<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
<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
<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.

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.

-

Ejemplo JSON
[
	{
 		"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)

Filtrado de usuario
<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.


Signature Success
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'.

Signature Error
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
<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:

PropiedadDescripciónValores aceptados
idIdentificador obligatorio del elementomfe_signature_button
data-applicationIdentificador de la aplicación integradoraLo elige el integrador al realizar el alta en MFE
data-operationNombre 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-modeIndica 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" />