Managing Custom TLS Server Certificates for an Event Broker Service

You can use the advanced event mesh v2 REST APIs for Mission Control to manage custom TLS/SSL server certificates for your event broker services without assistance from SAP. 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 REST APIs for advanced event mesh. Server certificates installed using other methods (for example, CLI or by SAP) 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 REST APIs for advanced event mesh, 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 SAP.

  • 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 SAP.

  • 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:

    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:

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:

  1. Uploading the server certificate to the event broker service.

  2. Installing the server certificate to the event broker service.

  3. Configuring a customer domain hostname for the event broker service.

Uploading a Server Certificate to an Event Broker Service

  1. 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:

    VariableDefinition
    ENDPOINT

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

    Where:

    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

    2. Post 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 by issuing a GET request to: 

https://${ENDPOINT}/operations/${operationsId}

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

Variable Definition
ENDPOINT

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

Where:

operationId The unique identifier of the operation you want to query, included as part of the payload of the response body to an asynchronous API post.

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.

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

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

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

Variable Definition
ENDPOINT

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

Where:

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.

Provide the following in the body of the POST request:

{
  "passphrase": "{passphrase}"
}

Post 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 SAP provided server certificate, you do not require the passphrase.

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 by issuing a GET request to: 

https://${ENDPOINT}/operations/${operationsId}

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

Variable Definition
ENDPOINT

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

Where:

operationId The unique identifier of the operation you want to query, included as part of the payload of the response body to an asynchronous API post.

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 REST APIs for advanced event mesh. Server certificates installed using other methods (for example, CLI or by SAP) 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

Get a list of all server certificates uploaded to an event broker service by issuing a GET request to the following URL: 

https://${ENDPOINT}/serverCertificates

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

VariableDefinition
ENDPOINT

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

Where:

A successful GET request returns code 200. The body of the response contains the following information:

Response item Description
id The unique identifier for the server certificate. The ID is a combination of the event broker service ID and path to the server certificate.
installed

Indicates whether or not the server certificate is installed on the event broker service.

  • true—The server certificate is installed.

  • false—The server certificate is not installed.
certificateType

The type of server certificate:

  • SolaceManaged—The default server certificate installed on the event broker service.

  • Custom—a custom server certificate installed on the event broker service.

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 a list of all server certificates uploaded to an event broker service issue a GET request to the following URL: 

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

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

Variable Definition
ENDPOINT

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

Where:

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

A successful GET request returns code 200. The body of the response contains the following information:

Response item Description
id The unique identifier for the server certificate. The ID is a combination of the event broker service ID and path to the server certificate.
type The type of object. In this case a servercertificate.
installed

Indicates whether or not the server certificate is installed on the event broker service.

  • true—The server certificate is installed.

  • false—The server certificate is not installed.
certificateType

The type of server certificate:

  • SolaceManaged—The default server certificate installed on the event broker service.

  • Custom—a custom server certificate installed on the event broker service.
validityNotBefore The date the server certificate is valid from in ISO 8601 date/time format.
validityNotAfter The date the server certificate expires, in ISO 8601 date/time format.
subjectCN The server certificate’s common name (CN).
serialNumber The server certificate’s serial number. The certificate authority issues the serial number, which uniquely identifies the certificate.
installedCertificateDetails

This field appears only for an installed server certificate. The field provides information about the server certificate, and subject public key in a string, including:

  • Serial Number
  • Signature Algorithm
  • Issuer
  • Validity dates
  • Subject
  • Subject public key info, including:
    • Public Key Algorithm
    • RSA Public Key value
    • Modulus

Deleting a Server Certificate From an Event Broker Service

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

To delete a server certificate, issue a DELETE request to: .

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

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

Variable Definition
ENDPOINT

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

Where:

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.

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 by issuing a GET request to: 

https://${ENDPOINT}/operations/${operationsId}

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

Variable Definition
ENDPOINT

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

Where:

operationId The unique identifier of the operation you want to query, included as part of the payload of the response body to an asynchronous API post.