Managing Custom TLS Server Certificates for an Event Broker Service

You can manage server certificates for your event broker services using the Cloud Console or the v2 REST APIs. 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 installing the custom server certificates using the Cloud Console or v2 REST APIs, over other options such as the Solace CLI because of enhanced benefits, including:

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 Cloud Console or v2 REST APIs. Server certificates installed using other methods (for example, the CLI) 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 Cloud Console or v2 REST APIs, you should review the Considerations for Managing Server Certificates .

For more information see:

Managing Custom TLS Server Certificates Using the Cloud Console
Managing Custom TLS Server Certificates Using the v2 REST APIs

Considerations for Managing Server Certificates

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

When managing server certificates using the Cloud Console, you must have the Administrator or Mission Control Manager role.
When using the v2 REST APIs to manage your server certificates:
- you require an API token generated from the Cloud Console by an account with the Administrator or Mission Control Manager roles. The API token must have permissions based on the actions you want to perform:
  - Uploading and Installing server certificates: Create services (services:post)
  - Getting all server certificates, or Getting a server certificate by ID: Get Services with Management Credentials (services:get)
  - Deleting server certificates: Delete Services (services:delete)
  For more information see Creating an API Token.
- 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.
You must upload and install server certificates on one event broker service at a time.
You can upload only PEM encoded server certificates. Event broker services do not support DER encoded server certificates.
Only server certificates with RSA private keys are supported. ECDSA private keys are not supported.
You can upload plain text or encrypted server certificates. Encrypted certificates require entry of a passphrase during installation.
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
An event broker service can have a maximum of four server certificates, including the default server certificate provided by Solace.
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.
You cannot delete the default server certificate, or a currently installed custom server certificate.
You can reinstall the default server certificate provided by Solace. Reinstalling the default certificate may require you to resynchronize SSO configurations for event broker service management if you have configured SSO with a custom domain name on your event broker service. see Considerations for Using Custom Hostnames with Single-Sign On Enabled Event Broker Services.
After installing a custom server certificate, you must configure a custom domain hostname for the event broker service.

Managing Custom TLS Server Certificates Using the Cloud Console

You can manage custom TLS server certificate using the Cloud Console. Using the Cloud Console provides the benefit of not having to prepare your server certificate for upload as you must when using the v2 REST APIs.

To install a custom server certificate for your event broker service using the Cloud Console, perform the following steps:

Upload a server certificate
Install the server certificate
Configure a custom domain hostname for the event broker service

You can view information about uploaded and installed server certificates at any time using the Cloud Console. For more information, see Viewing a Server Certificate Information Using the Cloud Console.

You can delete uploaded server certificates when you no longer need them using the Cloud Console. You cannot delete currently installed server certificates, or the default Solace server certificate. For more information, see Deleting a Server Certificate Using the Cloud Console.

Before managing custom certificates using the Cloud Console, you should review the Considerations for Managing Server Certificates .

Uploading a Server Certificate Using the Cloud Console

You can upload a custom TLS server certificate using the Cloud Console. Each event broker service can have up to four server certificates. One of the server certificates must be the default server certificate provided by Solace during service creation.

Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
On the navigation bar, select Cluster Manager .
Select the event broker service that you want to configure. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.
On the Service Details page, click the Manage tab.
On the Management Settings menu, select Network Access.
On the Server Certificates tile, click Upload. The Server Certificate tile shows a total count of server certificates available to install on your event broker service. It also provides information including server certificate IDs, certificate types, and whether a certificate is currently installed.
On the Upload Server Certificate dialog do the following:
1. Click Import, navigate to the location of your server certificate, select it and click Open, or copy and paste the entire contents of the server certificate’s PEM file into the field. The field has a maximum capacity of 32 KB.
2. Click Import, navigate to the location of your server certificate, select it and click Open, or copy and paste entire contents of the private key's PEM file into the field. The field has a maximum capacity of 5 KB.
3. Click Upload.
You return to the Network Access page of the Manage tab and your custom certificate appears in the list of certificates on the Server Certificate tile.

Installing a Server Certificate Using the Cloud Console

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.

Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
On the navigation bar, select Cluster Manager .
Select the event broker service that you want to configure. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.
On the Service Details page, click the Manage tab.
On the Management Settings menu, select Network Access.
On the Server Certificates tile, beside the server certificate you want to install, click Actions and then select Install.
If your server certificate requires a passphrase, enter it in the provided field on the Install Server Certificate dialog. Click Install.
The certificate installs, you a returned to the Network Access page of the Manage tab and Yes appears in the Installed column next to the custom certificate you installed after installation on the event broker service completes.

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.

Managing Custom TLS Server Certificates Using the v2 REST APIs

You can manage custom TLS server certificate using the v2 REST APIs. When managing your server certificates using the v2 REST APIs you must first prepare your server certificate for upload.

To install a custom server certificate for your event broker service using the v2 REST APIs, perform the following steps:

Prepare your server certificate for upload
Upload a server certificate
Install the server certificate
Configure a custom domain hostname for the event broker service

You can view information about uploaded and installed server certificates at any time using the v2 REST APIs . For more information, see Viewing a Server Certificate Information Using v2 REST APIs.

You can delete uploaded server certificates when you no longer need them using the v2 REST APIs. You cannot delete currently installed server certificates, or the default Solace server certificate. For more information, see Deleting a Server Certificate Using v2 REST APIs.

Before managing custom certificates using the v2 REST APIs, you should review the Considerations for Managing Server Certificates .

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 the Certificate

You can use a Linux/Unix terminal command to string the certificates together after extracting them.

cat 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 (outputFilename.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 certificates.p12 -nodes -nokeys | cat inputFilename.pem | awk '{printf "%s\\n", $0}'>>outputFilename.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 custom 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://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.

Upload the server certificate to the event broker service by issuing a POST request to the following URL:

https://${ENDPOINT}/serverCertificates

Replace the variables in the string above with the definitions listed in the table below:

Variable Definition

Variable	Definition
`ENDPOINT`	The REST API URL to the event broker service: `${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}` Where: `CLOUD_HOST`—The base REST API URL for the regional site of your PubSub+ Cloud deployment, for example, https://api.solace.cloud/. For more information, see the list of available base APIs. `SERVICE_ID`—The unique identifier of the event broker service. You can find the ID either: at the end of the URL for your event broker service, for example: `https://console.solace.cloud/services/k8vv6x131e1`, using a GET call. See Getting the Connection Details for the Event Broker Service Using the REST API.

ENDPOINT

The REST API URL to the event broker service: ${CLOUD_HOST}/api/v2/missionControl/eventBrokerServices/${SERVICE_ID}

Where:

CLOUD_HOST—The base REST API URL for the regional site of your PubSub+ Cloud deployment, for example, https://api.solace.cloud/. For more information, see the list of available base APIs.
SERVICE_ID—The unique identifier of the event broker service. You can find the ID either:
- at the end of the URL for your event broker service, for example: https://console.solace.cloud/services/k8vv6x131e1,
- using a GET call. See Getting the Connection Details for the Event Broker Service Using the REST API.

Provide the following in the body of the POST request:

{
  "certificate": "{certificate}",
  "privateKey": "{privateKey}"
}

Replace the variables above with the definitions listed in the table below

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.

The URL for the request must use base REST API URL for the regional site of your PubSub+ Cloud deployment, for example, https://api.solace.cloud/. For more information, see the list of available base APIs.

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

To install a custom server certificate, use the Install a server certificate API to install an uploaded server certificate to the event broker service. The URL for the request must use base REST API URL for the regional site of your PubSub+ Cloud deployment, for example, https://api.solace.cloud/. For more information, see the list of available base APIs.

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 Viewing Server Certificate Information For 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 Cloud Console or v2 REST APIs. Server certificates installed using other methods (for example, the CLI) may not show a date, or may show an invalid date.

Configuring a Custom Domain Hostname for an Event Broker Service

Viewing Server Certificate Information For an Event Broker Service

You can view server certificate information using the Cloud Console or v2 REST APIs. For more information, see:

Viewing a Server Certificate Information Using the Cloud Console
Viewing a Server Certificate Information Using v2 REST APIs

Viewing a Server Certificate Information Using the Cloud Console

You can view limited information about a specific server certificate installed on an event broker service directly from the Server Certificates tile, the total number of server certificates uploaded, the server certificate IDs, the certificate types (custom or default), and whether a certificate is installed. You can view additional information about server certificates using the Cloud Console. To view additional information about uploaded server certificates, do the following:

Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
On the navigation bar, select Cluster Manager .
Select the event broker service that you want to configure. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.
On the Service Details page, click the Manage tab.
On the Management Settings menu, select Network Access.
On the Server Certificates tile, beside the server certificate you want to install, click Actions and then select View.
Complete information about the sever certificate is shown in the View Server Certificate dialog, including certificate ID, certificate type (default of custom), whether the certificate is installed, the valid date range for the certificate, the certificate subject CN, the certificate serial number, and the certificate SHA-1 thumbprint. When done reviewing the information, click Close.

Viewing a Server Certificate Information Using v2 REST APIs

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.

The URL for the request must use the base REST API URL for the regional site of your PubSub+ Cloud deployment, for example, https://api.solace.cloud/. For more information, see the list of available base APIs.

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.

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 using the Cloud Console or v2 REST APIs. You cannot delete the Solace-provided default server certificate or a currently installed custom server certificate. To delete an installed certificate, you must install a different server certificate first.

For more information, see:

Deleting a Server Certificate Using the Cloud Console
Deleting a Server Certificate Using v2 REST APIs

Deleting a Server Certificate Using the Cloud Console

You can delete server certificates using the Cloud Console. You cannot delete the Solace-provided default server certificate or a currently installed custom server certificate. To delete a server certificate, do the following:

Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
On the navigation bar, select Cluster Manager .
Select the event broker service that you want to configure. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.
On the Service Details page, click the Manage tab.
On the Management Settings menu, select Network Access.
On the Server Certificates tile, beside the server certificate you want to install, click Actions and then select Delete.
On the Delete Server Certificate dialog, click Delete.

Deleting a Server Certificate Using v2 REST APIs

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 Viewing Server Certificate Information For an Event Broker Service.

Provide feedback