Version: 4.32

Integration with Sign Service

Overview

In this tutorial, you'll learn how to integrate with Redtrust's Sign Service, a server-side digital signing solution that centralizes certificate management and uses token-based authentication to enforce access control.

This tutorial is intended for developers and IT administrators. It assumes you have basic knowledge of HTTP APIs, bearer token authentication, and digital certificates.

Background

This integration allows your application to use Redtrust’s centralized digital certificates to sign documents securely through Sign Service.

Redtrust's Sign Service handles the entire signing flow — including user authentication, token issuance, certificate management, and signature execution — all through a secure, centralized API.

The integration flow consists of two main phases:

Authentication and token acquisition:
The user authenticates against Redtrust, which issues a JWT (JSON Web Token) to authorize access to signing services.
Document signing using Redtrust certificates:
Once authenticated, your application can perform signing operations using the digital certificates managed by Redtrust.

Before you start

To integrate with the new service, you need the following information provided by the Redtrust client:

IP address or hostname of the Redtrust server.
The port used to access Sign Service (default is 8083).
Name of the application user for the service.
(Optional) Domain name.

You will also need the following information provided by the client application's operator:

Redirect URL where the temporary credentials will be sent. This address must be registered in Redtrust to authorize the redirection target and is essential to obtain the final token (JWT).

Step 1: General configuration

Access the service URL and log in.
```
https://[HOSTNAME_OR_IP]:[PORT]/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=[DOMAIN]&RedirectUrl=[REDIRECT_URL]&timestamp=[TIMESTAMP]&partner=[PARTNER_NAME]&hmac=[HMAC_SIGNATURE]
```
For example: 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

note

For a list of supported parameters, see Supported parameters.

Required headers

To ensure the legitimacy of each request, you must include the following HTTP headers:

Header	Description
`x-partner-name`	The name of the client application, written in uppercase. This is used to identify and authorize the calling partner.
`x-request-timestamp`	A UNIX timestamp indicating when the request is made. This helps prevent replay attacks. See Unix TimeStamp - Epoch Converter.
`x-hmac-signature`	A cryptographic signature used to validate the request. It is generated by signing the message `PARTNER_NAME:UNIX_TIMESTAMP` using the HMAC-SHA256 algorithm with a shared secret.

The x-hmac-signature allows the server to verify the authenticity and integrity of the request using the same shared secret. Any request with a missing, malformed, or invalid signature will be rejected.

Resources for implementation

.NET HMACSHA256 Class

Akto HMAC-SHA256 Hash Generator

Temporary credential return

If the authentication operation completes successfully, the server automatically redirects the user to the URL specified in the initial request.

This redirect will append a temporary credential in the query string. For example:

https://apptest.com?tkn=WP0WSA2D4415ABZ270HW3F62F1152C48ORT0F929I6VISR780Y583FD10138FG4S

Your application must intercept this tkn parameter in the redirected URL. This temporary credential must then be exchanged for a permanent access token and refresh token by calling a specific token endpoint (see step 2 Log in process).

The access token is required for digital signing (and other authorized operations). The refresh token allows you to renew the session without re-authenticating.

Step 2: Log in process

The login process is initiated by calling the following URL:

https://[HOSTNAME_OR_IP]:[PORT]/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=[DOMAIN]&RedirectUrl=[REDIRECT_URL]&timestamp=[TIMESTAMP]&partner=[PARTNER_NAME]&hmac=[HMAC_SIGNATURE]

Depending on the parameters and user configuration, there are three possible outcomes:

No domain specified.

If no domain is provided (or if the specified domain is not of type OAuth or SAML), the request will load the Redtrust authentication form. The user must then complete the login process as configured in the Redtrust environment (e.g., username and password or multifactor authentication).
External IdP domain specified (OAuth or SAML)

If the request includes a domain that is registered as an external Identity Provider (IdP) using OAuth or SAML, Redtrust will immediately redirect the user to the IdP's login page.

This flow bypasses any Redtrust login UI. It also allows for seamless Single Sign-On (SSO) if a federation exists between the client application and Redtrust, meaning that users already logged into the client application won’t need to authenticate again.
No domain specified, but the user belongs to an external IdP

This is a variation of scenario 1. The user first enters their Redtrust username in the standard login form. Based on this username, if the user is associated with an external IdP, Redtrust will then redirect to the appropriate IdP login page.

In all three cases, the process ends with a redirection to the RedirectUrl specified in the original request. This redirection will append a temporary credential (via the tkn parameter) that must be exchanged for a final access token.

To complete the token exchange, you must call the following endpoints:

Endpoint: `/authapi/v1/login_by_temp_token`

Method: GET
Authentication: Bearer Token in Authorization header
Body:

{
  "temporalToken": "string"
}

Response

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

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

Method: PUT
Authentication: Bearer Token in Authorization header
Body:

{
  "refreshToken": "string"
}

Content-Type: application/json

Response

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

Endpoint: `/authapi/v1/logout`

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

Response

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

Additional resources

To help you test the integration and generate the required headers, the following resources are available:

Postman collection Download This file contains a set of preconfigured requests to test the authentication process with Redtrust.
Helper script for Postman Download This script helps you generate the x-hmac-signature header within Postman using the correct format and secret.

tip

Make sure to import the collection into Postman and configure the variables (e.g., timestamp, partner name, shared secret) before sending requests.

Step 3: Signing process

The signing requests will be made to the following URL:

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

For example https://localhost:8083/signapi/v1/sign/document or https://localhost:8083/signapi/v1/certificate/list

To complete the signing calls, you must use the following three endpoints:

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

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

Response

{
  "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: Bearer Token in Authorization header
Body: None
Content-Type: application/json
Response: Signed file.

note

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

Response

{
  "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 ]

Additional resources

Postman collection Download

Supported parameters

Parameter	Description
`Consumer` (required)	This must always be set to `SIGN_SERVICE` for this service.
`RedirectUrl` (required)	The URL to which the user will be redirected at the end of the process. A temporary credential will be appended to this URL. Make sure to apply `UrlEncode` to the final value.
`Domain` (optional)	Refers to the domain of the users who will use the API. Helps streamline the flow based on user type (see additional notes below).
`timestamp` (required)	Timestamp of the request in UNIX format (seconds since epoch).
`partner` (required)	The uppercase name of the client application making the request.
`hmac` (required)	HMAC signature for security. Refer to the `x-hmac-signature` header section below for more information.

Overview​

Background​

Before you start​

Step 1: General configuration​

Required headers​

Resources for implementation​

Temporary credential return​

Step 2: Log in process​

Endpoint: /authapi/v1/login_by_temp_token​

Response​

Endpoint: /authapi/v1/refresh-token​

Response​

Endpoint: /authapi/v1/logout​

Response​

Additional resources​

Step 3: Signing process​

Endpoint: /signapi/v1/certificate/list​

Response​

Endpoint: /signapi/v1/sign/document​

Endpoint: /signapi/v1/sign/hash​

Response​

Supported algorithms and paddings​

Additional resources​

Supported parameters​

Overview

Background

Before you start

Step 1: General configuration

Required headers

Resources for implementation

Temporary credential return

Step 2: Log in process

Endpoint: `/authapi/v1/login_by_temp_token`

Response

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

Response

Endpoint: `/authapi/v1/logout`

Response

Additional resources

Step 3: Signing process

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

Response

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

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

Response

Supported algorithms and paddings

Additional resources

Supported parameters