Versión: 4.31

Integración con Sign Service

Descripción general

En este tutorial, aprenderás a integrar Sign Service, una solución de firma digital del lado del servidor que centraliza la gestión de certificados y aplica control de acceso mediante autenticación basada en tokens.

Este tutorial está dirigido a desarrolladores y administradores de TI. Para seguir este tutorial, te será útil tener conocimientos básicos de las API HTTP, la autenticación con tokens bearer y los certificados digitales.

Antecedentes

Esta integración permite que tu aplicación use los certificados digitales centralizados de Redtrust para firmar documentos de forma segura mediante Sign Service.

Sign Service de Redtrust gestiona todo el flujo de firma, incluyendo autenticación de usuario, emisión de tokens, gestión de certificados y ejecución de firmas, a través de una API centralizada y segura.

El flujo de integración consta de dos fases principales:

Autenticación y obtención de token:
El usuario se autentica contra Redtrust, que emite un JWT (JSON Web Token) para autorizar el acceso al servicio de firma.
Firma de documentos usando certificados de Redtrust:
Una vez autenticada, tu aplicación puede realizar operaciones de firma usando los certificados digitales gestionados por Redtrust.

Antes de empezar

Para integrar el nuevo servicio, necesitas la siguiente información proporcionada por el cliente de Redtrust:

Dirección IP o nombre del host del servidor Redtrust.
El puerto utilizado para acceder a Sign Service (el valor predeterminado es 8083).
Nombre del usuario de aplicación para el servicio.
(Opcional) Nombre de dominio.

También necesitas la siguiente información proporcionada por el operador de la aplicación cliente:

URL de redirección donde se enviarán las credenciales temporales. Esta dirección debe estar registrada en Redtrust para autorizar el destino de redirección y es esencial para obtener el token final (JWT).

Paso 1: Configuración general

Accede a la URL del servicio e inicia sesión:
```
https://[HOSTNAME_O_IP]:[PUERTO]/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=[DOMINIO]&RedirectUrl=[URL_REDIRECCIÓN]&timestamp=[TIMESTAMP]&partner=[NOMBRE_PARTNER]&hmac=[FIRMA_HMAC]
```
Por ejemplo: https://localhost:8083/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=local.users&RedirectUrl=https%3A%2F%2Fgoogle.es%3Ftkn%3D&timestamp=1744719496&partner=CA_DEMO&hmac=c360b2d221a55da777a5ba75264d8800ce6ebe89f41aa8b6da7e1a78bb601055

nota

Para ver la lista de parámetros compatibles, consulta Parámetros soportados.

Cabeceras obligatorias

Para garantizar la legitimidad de cada solicitud, debes incluir las siguientes cabeceras HTTP:

Cabecera	Descripción
`x-partner-name`	Nombre de la aplicación cliente, escrito en mayúsculas. Sirve para identificar y autorizar al partner que realiza la llamada.
`x-request-timestamp`	Timestamp UNIX que indica cuándo se hace la solicitud. Ayuda a prevenir ataques de repetición. Consulta Unix TimeStamp - Epoch Converter.
`x-hmac-signature`	Firma criptográfica que valida la solicitud. Se genera firmando el mensaje `NOMBRE_PARTNER:TIMESTAMP_UNIX` usando HMAC-SHA256 con una clave compartida.

La cabecera x-hmac-signature permite al servidor verificar la autenticidad e integridad de la solicitud usando la clave secreta compartida. Toda solicitud que no tenga firma, esté mal formada o no sea válida será rechazada.

Recursos para la implementación

Clase .NET HMACSHA256

Generador de firma HMAC-SHA256 - Akto

Devolución de credencial temporal

Si la autenticación se completa correctamente, el servidor redirige automáticamente al usuario a la URL especificada en la solicitud inicial.

Esta redirección incluirá una credencial temporal en la cadena de consulta. Por ejemplo:

https://apptest.com?tkn=WP0WSA2D4415ABZ270HW3F62F1152C48ORT0F929I6VISR780Y583FD10138FG4S

Tu aplicación debe interceptar el parámetro tkn en la URL redirigida. Esta credencial temporal debe canjearse por un token de acceso permanente y un token de refresco, llamando a un endpoint específico (consulta el paso 2 Proceso de inicio de sesión).

El token de acceso es necesario para firmar documentos (y otras operaciones autorizadas). El token de refresco permite renovar la sesión sin necesidad de autenticarse de nuevo.

Paso 2: Proceso de inicio de sesión

El proceso se inicia llamando a la siguiente URL:

https://[HOSTNAME_O_IP]:[PUERTO]/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=[DOMONIO]&RedirectUrl=[URL_REDIRECCIÓN]&timestamp=[TIMESTAMP]&partner=[NOMBRE_PARTNER]&hmac=[FIRMA_HMAC]

Según los parámetros y la configuración del usuario, hay tres posibles escenarios:

Sin dominio especificado

Si no se proporciona dominio (o si no es del tipo OAuth o SAML), se mostrará el formulario de autenticación de Redtrust. El usuario debe iniciar sesión con las credenciales configuradas (usuario y contraseña, autenticación multifactor, etc.).
Dominio externo especificado (OAuth o SAML)

Si se especifica un dominio registrado como Proveedor de Identidad externo (IdP) usando OAuth o SAML, Redtrust redirigirá directamente al usuario a la página de inicio de sesión del IdP.

Este flujo omite la interfaz de inicio de sesión de Redtrust. Si existe federación entre la aplicación cliente y Redtrust, también se permite Single Sign-On (SSO), evitando que el usuario tenga que autenticarse nuevamente.
Sin dominio especificado, pero el usuario pertenece a un IdP externo

Variante del escenario 1. El usuario introduce su nombre de usuario de Redtrust y, si pertenece a un IdP externo, se le redirige automáticamente al proveedor correspondiente.

En todos los casos, el proceso termina redirigiendo al usuario a la URL de redirección especificada. Esta incluirá la credencial temporal (tkn) que debe canjearse por un token de acceso definitivo.

Para completar el intercambio del token, debes llamar a los siguientes endpoints:

Endpoint: `/authapi/v1/login_by_temp_token`

Method: GET
Authentication: Token bearer en la cabecera Authorization
Body:

{
  "temporalToken": "string"
}

Respuesta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "ERROR_CODE",
  "data": {
    "refreshToken": "string",
    "accessToken": "string",
    "expiration": "<dateTime>"
  }
}

Endpoint: `/authapi/v1/refresh-token`

Method: PUT
Authentication: Token bearer en la cabecera Authorization
Body:

{
  "refreshToken": "string"
}

Content-Type: application/json

Respuesta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "ERROR_CODE",
  "data": {
    "refreshToken": "string",
    "accessToken": "string",
    "expiration": "<dateTime>"
  }
}

Endpoint: `/authapi/v1/logout`

Method: DELETE
Authentication: Token bearer en la cabecera Authorization
Body: None
Content-Type: application/json

Respuesta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "ERROR_CODE",
  "data": {}
}

Recursos adicionales

Para ayudarte a probar la integración y generar las cabeceras necesarias, tienes disponibles los siguientes recursos:

Colección Postman Descargar
Incluye solicitudes preconfiguradas para probar la autenticación con Redtrust.
Script auxiliar para Postman Descargar
Genera automáticamente la cabecera x-hmac-signature en Postman con el formato y secreto correctos.

tip

Asegúrate de importar la colección en Postman y configurar las variables necesarias (timestamp, nombre del partner, clave compartida) antes de enviar solicitudes.

Paso 3: Proceso de firma

Las solicitudes de firma se realizan en la siguiente URL base:

https://[HOSTNAME_OR_IP]:[PORT]/signapi

Por ejemplo https://localhost:8083/signapi/v1/sign/document o https://localhost:8083/signapi/v1/certificate/list

Para completar el proceso de firma, debes usar los siguientes endpoints:

Endpoint: `/signapi/v1/certificate/list`

Method: GET
Authentication: Token bearer en la cabecera Authorization
Body: None
Content-Type: application/json

Respuesta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": [
    {
      "id": 0,
      "alias": "string",
      "thumbprint": "string",
      "pinPolicy": "NoPIN",
      "requireUsageReason": true
    }
  ]
}

Endpoint: `/signapi/v1/sign/document`

Method: POST
Authentication: Token bearer en la cabecera Authorization
Body: None
Content-Type: application/json
Response: Signed file.

nota

This request uses form data. You must include:

jsonUploadData: a form field containing the serialized JSON (see example below).
file: the document to be signed.

The visualSignature field is optional.

{
    "certificateId":11,
    "pin":null,
    "reason":null,
    "visualSignature": {
        "x": 316,
        "y":843,
        "width":385,
        "height":96, 
        "imageBase64":"[IMAGE_IN_B64]",
        "pages":[1]
    }
}

Endpoint: `/signapi/v1/sign/hash`

Method: POST
Authentication: Bearer Token in Authorization header
Content-Type: application/json
Body:

{
  "dataInBase64": "string",
  "hashAlgorithm": "MD5",
  "padding": "PKCS1",
  "certificate": "string",
  "pin": "a131wC",
  "usageReason": "string"
}

Respuesta

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "OK",
  "data": "string"
}

Supported algorithms and paddings

Supported algorithms: [ MD5, SHA1, SHA224, SHA256, SHA384, SHA512 ]

Supported paddings: [ PKCS1, PSS, OAEP ]

Recursos adicionales

Postman collection Download

Parámetros soportados

Parámetro	Descripción
`Consumer` (requerido)	Debe establecerse siempre como `SIGN_SERVICE` para este servicio.
`RedirectUrl` (requerido)	URL a la que se redirigirá al usuario al finalizar el proceso. Se añade una credencial temporal. Asegúrate de aplicar `UrlEncode`.
`Domain` (opcional)	Dominio de los usuarios que usarán la API. Permite adaptar el flujo según el tipo de usuario.
`timestamp` (requerido)	Marca de tiempo en formato UNIX (segundos desde epoch).
`partner` (requerido)	Nombre en mayúsculas de la aplicación cliente que hace la solicitud.
`hmac` (requerido)	Firma HMAC para seguridad. Consulta la sección sobre la cabecera `x-hmac-signature` para más información.

Descripción general​

Antecedentes​

Antes de empezar​

Paso 1: Configuración general​

Cabeceras obligatorias​

Recursos para la implementación​

Devolución de credencial temporal​

Paso 2: Proceso de inicio de sesión​

Endpoint: /authapi/v1/login_by_temp_token​

Respuesta​

Endpoint: /authapi/v1/refresh-token​

Respuesta​

Endpoint: /authapi/v1/logout​

Respuesta​

Recursos adicionales​

Paso 3: Proceso de firma​

Endpoint: /signapi/v1/certificate/list​

Respuesta​

Endpoint: /signapi/v1/sign/document​

Endpoint: /signapi/v1/sign/hash​

Respuesta​

Supported algorithms and paddings​

Recursos adicionales​

Parámetros soportados​

Descripción general

Antecedentes

Antes de empezar

Paso 1: Configuración general

Cabeceras obligatorias

Recursos para la implementación

Devolución de credencial temporal

Paso 2: Proceso de inicio de sesión

Endpoint: `/authapi/v1/login_by_temp_token`

Respuesta

Endpoint: `/authapi/v1/refresh-token`

Respuesta

Endpoint: `/authapi/v1/logout`

Respuesta

Recursos adicionales

Paso 3: Proceso de firma

Endpoint: `/signapi/v1/certificate/list`

Respuesta

Endpoint: `/signapi/v1/sign/document`

Endpoint: `/signapi/v1/sign/hash`

Respuesta

Supported algorithms and paddings

Recursos adicionales

Parámetros soportados