Managing Custom TLS Server Certificates for an Event Broker Service

You can use the PubSub+ Cloud v2 REST APIs for Mission Control to manage custom TLS/SSL server certificates for your event broker services without assistance from Solace. Management of custom server certificates includes uploading, installing, reviewing, and deleting custom server certificates.

Uploading and installing a custom server certificate to your event broker service allows you to assign a custom domain hostname to your event broker service that matches the common name (CN) of the server certificate. Installing a custom server certificate and assigning a custom domain hostname allows you to enable single sign-on for the event broker service.

We recommend using the v2 REST API described here for installing custom TLS server certificates over other options such as the command line interface (CLI) because of enhanced benefits native to the v2 REST API, such as:

Visibility of the server certificate expiration date for the event broker service on the Status tab of Cluster Manager.

Server certificate expiration dates on the Status tab of Cluster Manager are only visible for server certificates installed using the v2 REST APIs. Server certificates installed using other methods (for example, CLI or by Solace) may not show a date, or may show an invalid date.
Resiliency of storing the certificate as a Kubernetes secret. If a pod needs to be recreated, the event broker service it contains does not need to have its certificate reinstalled to continue functioning.

Before managing a custom server certificate for your event broker service using the v2 REST APIs, you should review the Considerations for Managing Server Certificates .

Considerations for Managing Server Certificates

Be aware of the following considerations when managing server certificates for your event broker service:

You must upload and install server certificates on one event broker service at a time.
An event broker service can have three server certificates, including the default server certificate provided by Solace.
Only server certificates with RSA private keys are supported. ECDSA private keys are not supported.
You can upload only PEM encoded server certificates. Event broker services do not support DER encoded server certificates.
The system validates uploaded server certificates. Validation ensures that the server certificate:

components are in the right order
is syntactically correct
dates are valid, and not expired

You can upload plain text or encrypted server certificates. Encrypted certificates require entry of a passphrase during installation.
If your server certificates and private key are in a PKCS file, you must extract the server certificates and add them to a concatenated string before uploading them. You must also extract the private key as a string before uploading as well. See Preparing a Server Certificate for Upload for example commands you can use to extract and concatenate server certificates into a text file.
The Mission Control Agent stores uploaded server certificates as an encrypted, event broker service-specific Kubernetes secret prior to installation.
The Mission Control Agent stores installed server certificates on the event broker service.
After installing a custom server certificate, you must configure a custom domain hostname for the event broker service.
If you want to revert to the default server certificate, contact Solace.
You require an API key with at least the access to Mission Control permission (mission_control:access). You also require additional permissions based on the action you want to perform:
- Uploading and Installing a server certificates: Create services (services:post)
- Get All, Get by ID: Get Services with Management Credentials (services:get)
- Delete server certificates: Delete Services (services:delete)
For more information see Creating an API Token.

Preparing a Server Certificate for Upload

Uploading a server certificate and using the v2 REST API requires adding a string containing the server certificates you want to upload and install, as well as another string with the private key . Typically, your certificate provider gives you a single PKCS file containing the certificates and private key you require. You can use OpenSSL to extract the contents of the PKCS file. You can concatenate the server certificates into a text file, from which you can copy and paste them for use with the Initiate an upload of a server certificate API.

Below we provide examples of how you can:

extract certificates and keys from a PKCS file using OpenSSL commands
concatenate the certificates using an awk command
extract and concatenate certificates to a text file

Extracting the Certificate or Keys from a PKCS File

You can use OpenSSL commands to extract the contents of the PCKS file. Below you will find a command for extracting certificates and another command for extracting a private key.

To extract the certificates, use the following command:
```
openssl pkcs12 -info -in INFILE.p12 -nokeys
```
To extract the private key, use the following command.
```
openssl pkcs12 -info -in INFILE.p12 -nocerts
```

Concatenating Certificates Using an AWK Command

You can use an awk command to string the certificates together after extracting them.

cert.pem | awk '{printf "%s\\n", $0}'

Extracting and Concatenating Certificates to a Text File

You can combine the commands above to extract the server certificates from a provided PKCS file (certificates.p12) and create a text file (containerFile.txt) with the concatenated certificates, whose contents you can paste into the a certificate parameter field of the Initiate an upload of a server certificate API.

openssl pkcs12 -info -in example.p12 -nodes -nokeys | awk '{printf "%s\\n", $0}'>>containerFile.txt

Adding Server Certificates to Event Broker Services

Installing a server certificate on your event broker service requires three steps:

Uploading the server certificate to the event broker service.
Installing the server certificate to the event broker service.
Configuring a customer domain hostname for the event broker service.

Uploading a Server Certificate to an Event Broker Service

Determine the unique identifier for the event broker service you want to upload the server certificate to, using one of the following methods:

In Cluster Manager, select the event broker service and get its unique identifier from the last segment in the URL. For example, 9c5vurtex4b is the identifier from https://console.solace.cloud/services/9c5vurtex4b.
Use the Get list of services REST endpoint to find the unique identifier (id) of the event broker service.

Use the Initiate an upload of a server certificate API to upload your server certificate to the event broker service.

Specify the Path Parameter fields as follows:

Body Parameter	Definition
`certificate`	Copy and paste the contents of the server certificate’s PEM file into the field, starting from and including the lines `-----BEGIN CERTIFICATE-----` to `-----END CERTIFICATE-----`. The field has a maximum capacity of 32 KB. The string you add to this field must contain all of the server certificates as a concatenated string. For more information, see Preparing a Server Certificate for Upload.
`privateKey`	Copy and paste the contents of private key's PEM file into the field, starting from and including the lines `-----BEGIN PRIVATE KEY-----` to `-----END PRIVATE KEY-----`. The field has a maximum capacity of 5 KB.

A successful POST request returns code 202 Accepted, with an operationId as part of the payload of the response body. You can get the status of the operation using the Get the status of a service operation REST API with the operationId to query the status of the operation.

You can test that the server certificate was successfully installed by getting a list of server certificates uploaded to an event broker service. A successfully installed server certificate will appear in the response with a unique Id and installed status of false, and certificateType of custom.

Installing a Server Certificate on an Event Broker Service

After uploading a server certificate to an event broker service, you can install it. Installing the server certificate makes it the active certificate for the event broker service. Only one server certificate can be active at any time. After installing a custom server certificate, you must configure a custom domain hostname for the event broker service.

To install a custom server certificate, use the Install a server certificate API to install an uploaded server certificate to the event broker service.

https://${ENDPOINT}/serverCertificates/${certificateId}/install

Specify the Path Parameter fields as follows:

Variable	Definition
`serviceId`	The unique identifier of the event broker service where you want to install the server certificate. You can determine the unique identifier for an event broker service using the Cloud Console or by using a GET call. See Get a list of event broker services.
`certificateId`	The unique identifier of the server certificate you want to install. You can get the certificate ID using a GET request. For more information, see Retrieving Server Certificate Information From an Event Broker Service.

Define the Body Parameter field with the information listed in the table below:

{
  "passphrase": "{passphrase}"
}

Body Parameter	Definition
`passphrase`	If the server certificate you uploaded in step 1 was encrypted, you must enter its passphrase. If you are reinstalling the default Solace provided server certificate, you do not require the passphrase.

You can test that the server certificate was successfully installed by Getting Information About a Specific Server Certificate by Its ID. If the certificate is installed, its installed property shows as true.

Server certificates installed using the v2 REST API show their expiry date on the Status tab in Cluster Manager. Certificates that expire within the next 90 days show a status of Expires Soon. Expired certificates show a status of Expired.

Server certificate expiration dates on the Status tab of Cluster Manager are only visible for server certificates installed using the v2 REST APIs. Server certificates installed using other methods (for example, CLI or by Solace) may not show a date, or may show an invalid date.

Configuring a Custom Domain Hostname for an Event Broker Service

After uploading and installing a custom server certificate, you must configure a custom domain hostname for the event broker service. Failure to configure a custom domain hostname will cause name mismatch warnings to appear when attempting to connect to the event broker service. For more information, see Configuring Custom Domain Names for Event Broker Services.

Retrieving Server Certificate Information From an Event Broker Service

You can retrieve information about the server certificates uploaded to an event broker service. You can also get more detailed information about a specific server certificate using the server certificates' unique ID.

For more information, see:

Getting a List of Server Certificates Uploaded to an Event Broker Service
Getting Information About a Specific Server Certificate by Its ID

Getting a List of Server Certificates Uploaded to an Event Broker Service

To get a list of server certificates uploaded to an event broker service, use the Get all server certificates API. The returned information includes the server certificate IDs, type (custom or Solace managed), and whether the certificate is installed.

https://${ENDPOINT}/serverCertificates

A successful GET request returns code 200. The response will contain the id, installed status, and certificateType information for all uploaded certificates.

Getting Information About a Specific Server Certificate by Its ID

You can get information about a specific server certificate installed on an event broker service using the server certificates ID. Information returned includes the server certificate IDs, type (custom or default), and whether the certificates are installed, validity dates, common name, and serial number, and details about the server certificate.

To get information about a server certificate by its ID, use the Get a server certificate by ID API.

https://${ENDPOINT}/serverCertificates/${certificateId}

Specify the Path Parameter fields as follows:

Variable	Definition
`certificateId`	The unique identifier for the custom server certificate you uploaded.

A successful GET request returns code 200.

Deleting a Server Certificate From an Event Broker Service

You can delete server certificates when you no longer need them. You cannot delete the Solace-provided default server certificate or a currently installed custom server certificate.

To delete a server certificate use the Delete a server certificate by ID API.

Specify the Path Parameter fields as follows:

Variable	Definition
`certificateId`	The unique identifier of the server certificate you want to delete. You can get the certificate ID using a GET request. For more information, see Retrieving Server Certificate Information From an Event Broker Service.

Provide feedback