Skip to main content

How to manage certificates in Temporal Cloud

Join the Temporal Cloud waitlist

Access to Temporal Cloud is currently by invitation only. You can join the waitlist.

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 include SHA-256 or stronger. SHA-1 and MD5 signing algorithms are rejected.

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 include SHA-256 or stronger. SHA-1 and MD5 signing algorithms are rejected.

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.

  1. Ensure that your certificates meet the certificate requirements.
  2. Add client CA certificates to a Cloud Namespace.

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

To manage certificates for Temporal Cloud Namespaces, use the tcld namespace accepted-client-ca commands.

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

This functionality is in development.

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 export command.