4.- Integración con MFE
INDICE DEL CONTENIDO
- 1 1. MFE - Módulo de identificación
- 1.1 1.1 Requisitos Previos
- 1.2 1.2 Integración de la aplicación
- 1.2.1 1.2.1 Etiqueta compatibilidad Internet Explorer
- 1.2.1.1 Metadato compatibilidad con IE
- 1.2.2 1.2.2 Archivos javascript
- 1.2.2.1 Script de identificación
- 1.2.3 1.2.3 Iframe para incrustar los métodos de identificación
- 1.2.3.1 Etiqueta Iframe
- 1.2.4 Iframe con estilos DESY
- 1.2.4.1 Script para redimensionar
- 1.2.5 1.2.4 Método javascript 'onIdentification'
- 1.2.6 1.2.5 Validación del token jwt
- 1.2.7 1.2.6 Cierre de sesión (logout)
- 1.2.8 1.2.7 Obtención de clave pública del certificado que firma jwt
- 1.2.9 1.2.7 Renovar token JWT
- 1.2.9.1 Renovación de token JWT
- 1.2.10 1.2.8 Cambio de organismo JWT
- 1.2.10.1 Cambio de organismo JWT
- 1.2.11 1.2.9 Uso de MFE en dominio cruzado ( Modalidad PRETOKEN )
- 1.2.1 1.2.1 Etiqueta compatibilidad Internet Explorer
- 2 2. MFE - Módulo de Firma Cliente
- 2.1 2.1 Requisitos Previos
- 2.2 2.2.- Integración de la aplicación
- 2.2.1 2.2.1.- Firma simple o multi-firma (en paralelo o en cascada).
- 2.2.1.1 Metadato compatibilidad con IE
- 2.2.1.2 Script
- 2.2.1.3 IFrame
- 2.2.2 2.2.2 Firma en bloque de varios documentos.
- 2.2.2.1 Metadato compatibilidad con IE
- 2.2.2.2 Script
- 2.2.2.3 IFrame
- 2.2.2.4 Datos a firmar
- 2.2.2.5 Ejemplo JSON
- 2.2.2.6 Filtrado de usuario
- 2.2.2.7 Signature Success
- 2.2.2.8 Signature Error
- 2.2.1 2.2.1.- Firma simple o multi-firma (en paralelo o en cascada).
- 2.3 2.3.- Integración de la aplicación sin IFRAME
- 2.3.1 Script
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.
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.4.1 Método javascript 'onIdentification' en Angular con varios nodos
En el caso de que el iframe de MFE se ejecute en una aplicación Angular con varios nodos, es necesario controlar el funcionamiento correcto, dentro del método JS onIdentification definido para evitar los múltiples eventos.
Para dicho control, se puede utilizar un campo que haga de flag, el cual al cargar inicialmente la aplicación estará a true, una vez el usuario se identifique correctamente y el flujo entre al método JS onIdentification definido, se controla dicho flag, si es true, este se pasa a false y se continua con la lógica propia de la aplicación para el acceso correcto del usuario. Si se produce un error al identificarse se vuelve a poner a true para que el usuario vuelva a identificarse en el iframe.
On Identification - Angular varios nodos
// Por defecto en el componente se permite identificar la primera vez
allowOnIdentification = true;
public onIdentification(operation: any): void {
if (this.allowOnIdentification) {
this.allowOnIdentification = false;
service.loginEnLaAplicacion(operation).then(() => {
// Lógica de aplicación
}.catch(() => {
this.allowOnIdentification = true;
// Lógica de aplicación
});
}
}
-
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
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:
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: