Sign Service integration

Overview

In this tutorial, you will learn how to integrate Sign Service, a server-side digital signing solution that centralizes certificate management and enforces access control using token-based authentication.

This tutorial is intended for developers and IT administrators. To follow it, a basic understanding of HTTP APIs, bearer token authentication, and digital certificates is helpful.

Background

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

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

The integration flow consists of two main phases:

1. Authentication and token retrieval: The user authenticates against Redtrust, which issues a JWT (JSON Web Token) to authorize access to the signing service.

2. Document signing using Redtrust certificates: Once authenticated, your application can perform signing operations using the digital certificates managed by Redtrust.

Before you begin

To integrate the service, you need the following information provided by the Redtrust customer:

• IP address or host name of the Redtrust server.

• The port used to access Sign Service (default is 8083).

• Application user name for the service.

• (Optional) Domain name.

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

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

Step 1: General configuration

1. Access the service URL and sign in:

   https://YOUR_REDTRUST_IP:PORT/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=YOUR_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 the list of supported parameters, see Supported parameters.

Required headers

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

Header	Description
x-partner-name	Client application name in uppercase. Used to identify and authorize the calling partner.
x-request-timestamp	UNIX timestamp indicating when the request is made. Helps prevent replay attacks. See Unix TimeStamp - Epoch Converter.
x-hmac-signature	Cryptographic signature that validates the request. Generated by signing the message PARTNER_NAME:UNIX_TIMESTAMP using HMAC-SHA256 with a shared key.

The x-hmac-signature header lets the server verify the authenticity and integrity of the request using the shared secret key. Any request that is unsigned, malformed, or invalid will be rejected.

Implementation resources

.NET HMACSHA256 class

HMAC-SHA256 signature generator - Akto

Temporary credential callback

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

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

https://apptest.com?tkn=WP0WSA2D4415ABZ270HW3F62F1152C48ORT0F929I6VISR780Y583FD10138FG4S

Your application must capture the tkn parameter from the redirect URL. This temporary credential must be exchanged for a permanent access token and a refresh token by calling a specific endpoint (see step 2, Sign-in process).

The access token is required to sign documents and perform other authorized operations. The refresh token allows session renewal without re-authenticating.

Step 2: Sign-in process

The process starts by calling the following URL:

https://YOUR_REDTRUST_IP:PORT/authclient/auth/loginrequest?Consumer=SIGN_SERVICE&Domain=YOUR_DOMAIN&RedirectUrl=REDIRECT_URL&timestamp=TIMESTAMP&partner=PARTNER_NAME&hmac=HMAC_SIGNATURE

Depending on the parameters and the user's configuration, there are three possible scenarios:

1. No domain specified

   If no domain is provided (or if it is not an OAuth or SAML type), the Redtrust authentication form is displayed. The user must sign in with the configured credentials (username and password, multi-factor authentication, etc.).

2. External domain specified (OAuth or SAML)

   If a domain registered as an external Identity Provider (IdP) using OAuth or SAML is specified, Redtrust redirects the user directly to the IdP's sign-in page.

   This flow bypasses the Redtrust sign-in interface. If federation exists between the client application and Redtrust, single sign-on (SSO) is also supported, allowing the user to skip re-authentication.

3. No domain specified, but the user belongs to an external IdP

   A variant of scenario 1. The user enters their Redtrust username and, if they belong to an external IdP, they are automatically redirected to the corresponding provider.

In all cases, the process ends by redirecting the user to the specified redirect URL, which includes the temporary credential (tkn) to be exchanged for a permanent access token.

To complete the token exchange, call the following endpoints:

Endpoint: /authapi/v1/login_by_temp_token

Method: POST Authentication: Authorization: Bearer <accessToken> 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: Authorization: Bearer <accessToken> 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: Authorization: Bearer <accessToken> Body: None
Content-Type: application/json

Response

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

Additional resources

The following resources are available to help you test the integration and generate the required headers:

• Postman collection Download Includes pre-configured requests for testing authentication with Redtrust.

• Postman helper script Download Automatically generates the x-hmac-signature header in Postman with the correct format and secret.

tip

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

Step 3: Signing process

Signing requests are made to the following base URL:

https://YOUR_REDTRUST_IP:PORT/signapi

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

To complete the signing process, use the endpoints described in the Sign API reference.

Additional resources

• Postman collection Download

Supported parameters

Parameter	Description
Consumer (required)	Must always be set to SIGN_SERVICE for this service.
RedirectUrl (required)	URL to which the user will be redirected at the end of the process. A temporary credential is appended. Make sure to apply UrlEncode.
Domain (optional)	Domain of the users who will use the API. Allows the flow to adapt based on the user type.
timestamp (required)	Timestamp in UNIX format (seconds since epoch).
partner (required)	Uppercase name of the client application making the request.
hmac (required)	HMAC signature for security. See the section on the x-hmac-signature header for more information.