Integration with Certificate Enroll

Overview

In this tutorial, you’ll learn how to integrate Certificate Enroll, a Redtrust service that allows applications to securely generate keys and request the issuance of digital certificates from a controlled environment.

This tutorial is intended for developers from Redtrust partners who have the capability to issue certificates and want to integrate with the Redtrust enrollment service. It assumes you have basic knowledge of HTTP APIs, bearer token authentication, and digital certificates.

Background

This integration allows a Redtrust partner with certificate issuance capabilities to securely generate the keys on the Redtrust server and ultimately generate the digital certificates.

Certificate Enroll handles the entire certificate issuance flow, including:

• User authentication
• Token issuance
• Key generation
• Certificate request and renewal

The integration flow consists of two main phases:

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

2. Key generation and certificate issuance:
   You use API endpoints to complete the issuance process.

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: Authentication and token acquisition

Authentication request

Access the service URL.

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

For example:

https://localhost:8083/authclient/auth/loginrequest?Consumer=RA_API&Domain=local.users&RedirectUrl=https%3A%2F%2Fgoogle.es%3Ftkn%3D&timestamp=1744719496&partner=CA_DEMO&hmac=c360b2d221a55da777a5ba75264d8800ce6ebe89f41aa8b6da7e1a78bb601055

info

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.

Redirection with temporary token

If authentication completes successfully, the server automatically redirects the user to the provided URL and appends the tkn parameter:

https://your-app.com?tkn=TEMPORARY_TOKEN

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).

Step 2: Token exchange

To complete the authentication, you must exchange the temporary token (tkn) received during redirection for an access token and a refresh token. This is done using the endpoints below:

Endpoint: /authapi/v1/login_by_temp_token

Method: GET
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> Content-Type: application/json Body:

{
  "refreshToken": "string"
}

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

Step 3: Certificate generation and issuance

Certificate-related requests are sent to the base URL:

https://[HOSTNAME_OR_IP]:[PORT]/raapi

For example https://localhost:8082/raapi/v1/csr/create or https://localhost:8082/raapi/v1/csr/finalize

To issue a certificate, you must call two endpoints in sequence:

Endpoint: /raapi/v1/csr/create

Method: GET
Authentication: Authorization: Bearer <accessToken>
Content-Type: application/json
Body:

{
  "dn": [
    {
      "attribute": "<string>",
      "value": "<string>"
    },
    {
      "attribute": "<string>",
      "value": "<string>"
    }
  ],
  "hashType": "SHA384",
  "keyLength": "<integer>",
  "keyType": "DSA",
  "provider": "<string>",
  "requestCode": "<string>",
  "info": {
    "proident_9b": "<string>"
  }
}

This request returns a CSR and a requestCode that you’ll use to complete the process.

Response

{
  "message": "<string>",
  "messageType": "IGNORE",
  "errorCode": "OK",
  "data": "<string>"
}

Example

Request

{
  "dn": [
    {
      "attribute": "cn",
      "value": "john doe"
    },
    {
      "attribute": "o",
      "value": "Redtrust"
    },
    {
      "attribute": "c",
      "value": "Brasil"
    },
    {
      "attribute": "st",
      "value": "PJE"
    },
    {
      "attribute": "l",
      "value": "Sao Paolo"
    },
    {
      "attribute": "ou",
      "value": "Developement"
    }
  ],
  "hashType": "SHA384",
  "keyLength": "2048",
  "keyType": "RSA",
  "provider": "CA_BRASIL"
}

Response

{
"message": "Operation finalized successfully",
    "messageType": "SUCCESS",
    "errorCode": "OK",
    "data": {
        "requestCode": "P775W98SSW4Z1774PMZU",
        "csr": "MIIDYzCCAksCAQAwADCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKpo256NtdwCAcY9tsEzQu/PYMq5lmzkyC8hHqRWKl4IQY9YdSx7Qg7r8P9GHB+CydL2IarzPSE9KXrlWUb4YyKAcEKjlsIcXyTEbTJg0WScETw25Q7lZg2K7erJYfQlLJfZ8EWkZl6ufZoxC/gL8/RMkWAhZouOHXhBy3Ut//RNHPFA1dcGjcMEIAf/rOSp2vnfD7M96ph9NZzJsovUzISogdBayY0QYHHITxtLJbGTa+QoXzPQz9toCEOktCaoJKJALHiw5/IQuEvaYXPh5sh1OGC4el5J+qprGtB4JDq6ztVFo+yK+dRvrLaCh61kblxzw/njPTUm/jXblC13wBUCAwEAAaCCARwwHAYKKwYBBAGCNw0CAzEOFgwxMC4wLjE3NzYzLjIwNwYJKwYBBAGCNxUUMSowKAIBBQwGYmV0YTAxDBFXT1JLR1JPVVBcYmV0YTAxJAwIdzN3cC5leGUwPgYJKoZIhvcNAQkOMTEwLzAdBgNVHQ4EFgQUS8EPLaw20Fc186vA+W2Hs3JgcnkwDgYDVR0PAQH/BAQDAgUgMIGCBgorBgEEAYI3DQICMXQwcgIBAR5qAE0AaQBjAHIAbwBzAG8AZgB0ACAARQBuAGgAYQBuAGMAZQBkACAAUgBTAEEAIABhAG4AZAAgAEEARQBTACAAQwByAHkAcAB0AG8AZwByAGEAcABoAGkAYwAgAFAAcgBvAHYAaQBkAGUAcgMBADANBgkqhkiG9w0BAQUFAAOCAQEAgkJ3Z3a7PCIKL46og9Wljh37xY9za5gNZ8Y+/W4ZFAkVJp0kiI1CdTrgq3XLT0lX/RZ7MOEH7U0nZKQay+wUrEnXLjETGUdr/vmifzhTNzl3Q7wrI53Qg2XAEuAho2vwIE7Hc8PKa2S9da2Z1DprbnnY09P+YlfVes5o9MEm5AKlu1kBnPAsrLSa0cSAywUsZpyTJU+5/zma//ODgTzbl99P06VHIMeJW/Pog4yX+UA420RU8z76pmwgJOs2JqfiRmx7qo5herr0V7A0qdT/pfMInpRmuJlrwAlfIowyx9uK1Tzzs5ZNKhZXaXZ626yq9p1tJcajiUiCUjbatI844w=="
    },
    "isValid": true
}

Endpoint: /raapi/v1/csr/finalize

Method: PUT
Authentication: Authorization: Bearer <accessToken>
Body:

{
  "dataInB64": "<string>",
  "provider": "<string>",
  "requestCode": "<string>"
}

Response: HTTP Code Response
Content-Type: application/json

This call finalizes the issuance process.

Step 4: Certificate renewal

To renew a certificate, you must also call two endpoints. Note that the creation endpoint version changes to v2, while the finalize endpoint remains v1.

Endpoint: /raapi/v2/csr/create

You must include the thumbprintToRenew field in the request body:

{
  ...
  "thumbprintToRenew": "<thumbprint>"
}

Example

Request

{
    "dn": [
        {
            "attribute": "<string>",
            "value": "<string>"
        },
        {
            "attribute": "<string>",
            "value": "<string>"
        }
    ],
    "hashType": "SHA384",
    "keyLength": "<integer>",
    "keyType": "DSA",
    "provider": "<string>",
    "requestCode": "<string>",
    "info": {
        "proident_9b": "<string>"
    },
    "thumbprintToRenew": "<string>"
}

Response

{
  "message": "<string>",
  "messageType": "IGNORE",
  "errorCode": "OK",
  "data": "<string>"
}

Endpoint: /raapi/v1/csr/finalize

This step is the same as in the initial issuance. You must call this endpoint using the same requestCode returned during creation. There’s no need to modify the request data. The new certificate will replace the previous one, preserving its configuration and associations.

Supported parameters

Parameter	Description
Consumer (required)	This must always be set to RA_API 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.