Guía del utilitario PPS

📘

Audiencia: TPP y Bancos ·
Propósito: generar las firmas digitales de seguridad (registro DCR y client_assertion) sin tener que construirlas manualmente.

Producir los security details a mano (firmas DCR, client assertion, pruebas DPoP y x-jws-signature) es complejo y propenso a errores. El utilitario PPS automatiza esa generación a partir de los certificados y llaves del participante.

1. Objetivo del utilitario

El utilitario genera firmas digitales que protegen información sensible antes de enviarla a otros sistemas. La firma permite comprobar que el mensaje:

• proviene de quien dice enviarlo, y
• no ha sido alterado en el camino.

La firma se envía por separado del mensaje, como lo exigen los estándares financieros de Open Banking.

2. Prerrequisitos

Antes de usar el utilitario, debe haberse completado el intercambio inicial con Redeban: enviar los CSR y recibir los archivos .jks y .jwks.

Desde el archivo .jwks se identifica la URL del campo x5u para descargar los certificados públicos en formato .pem. El campo use indica para qué sirve cada certificado:

📘

Glosario breve de archivos

• CSR (solicitud de certificado)
• .jks (almacén de llaves/certificados en Java)
• .jwks (conjunto de claves públicas)
• .pem (certificado público para validación)
• .key (llave privada).

3. Configuración mínima

El utilitario se configura mediante un archivo externo que define las rutas de los archivos y los datos del participante, sin necesidad de modificar el código. Se recomienda organizar los archivos junto al .jar con esta estructura:

Ubicación del archivo de configuración

El archivo debe estar en la misma ruta del .jar, dentro de la carpeta unified/, con el formato utilitiesunified_{env}.yml, donde {env} puede ser sandbox o cert.

Contenido del archivo

Como mínimo se configuran las rutas de las llaves privadas, los certificados públicos, el archivo .jwks, el archivo .jks y datos como el SSA y el OnboardingID.

4. Archivos clave

5. Cómo ejecutar el utilitario

El sistema se distribuye como un archivo .jar.

Requisitos previos

• Java 21 instalado.
• Una terminal (CMD o PowerShell).

Paso 1. Seleccionar el ambiente: cert o sandbox.

Paso 2. Ejecutar el app.jar desde la terminal con el perfil correspondiente:

java --jar ./app.jar --spring.profiles.active=cert

📘

Reemplazar cert por sandbox cuando corresponda.

Paso 3. Abrir Swagger en el navegador para probar los servicios:

http://localhost:5003/swagger-ui/index.html

6. Casos de uso principales

6.1 Firma para registro (DCR)

Sirve para firmar la información requerida al registrar una aplicación. Usa el kid del certificado de signing y datos como software_id, scope y SSA.

Endpoint: en Swagger, ir a dynamic-client-registration-controller y hacer clic en Try it out para generar el DCR.

Descripción de los campos (headers y body):

📘

Para consultar el contenido del SSA puede usarse un decodificador de JWT como jwt.io.

Resultado. Se obtiene una firma que se incorpora al payload enviado al endpoint de registro del ambiente correspondiente:

6.2 Firma para autenticación (Client Assertion)

Permite generar un token de autenticación (client_assertion) con el que el sistema solicita acceso a otros servicios.

Datos clave: kid, sub, iss, isBank e isPreproduction.

Resultado. Se obtiene un token JWT utilizable para autenticarse ante otros servicios.

7. Relación entre archivos y carpetas

Las rutas definidas en la configuración deben apuntar correctamente a los archivos de llaves, certificados, .jwks y .jks. Estos archivos deben estar en la misma ruta del .jar, dentro de la carpeta works/, organizada por ambiente (por ejemplo sandbox y certification).

🚧

Cada llave privada debe corresponder exactamente al certificado público asociado.

Ejemplo de configuración de rutas:

utilities:
  thirdPartyProviderPaths:
    privateKeySigningFile: 'works/certification/{{namefile_signing}}.key'
    privateKeyNetworkFile: 'works/certification/{{namefile_network}}.key'
    publicKeySigningFile: 'works/certification/{{namefile_signing}}.pem'
    publicKeyNetworkFile: 'works/certification/{{namefile_network}}.pem'
    jwksFile: 'works/certification/{{namefile_OB}}.jwks'
    jksFile: 'works/certification/{{namefile_SC}}.jks'

8. Flujo resumido del proceso

1. Verificar que se recibieron los archivos requeridos y descargar los certificados .pem.
2. Configurar correctamente las rutas en el archivo utilitiesunified_{env}.yml.
3. Ubicar los archivos en las carpetas del ambiente correspondiente.
4. Ejecutar el utilitario y generar la firma o el token necesario.

9. Problemas comunes

10. Nota importante

📘

El sistema utiliza por defecto el puerto de ejecución 5003.