Skip to main content

TLS

There are two classes in the SDK that connect to the Temporal server, the Worker and the client Connection. When instantiating either of them, you may choose whether to connect securely or not.

In order to connect to the server using TLS, set a truthy value (true or TLSConfig for custom options) in the tls configuration option.

Use ServerOptions.tlsWhen creating a new Worker and ConnectionOptions.tls for the Connection constructor.

The client connection also accepts GRPC credentials at ConnectionOptions.credentials as long as tls is not also specified.

mTLS tutorial#

Follow this tutorial for setting up mTLS (Mutual TLS authentication) for a local server, client, and Worker.

  1. Clone the customization samples repo
  2. Change directory to tls/tls-simple in the cloned repository
  3. Follow these instructions to set up a local server with mTLS
  4. The sample does not register the default namespace on startup, register it with: docker exec -it tls-simple_temporal-admin-tools_1 tctl n re --retention 1 default
  5. Create a new temporal project with npm init @temporalio --sample hello-world-mtls or copy the relevant configuration from the snippets below into an existing project.
  6. Build your project with npm run build
  7. Export the required environment variables:
  • export TEMPORAL_ADDRESS=localhost
  • export TEMPORAL_NAMESPACE=default
  • export TEMPORAL_SERVER_ROOT_CA_CERT_PATH=/path/to/customization-samples/tls/tls-simple/certs/ca.cert
  • export TEMPORAL_SERVER_NAME_OVERRIDE=tls-sample
  • export TEMPORAL_CLIENT_CERT_PATH=/path/to/customization-samples/tls/tls-simple/certs/client.pem
  • export TEMPORAL_CLIENT_KEY_PATH=/path/to/customization-samples/tls/tls-simple/certs/client.key
  1. Run the Worker

packages/create-project/samples/worker-mtls.ts

import fs from 'fs';
import { Worker, Core } from '@temporalio/worker';
import { getEnv, Env } from './mtls-env';
/**
* Run a Worker with an mTLS connection, configuration is provided via environment variables.
* Note that serverNameOverride and serverRootCACertificate are optional.
*/
async function run({
address,
namespace,
clientCertPath,
clientKeyPath,
serverNameOverride,
serverRootCACertificatePath,
taskQueue,
}: Env) {
let serverRootCACertificate: Buffer | undefined = undefined;
if (serverRootCACertificatePath) {
serverRootCACertificate = fs.readFileSync(serverRootCACertificatePath);
}
await Core.install({
serverOptions: {
address,
namespace,
tls: {
serverNameOverride,
serverRootCACertificate,
// See docs for other TLS options
clientCertPair: {
crt: fs.readFileSync(clientCertPath),
key: fs.readFileSync(clientKeyPath),
},
},
},
});
const worker = await Worker.create({
workDir: __dirname,
taskQueue,
});
console.log('Worker connection succesfully established');
// Start accepting tasks on the `tutorial` queue
await worker.run();
}
run(getEnv()).catch((err) => {
console.error(err);
process.exit(1);
});
  1. In a new terminal run the client to schedule a sample Workflow

packages/create-project/samples/client-mtls.ts

import fs from 'fs';
import { Connection } from '@temporalio/client';
import { Example } from '../interfaces/workflows';
import { getEnv, Env } from './mtls-env';
/**
* Schedule a Workflow connecting with mTLS, configuration is provided via environment variables.
* Note that serverNameOverride and serverRootCACertificate are optional.
*/
async function run({
address,
namespace,
clientCertPath,
clientKeyPath,
serverNameOverride,
serverRootCACertificatePath,
taskQueue,
}: Env) {
let serverRootCACertificate: Buffer | undefined = undefined;
if (serverRootCACertificatePath) {
serverRootCACertificate = fs.readFileSync(serverRootCACertificatePath);
}
const connection = new Connection({
address,
tls: {
serverNameOverride,
serverRootCACertificate,
clientCertPair: {
crt: fs.readFileSync(clientCertPath),
key: fs.readFileSync(clientKeyPath),
},
},
});
await connection.untilReady();
// Create a typed client using the Example Workflow interface,
const workflow = connection.workflow<Example>('example', { namespace, taskQueue });
const result = await workflow.start('Temporal');
console.log(result); // Hello, Temporal!
}
run(getEnv()).then(
() => process.exit(0),
(err) => {
console.error(err);
process.exit(1);
}
);

Connecting to Temporal Cloud (with mTLS)#

The sample above can be used to connect to a Temporal Cloud account. When signing up to Temporal Cloud you should receive a namespace, a server address and a client certificate and key. Use the following environment variables to set up the sample:

  • TEMPORAL_ADDRESS
  • TEMPORAL_NAMESPACE
  • TEMPORAL_CLIENT_CERT_PATH
  • TEMPORAL_CLIENT_KEY_PATH

Get notified of updates