Managing Certificate Authorities with the PubSub+ Cloud REST API

The PubSub+ CloudREST APIs and API tokens allow you to add and delete the domain certificate authority (CA) certificates and client CA certificates programmatically. You can also disable the standard domain CA list if you want to use only the domain CA certificates that you have added.

If applications use client certificates to authenticate with an event broker service, you must also add the appropriate client CA certificates. For more information, see Managing Authentication with the PubSub+ Cloud REST API.

To perform these tasks in the Cloud Console, see Managing Domain and Client Certificate Authorities.

This topic includes steps to complete the following tasks:

Adding a Domain or Client CA for Event Broker Services
Deleting a Domain or Client CA
Getting the List of CA Certificates for Event Broker Services
Enabling or Disabling the Standard Domain Certificate Authorities List

About Certificates and Event Broker Services

Event broker services use certificates to authenticate the servers that they establish TLS connections with. Event broker services can also use certificates to authenticate the client applications that they connect with. Certificates are issued by a certificate authority (CA). When a CA issues a server (domain) or client certificate, the CA signs the issued certificate. If an event broker service has the signing CA's own certificate in its trust store, the event broker service can verify that certificate presented for authentication was issued by a trusted CA and can therefore be sure of the identity of the server or client.

The trust store for PubSub+ Cloud event broker services can include these types of CA certificates:

Standard Domain Certificate Authorities

The trust store for all event broker services contains CA certificates for Mozilla's standard trust of server certificate CAs. Mozilla is a highly-trusted, industry-accepted, de-facto standard. Servers with certificates issued by these CAs are trusted in many environments. The Standard Domain CA certificate trust store enables event broker services to authenticate a server's name and domain for all outgoing TLS connections.

This trust store is read-only and can be disabled if you don't want to allow TLS connections to servers that use certificates issued by these CAs.

Domain Certificate Authorities

You can also add domain CA certificates to the trust store if, for example, your organization uses your own internal CA to sign domain certificates. These domain CA certificates can be used in combination with the CA certificates in the Standard Domain CA trust store to authenticate servers for outgoing TLS connections.

Client Certificate Authorities

For greater security, you can require client applications to present a client certificate to authenticate their identity to an event broker service to establish a mutual TLS connection. The Client CA trust store can contain CA certificates that enable event broker services to authenticate clients using client certificate authentication or OAuth authentication for incoming TLS connections.

Before you Begin

Before you can start this tutorial, you require the following:

An account with PubSub+ Cloud and event broker service.
Your profile must be assigned the Administrator or Cluster Manager Editor role.
The service ID of the event broker service. The {serviceId} is the last value of the specified service's URL. For example, in this URL https://console.solace.cloud/services/d4g5cxzcrhk, the service ID is d4g5cxzcrhk. The service identifier is required for many of the REST API calls.
An API token must be available in the account with the following permissions:
- From Mission Control:
  - Get My Services with Management Credentials
- From Organization Services:
  - Get Services With Management Credentials
  - Create / Delete Certificate Authorities
For more information, see Creating an API Token.
A REST client of your choice. Postman is a good choice if you want a visual REST API development tool. At this time, there is no Solace Blog available so if you use Postman, simply make each call by typing the REST API call after you've set up the environment in Postman to use your API token. For more information about setting up Postman, see Managing API Tokens.

After you've set up the environment in Postman to use your API token, you can simply make each call by specifying the REST API. To check that API token is set up correctly to use Bearer authorization in Postman, select the Headers tab to validate that it is using Bearer Authorization and set it to use the apiToken environment variable that you had set up earlier. For example, you can see that Authorization is set up to use Bearer and the apiToken in the following illustration:

Adding a Domain or Client CA for Event Broker Services

You can add a domain or client CA certificate to an event broker service.

The minimum permission required in the API token to use this REST API call is Create / Delete Certificate Authorities.

To add the certificate, you issue a POST to https://api.solace.cloud/api/v0/services/{serviceId}/requests/serviceCertificateAuthorityRequests where {serviceId} is the identifier of the event broker service.

A successful request returns 201 (Created); otherwise, one of the following error codes is returned:

5000 — with a support code of 102 if serviceCertificateAuthorityRequests was passed an invalid format or missing a parameter. The request must include all the required parameters in the payload.
5000 — with a support code of 106 indicates the certificate authentication permission (Create / Delete Certificate Authorities) is not enabled in the API token that was used.

As part of the POST call, you must specify the following parameters in the payload:

certificate — The container object for the payload that contains the following parameters:
- name —The string name to identify the certificate to add to the event broker service.
- content — The PEM file certificate. The -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- must be separated from the certificate contents (random string) using \n (newline).
- action — Use the action create as the verb to create the certificate.
certType — Use domain to create a server domain CA certificate or client to create a client CA certificate. To preserve API backwards compatibility, this parameter is not marked as required to preserve compatibility with older clients; however this parameter must be used for all new clients. If you don't specify this parameter, both a server domain and client certificate are created using the specified content.

For example, if the service identifier of vsr13ijvlhn is used in a POST call to https://api.solace.cloud/api/v0/services/vsr13ijvlhn/requests/serviceCertificateAuthorityRequests with the following payload:

{
  "certificate": {
  "name": "MyFirstCert",
  "content":"-----BEGIN CERTIFICATE-----\nMIID5zCCAs+gAwIBAgIUK1Esxtvcw0h772/ZNspgH7EkyMQwDQYJKoZIhvcNAQELBQAwgYIxCzAJBgNVBAYTAkdCMQ8wDQYDVQQIDAZMb25kb24xDzANBgNVBAcMBkxvbmRvbjEYMBYGA1UECgwPR2xvYmFsIFNlY3VyaXR5MRYwFAYDVQQLDA1JVCBEZXBhcnRtZW50MR8wHQYDVQQDDBYqLm1lc3NhZ2luZy5zb2xhY2UuY29tMB4XDTIxMDcxNTE3MzQ0MVoXDTIyMDcxNTE3MzQ0MVowgYIxCzAJBgNVBAYTAkdCMQ8wDQYDVQQIDAZMb25kb24xDzANBgNVBAcMBkxvbmRvbjEYMBYGA1UECgwPR2xvYmFsIFNlY3VyaXR5MRYwFAYDVQQLDA1JVCBEZXBhcnRtZW50MR8wHQYDVQQDDBYqLm1lc3NhZ2luZy5zb2xhY2UuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmpFZql+L7K3S5+8C2GojP8wpOk78N/rHTPTuGmylFnzOv5FBDkqZuZRQBnkkvPJO80XZAY2m5cBrWeH3VqQXn0s2pStxnFnjNoUpPg33OzYbFYZkOL8B3u2g1fM+vGfqIjm9UYFQaDPxSNvHB2slkOay4Z1iwaj6EfHy+yuLiImay3nfDydMgyM+/rsGA4DjEc7d5xnU1n1H10CLaLsvRah1LyR3YWKT85Pw5yft8bA9SWsJKBrzpo8vb4qP5gadqzQnljW4IrJbopKGvExb02CLlzd2eTZSr9CwnCREb4H1LjQ+0gxZV25aAmvGNho0TFSlpKgbfJoXS9V1ibpS0QIDAQABo1MwUTAdBgNVHQ4EFgQUl0rNoyaUxMaXG8/4xM666M86I2owHwYDVR0jBBgwFoAUl0rNoyaUxMaXG8/4xM666M86I2owDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAJD1lD//MzQE14KwXZ4nL9/5koLO6kQL7NvI0yhd1/hes9+lhhxeB2O8EZ28nxu5weBgVR/pyJDkpivJKntnlqOO0zitm85Z64tWh2RFjufs2DhKLtSZ1UKQQATIFsnYOsBDU2D3StVRrUqnWD/0OkoRzFpSKpqDtWl7FDIUcAscZZBGehsY/YtPMj3b/jcCdGAR+kUeEaj7v7Mx98Kx0vmUmYHwr+s28HCaQJOjQ7P9s6VT/QhXZ8ErhOQUoTrLYxa10SCtwgVkd/HYLJbDKZ5lALUO+lmbIBbwKOD3TIl3DHMniskuDrzSjKPemdM7dWn6AvQmBxbvghqfkpQ9o+A==\n-----END CERTIFICATE-----",
  "action": "create"
  },
  "certType": "client"
}

Upon success, the following response is returned:

  "data": {
    "id": "8bgf3k68bzs",
    "creationTimestamp": 1631136684773,
    "certificate": {},
    "certType": "client",
    "type": "serviceCertificateAuthorityRequest"
  }

Continuing from the previous example, if you issue the GET call to https://api.solace.cloud/api/v0/services/vsr13ijvlhn/requests/8bgf3k68bzs, you can see the status is completed in the adminProgress parameter in the response as shown below:

{
  "data": {
    "id": "8bgf3k68bzs",
    "creationTimestamp": 1631136684773,
    "adminProgress": "completed",
    "certificate": {},
    "certType": "client",
    "type": "serviceCertificateAuthorityRequest"
   },
  "meta": {
    "currentTime": 1631136792025
  }
}

You can also issue a GET request to the service to verify the certificate was created. For more information, see Getting the List of CA Certificates for Event Broker Services.

Deleting a Domain or Client CA

You can delete a domain or client CA certificate from an event broker service. The minimum permission required in the API token to use this REST API call is Create / Delete Certificate Authorities.

To remove the certificate, you issue a POST call to https://api.solace.cloud/api/v0/services/{serviceId}/requests/serviceCertificateAuthorityRequests where {serviceId} is the identifier of the event broker service.

A successful request returns 201 (Created); otherwise, one of following error codes is returned:

5000 — with a support code of 102 if serviceCertificateAuthorityRequests was passed an invalid format or missing a parameter. The request must include all parameters specified in the payload above.
5000 — with a support code of 106 indicates the certificate authentication permission (Create / Delete Certificate Authorities) is not enabled in the API token that was used.

As part of the POST call, you must specify the following parameters in the payload:

certificate — The container object for the payload that contains the following parameters:
- name — The name of the certificate to remove from the event broker service. Note that if you specify a name that doesn't exist, the operation returns a status of completed.
- action — Use the action delete as the verb for the POST request.
certType — Use domain to delete a server domain certificate or client to delete a client certificate. To preserve API backwards compatibility, this parameter is not marked as required to preserve compatibility with older clients; however this parameter must be used for all new clients. If you don't specify this parameter, the specified name for the certificate (if it exists) is removed from the both the client certificate and server domain lists for the event broker service.

For example, for the service identifier of vsr13ijvlhn, a POST call to https://api.solace.cloud/api/v0/services/vsr13ijvlhn/requests/serviceCertificateAuthorityRequests with the following payload to delete a client certificate looks like this:

{
  "certificate": {
    "name": "MyFirstCertificate",
    "action": "delete"
  },
  "certType": "client"
}

Upon success, the following response is returned:

{
  "data": {
    "id": "e23zv0w1qn8",
    "creationTimestamp": 1631131845296,
    "certificate": {},
    "certType": "client",
    "type": "serviceCertificateAuthorityRequest"
   }  
}

Because this operation is asynchronous, you must issue a GET call to https://api.solace.cloud/api/v0/services/{serviceId}/requests/{requestId} to check the progress of the operation, where serviceId is the identifier for the event broker service and requestId is the value from id parameter that was returned in the response from the POST call. Continuing from the previous example, if you issue the GET call to https://api.solace.cloud/api/v0/services/vsr13ijvlhn/requests/e23zv0w1qn8, you can see the status is completed in the adminProgress progress in the response as follows:

{
  "data": {
    "id": "e23zv0w1qn8",
    "creationTimestamp": 1631133476085,
    "adminProgress": "completed",
    "certificate": {},
    "certType": "client",
    "type": "serviceCertificateAuthorityRequest"
   },
  "meta": {
    "currentTime": 1631133476500
  }
}

You can also issue a GET request to the service to verify the certificate was removed. For more information, see Getting the List of CA Certificates for Event Broker Services.

Getting the List of CA Certificates for Event Broker Services

To get the names for the available CA certificates, you issue a GET to https://api.solace.cloud/api/v0/services/{serverId} where {serverId} is the identifier for the service regardless of the version of your event broker service.

The minimum permission required in the API token are one of Get My Services with Management Credentials or Get Services with Management Credentials (though both are recommended so that you can see both event broker services you create and those created by others in the Account). When the GET call is successful, a 200 response is returned. For event broker services, the names of the CA certificates are found in the clientCertificateAuthorities (for client CA certificates) and domainCertificateAuthorities (for server domainCA certificates) parameters.

If an error occurs for the GET call, one of the following error codes is returned:

5000 — with a support code of 103 if the specified event broker service could not be found.
5000 — with a support code of 106 if the required permissions (Get Services with Management Credentials or Get My Service with Management Credentials) were not enabled in the API token that was used.

For example, a POST call to https://api.solace.cloud/api/v0/services/v0q6d1xqg7g to an event broker service gives the following response:

{
  "data": {
  "type": "service",
  "timestamp": 0,
  "userId": "9hbxppv9y75",
  "serviceId": "v0q6d1xqg7g",
  "infrastructureId": "2bn7jlo767j",
  "name": "My-First-Service",
  "msgVpnName": "my-first-service",
  "datacenterId": "gke-gcp-us-central1-a",
  "datacenterProvider": "gcp",
  ...
			<snip>
			...
			...
  "certificateAuthorities": [],
  "clientCertificateAuthorities": [
    "MySecondCertificate",
    "MyFirstCertificate"
   ],
  "domainCertificateAuthorities": [
	"MyFirstServerCertificate"			
   ],
  "clientProfiles": [
			"default"
   ],
  ...
  <snip>
  ...
  }
}

For more information about getting service information, see Getting the Connection Details for the Event Broker Service Using the REST API.

Enabling or Disabling the Standard Domain Certificate Authorities List

For event broker services, the standard domain CA list includes industry-standard, trusted CA certificates used to verify the server names for outgoing TLS connections. This list cannot be modified and is enabled by default. If you want to use only the domain CA list that you have added CA certificates to, you can disable the standard domain CA list. To do this, run the following POST command to https://api.solace.cloud/api/v0/services/${serviceId}/requests/standardCertificateAuthorityRequests.

The minimum permission required in the API Token to use this REST API call is Create / Delete Certificate Authorities.

A successful request returns 201 (Created); otherwise, one of the following error codes is returned:

5000 — with a support code of 102 if the standardCertificateAuthorityRequests was passed an invalid format or missing a parameter. The request must include all parameters specified in the payload above.
5000 — with a support code of 106 certificate authentication permission (Create / Delete Certificate Authorities) is not enabled in the API token that was used.

As part of the POST call, you must specify the following parameters in the payload:

certificate — The container object for the payload that contains the following parameters:
- name — The name of the certificate to remove from the event broker service. Note that if you specify a name that doesn't exist, the operation still returns a status of completed.
- action — Use the action delete as the verb for the POST request.

For example, if the identifier for the service identifier of v0q6d1xqg7g, a POST call to https://api.solace.cloud/api/v0/services/v0q6d1xqg7g/requests/standardCertificateAuthorityRequests with the following parameters in the payload:

{
  "enable": "false"
}

Upon success, the following response is returned:

{
  "data": {
  "id": "st8do048y8c",
  "creationTimestamp": 1631203856862,
  "tlsStandardDomainCertificateAuthoritiesEnabled": true,
  "type": "standardCertificateAuthorityRequest"
  }
}

Because this operation is asynchronous, you must issue a GET call to https://api.solace.cloud/api/v0/services/{serviceId}/requests/{requestId} to check the progress of the operation, where serviceId is the identifier for the event broker service and requestId is the value from id parameter that was returned in the response from the POST call. Continuing from the previous example, if you issue the GET call to https://api.solace.cloud/api/v0/services/v0q6d1xqg7g/requests/st8do048y8c, you can see the status is completed in the adminProgress progress in the response as follows:

{
  "data": {
    "id": "st8do048y8c",
    "creationTimestamp": 1631203856862,
    "adminProgress": "completed",
    "type": "defaultServiceRequest"
   },
  "meta": {
    "currentTime": 1631203859000
  }
}

Provide feedback