How to manage certificates in Temporal Cloud

Access to Temporal Cloud is secured with the mutual Transport Layer Security (mTLS) protocol. This protocol requires a CA certificate from you.

Worker Processes use both CA certificates and private keys to connect to Temporal Cloud. Private keys remain in your control; Temporal Cloud requires no exchange of secrets.

Certificate requirements

Certificates provided to Temporal for your Namespaces must meet the following requirements.

CA certificates

CA certificates must meet the following criteria:

The certificates must be X.509v3.
Each certificate in the bundle must be either a root certificate or issued by another certificate in the bundle.
Each certificate in the bundle must include CA: true.
A certificate cannot be a well-known CA (such as DigiCert or Let's Encrypt) unless the user also specifies certificate filters.
The signing algorithm must be either RSA or ECDSA and must include SHA-256 or stronger message authentication. SHA-1 and MD5 cannot be used.

End-entity certificates

An end-entity (leaf) certificate must meet the following criteria:

The certificate must be X.509v3.
Basic constraints must include CA: false.
The key usage must include Digital Signature.
The signing algorithm must be either RSA or ECDSA and must include SHA-256 or stronger message authentication. SHA-1 and MD5 cannot be used.

When a client presents an end-entity certificate, and the whole certificate chain is constructed, each certificate in the chain (from end-entity to the root) must have a unique Distinguished Name.

caution

Distinguished Names are not case sensitive; that is, uppercase letters (such as ABC) and lowercase letters (such as abc) are equivalent.

Issue certificates

Temporal Cloud authenticates a client connection by validating the client certificate against one or more CA certificates that are configured for the specified Namespace.

Option 1: You already have certificate management infrastructure

If your existing certificate management infrastructure supports issuing CA and end-entity certificates, it satisfies the requirements. When you configure the client SDK, you must present a complete certificate chain up to the CA certificate given to Temporal.

Option 2: You have no certificate management infrastructure

If you don't have existing certificate management infrastructure, you can issue the CA and client certificates by using tools such as OpenSSL.

We also provide a tool that issues one root CA and the required end-entity certificate to use on the client SDK. The tool can issue multiple end-entity certificates. We've kept this tool minimal because it is a demonstration tool; it is not meant to be used in production.

You can use this tool in two ways:

Follow the instructions for the temporalio/client-certificate-generation image in Docker Hub. This procedure is the easiest because it's independent of your operating system.
Follow the README instructions in the client-only directory in our temporalio/samples-server repository in GitHub.

info

The maximum number of CA certificates in a certificate bundle is 16. The payload size of a certificate bundle (before base64-encoding) is 32 KB.

Control authorization

Because Temporal Cloud uses mTLS for authorization, we recommend that an end-entity certificate be scoped to a specific Namespace. Temporal Cloud requires full CA chains, so you can achieve authorization in two ways.

Option 1: Issue a separate root certificate for each Namespace

Each certificate must belong to a chain up to the root CA certificate. Temporal uses the root CA certificate as the trusted authority for access to your Namespaces.

Ensure that your certificates meet the certificate requirements.
Add client CA certificates to a Cloud Namespacetcld namespace accepted-client-ca add

How to add client CA certificates to a Namespace in Temporal Cloud using tcld.

Learn more.

Option 2: Use the same root certificate for all Namespaces but create a separate certificate filter for each Namespace

How to manage certificate filters in Temporal Cloud

Manage certificates

note

To manage certificates for a Namespace, a user must have Namespace Admin permission for that Namespace.

To manage certificates for Temporal Cloud Namespaces, use the Namespaces page in Temporal Cloud UI or the tcld namespace accepted-client-catcld namespace accepted-client-ca

How to manage the client CA certificates for a Namespace in Temporal Cloud using tcld.

Learn more commands.

Don't let your certificates expire! Add reminders to your calendar to issue new CA certificates well before the expiration dates of the existing ones.

When updating CA certificates, it's important to follow a rollover process. Doing so enables your Namespace to serve both CA certificates for a period of time until traffic to your old CA certificate ceases.

Be aware that the subject of the existing certificate and the subject of the new certificate must not be identical. One way to meet this requirement is to add a version or a date to the common name (CN).

Update certificates using Temporal Cloud UI

On the left side of the window, select Namespaces.
Select the name of the Namespace to update.
In the top-right portion of the page for the Namespace, select Edit.
On the Edit page, select the CA Certificates card to expand it.
In the certificates box, scroll to the end of the existing certificate (that is, past -----END CERTIFICATE-----).
On the following new line, paste the entire PEM block of the new certificate.
Select Save.
Wait until all Workers are using the new certificate.
Return to the Edit page of the Namespace and select the CA Certificates card.
In the certificates box, delete the old certificate, leaving the new one in place.
Select Save.

Update certificates using tcld

Create a single file that contains both your old and new CA certificate PEM blocks. Just concatenate the PEM blocks on adjacent lines.

-----BEGIN CERTIFICATE-----
... old CA cert ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... new CA cert ...
-----END CERTIFICATE-----

Run the tcld namespace accepted-client-ca set command with the CA certificate bundle file.
```
tcld namespace accepted-client-ca set --ca-certificate-file <path>
```
Monitor traffic to your old certificate until it ceases.
Create another file that contains only the new CA certificate.
Run the tcld namespace accepted-client-ca set command again with the updated CA certificate bundle file.

Manage certificate filters

To limit access to specific end-entity certificates, you can create certificate filters. Each filter contains values for one or more of the following fields:

commonName (CN)
organization (O)
organizationalUnit (OU)
subjectAlternativeName (SAN)

Corresponding fields in the client certificate must match every specified value in the filter.

The values for the fields are case-insensitive. If no wildcard is used, each specified value must match its field exactly.

To match a substring, place a single * wildcard at the beginning or end (but not both) of a value. You cannot use a * wildcard by itself.

You can create a maximum of 25 certificate filters in a Namespace.

If you provide a well-known CA certificate, you cannot clear a certificate filter. A well-known CA certificate is one that is typically included in the certificate store of an operating system.

Examples

In the following example, only the CN field of the certificate's subject is checked, and it must be exactly code.example.com. The other fields are not checked.

AuthorizedClientCertificate {
  CN : "code.example.com"
}

In the following example, the CN field must be stage.example.com and the O field must be Example Code Inc.

AuthorizedClientCertificate {
  CN : "stage.example.com"
  O : "Example Code Inc."
}

When using a * wildcard, the following values are valid:

*.example.com matches code.example.com and text.example.com.
Example Code* matches Example code and Example Code Inc.

The following values are not valid:

.example.*
code.*.com
*

Manage certificate filters using Temporal Cloud UI

To add or remove a certificate filter, follow these steps:

On the left side of the window, click Namespaces.
On the Namespaces page, click the name of the Namespace to manage.
On the right side of the page for the selected Namespace, click Edit.
On the Edit page, click Certificate Filters.
- To add a certificate filter, click Add a Certificate Filter and enter values in one or more fields.
- To remove a certificate filter, click the × in the upper-right corner of the filter details.
To cancel your changes, click Back to Namespace. To save your changes, click Save.

Manage certificate filters using tcld

To set or clear certificate filters, use the following tcld commands:

To view the current certificate filters, use the tcld namespace certificate-filters exporttcld namespace certificate-filters export

How to export certificate filters from a Namespace in Temporal Cloud using tcld.

Learn more command.

Certificate requirements​

CA certificates​

End-entity certificates​

Issue certificates​

Option 1: You already have certificate management infrastructure​

Option 2: You have no certificate management infrastructure​

Control authorization​

Option 1: Issue a separate root certificate for each Namespace​

Option 2: Use the same root certificate for all Namespaces but create a separate certificate filter for each Namespace​

Manage certificates​

Update certificates using Temporal Cloud UI​

Update certificates using tcld​

Manage certificate filters​

Manage certificate filters using Temporal Cloud UI​

Manage certificate filters using tcld​