Document how to live-update mTLS client certificates per SDK (#5032)

* Document how to live-update mTLS client certificates per SDK

Each SDK's client-connection page shows how to rotate an API key on a
running Worker with no downtime, but none covered mTLS client
certificates. Per-SDK mechanism differs and is now documented where it
exists:

- Go: tls.Config.GetClientCertificate callback (no reconnect needed)
- Java: gRPC AdvancedTlsX509KeyManager (no reconnect needed)
- Python, .NET, Ruby: connect a new client with the new cert and
  assign it to the running Worker (client/Client property setter)
- TypeScript: same pattern via worker.connection, available since
  @temporalio/worker 1.15.0
- PHP: noted as not yet supported, requires a Worker restart

Also tidies the bare/miscased external reference link in
cloud-access-control.mdx into a proper citation.

Addresses #3694

* Note that Rust doesn't yet support live mTLS cert rotation

Verified against the Rust SDK's public temporal_sdk::Worker API and
sdk-core: TlsOptions is read once into a static connection, and while
sdk-core gained a replace_client primitive in 2024 (used internally by
the other language SDKs' hot-swap support), it isn't exposed on the
Rust SDK's own public Worker type. Confirmed as a real, currently-open
gap via sdk-rust#1338.

* Update mTLS client certificate rotation instructions

Clarify the process for rotating mTLS client certificates in the Rust SDK documentation.

Author: Duncanma

docs/best-practices/cloud-access-control.mdx

@@ -38,9 +38,9 @@ The high-level end-to-end rotation process is:
 5. **Remove old credentials**: Remove old certificates and API keys from your secrets provider after confirming successful migration 
 
 This approach ensures near-zero-downtime rotation and prevents authentication failures that could impact running workflows. For specific guidance to rotate mTLS certificates and API keys, see:
-- https://docs.temporal.io/cloud/certificates#manage-certificates 
-- https://docs.temporal.io/cloud/api-keys#rotate-an-api-key 
-- https://github.com/temporal-sa/temporal-Worker-cert-rotation 
+- [How to add, update, and remove certificates in a Temporal Cloud Namespace](/cloud/certificates#manage-certificates)
+- [Rotate an API key](/cloud/api-keys#rotate-an-api-key)
+- Per-SDK code for rotating a Worker's mTLS client certificate without a restart is documented on each SDK's Temporal Client page, in the "Connect to Temporal Cloud" section (for example, [Go](/develop/go/client/temporal-client#connect-to-temporal-cloud)) — Go, Java, Python, .NET, Ruby, and TypeScript are all supported; PHP and Rust are not yet. The [temporal-worker-cert-rotation](https://github.com/temporal-sa/temporal-worker-cert-rotation) reference implementation walks through automating this with cert-manager on Kubernetes.
 
 For mutual TLS (mTLS) implementations, using Let's Encrypt is not recommended, as it is designed primarily for public-facing services and lacks support for internal certificate requirements. 
 

docs/develop/dotnet/client/temporal-client.mdx

@@ -460,6 +460,42 @@ To update an API key, update the value of `ApiKey` on the existing client connec
 myClient.Connection.ApiKey = myKeyUpdated;
 ```
 
+To connect using mTLS instead of an API key, provide the client certificate and private key on `Tls`:
+
+```csharp
+var myClient = TemporalClient.ConnectAsync(new(<endpoint>)
+{
+    Namespace = "<namespace_id>.<account_id>",
+    Tls = new()
+    {
+        ClientCert = File.ReadAllBytes("client-cert.pem"),
+        ClientPrivateKey = File.ReadAllBytes("client-private-key.pem"),
+    },
+});
+```
+
+Unlike `ApiKey`, `TlsOptions` is not mutable on an existing connection — the certificate bytes are fixed once the
+connection is established. To rotate an mTLS client certificate without restarting your Worker, connect a new client
+with the new certificate and assign it to the running `TemporalWorker`'s `Client` property:
+
+```csharp
+var newClient = await TemporalClient.ConnectAsync(new(<endpoint>)
+{
+    Namespace = "<namespace_id>.<account_id>",
+    Tls = new()
+    {
+        ClientCert = File.ReadAllBytes("client-cert-new.pem"),
+        ClientPrivateKey = File.ReadAllBytes("client-private-key-new.pem"),
+    },
+});
+
+// worker is the TemporalWorker instance already running against the old client
+worker.Client = newClient;
+```
+
+Setting `Client` replaces the connection the Worker uses for subsequent calls to the Temporal Service (Workflow Task
+completion, Activity Heartbeats, and so on); calls already in flight on the old client are not interrupted.
+
 </TabItem>
 
 </Tabs>

docs/develop/go/client/temporal-client.mdx

@@ -421,6 +421,38 @@ creds := client.NewAPIKeyDynamicCredentials(
 myKey = myKeyUpdated
 ```
 
+To rotate an mTLS client certificate without restarting your Worker, set `GetClientCertificate` on the `tls.Config`
+instead of setting `Certificates` directly. Go's standard library `crypto/tls` package calls this function on every new
+connection, so it always picks up the current certificate:
+
+```go
+clientCertPath := "/path/to/client.crt"
+clientKeyPath := "/path/to/client.key"
+
+clientOptions := client.Options{
+    HostPort:  <endpoint>,
+    Namespace: <namespace_id>.<account_id>,
+    ConnectionOptions: client.ConnectionOptions{
+        TLS: &tls.Config{
+            GetClientCertificate: func(*tls.CertificateRequestInfo) (*tls.Certificate, error) {
+                cert, err := tls.LoadX509KeyPair(clientCertPath, clientKeyPath)
+                if err != nil {
+                    return nil, err
+                }
+                return &cert, nil
+            },
+        },
+    },
+}
+c, err := client.Dial(clientOptions)
+```
+
+Rotate the certificate by overwriting the files at `clientCertPath` and `clientKeyPath`; the next time the connection
+re-establishes (for example, after Temporal Cloud's periodic connection recycling), `GetClientCertificate` reads the new
+files. This works because `ConnectionOptions.TLS` is a real `*tls.Config`, so any option `crypto/tls` supports is
+available. See this [reference implementation](https://github.com/temporal-sa/temporal-worker-cert-rotation) for a full
+walkthrough, including automating certificate issuance with cert-manager on Kubernetes.
+
 You can use a combination of environment variables, configuration files, and code to set connection options. For
 example, you can load a base configuration from environment variables or a configuration file, and then override
 specific options in code.

docs/develop/java/client/temporal-client.mdx

@@ -600,6 +600,39 @@ the new Client:
 ```
 <!--SNIPEND-->
 
+To rotate an mTLS client certificate without restarting your Worker, build the `SslContext` with gRPC's
+[`AdvancedTlsX509KeyManager`](https://grpc.github.io/grpc-java/javadoc/io/grpc/util/AdvancedTlsX509KeyManager.html)
+instead of `SimpleSslContextBuilder`. `updateIdentityCredentialsFromFile` schedules a periodic reread of the certificate
+and key files, so the same `SslContext` keeps serving fresh credentials for the life of the process:
+
+```java
+String tlsCertPath = "/path/to/tls.crt";
+String tlsKeyPath = "/path/to/tls.key"; // PKCS8 format
+
+// Reread the certificate and key files every 5 minutes.
+AdvancedTlsX509KeyManager keyManager = new AdvancedTlsX509KeyManager();
+keyManager.updateIdentityCredentialsFromFile(
+    new File(tlsKeyPath), new File(tlsCertPath),
+    5, TimeUnit.MINUTES,
+    Executors.newSingleThreadScheduledExecutor());
+
+SslContextBuilder sslContextBuilder = SslContextBuilder.forClient();
+GrpcSslContexts.configure(sslContextBuilder);
+SslContext sslContext = sslContextBuilder.keyManager(keyManager).build();
+
+WorkflowServiceStubsOptions stubsOptions = WorkflowServiceStubsOptions
+    .newBuilder()
+    .setSslContext(sslContext)
+    .setTarget(gRPCEndpoint)
+    .build();
+WorkflowServiceStubs serviceStub = WorkflowServiceStubs.newServiceStubs(stubsOptions);
+```
+
+Rotate the certificate by overwriting the files at `tlsCertPath` and `tlsKeyPath`; `keyManager` picks up the new files on
+its next scheduled check, and the Worker keeps running against the same `client`/`serviceStub`. See this
+[reference implementation](https://github.com/temporal-sa/temporal-worker-cert-rotation) (written for the Go SDK, but the
+"What if I am not using the Go SDK?" section covers this Java approach) for a full walkthrough.
+
 </TabItem>
 </Tabs>
 

docs/develop/php/client/temporal-client.mdx

@@ -129,6 +129,13 @@ $serviceClient = \Temporal\Client\GRPC\ServiceClient::createSSL(/*...*/)
     ->withAuthKey('your-api-key');
 ```
 
+Rotating an mTLS client certificate without restarting the Worker isn't currently supported by the PHP SDK or RoadRunner
+— the certificate configured on `ServiceClient::createSSL()` or in RoadRunner's `tls:` block is fixed for the life of
+the process. To rotate a certificate, stage the new certificate alongside the old one on your Temporal Cloud Namespace,
+then restart your Worker (RoadRunner process) with the new certificate before removing the old one. See
+[Update certificates using Temporal Cloud UI/tcld](/cloud/certificates#manage-certificates) for the zero-downtime
+staging sequence.
+
 ## How to start a Workflow Execution {/* #start-workflow-execution */}
 
 [Workflow Execution](/workflow-execution) semantics rely on several parameters—that is, to start a Workflow Execution you must supply a Task Queue that will be used for the Tasks (one that a Worker is polling), the Workflow Type, language-specific contextual data, and Workflow Function parameters.

docs/develop/python/client/temporal-client.mdx

@@ -470,6 +470,33 @@ async def main():
 For more information about configuring TLS to secure inter- and intra-network communication for a Temporal Service, see
 [Temporal Customization Samples](https://github.com/temporalio/samples-server).
 
+Unlike an API key, `TLSConfig` is static: the certificate bytes you pass to `Client.connect` are fixed for the lifetime
+of that `Client`. To rotate an mTLS client certificate without restarting your Worker, connect a new `Client` with the
+new certificate, then assign it to the running `Worker`'s `client` property:
+
+```python
+with open("client-cert-new.pem", "rb") as f:
+    client_cert = f.read()
+with open("client-private-key-new.pem", "rb") as f:
+    client_private_key = f.read()
+
+new_client = await Client.connect(
+    "your-custom-namespace.tmprl.cloud:7233",
+    namespace="<your-custom-namespace>.<account-id>",
+    tls=TLSConfig(
+        client_cert=client_cert,
+        client_private_key=client_private_key,
+    ),
+)
+
+# worker is the Worker instance already running against the old client
+worker.client = new_client
+```
+
+The Worker starts using `new_client` for subsequent calls to the Temporal Service (Workflow Task completion, Activity
+Heartbeats, and so on); calls already in flight on the old client finish normally. The new client must use the same
+`Runtime` as the Worker's current client.
+
 </TabItem>
 
 </Tabs>

docs/develop/ruby/client/temporal-client.mdx

@@ -416,6 +416,27 @@ client = Temporalio::Client.connect(
 For more information about configuring TLS to secure inter- and intra-network communication for a Temporal Service, see
 [Temporal Customization Samples](https://github.com/temporalio/samples-server).
 
+`TLSOptions` is static: the certificate you pass to `Client.connect` is fixed for the lifetime of that client. To rotate
+an mTLS client certificate without restarting your Worker, connect a new client with the new certificate, then assign
+it to the running `Worker`'s `client`:
+
+```ruby
+new_client = Temporalio::Client.connect(
+  '<endpoint>', # Endpoint
+  '<namespace_id>.<account_id>', # Namespace
+  tls: Temporalio::Client::Connection::TLSOptions.new(
+    client_cert: File.read('my-client-cert-new.pem'),
+    client_private_key: File.read('my-client-key-new.pem')
+  )
+)
+
+# my_worker is the Worker instance already running against the old client
+my_worker.client = new_client
+```
+
+The Worker starts using `new_client` for subsequent calls to the Temporal Service; calls already in flight on the old
+client finish normally.
+
 </TabItem>
 
 </Tabs>

docs/develop/rust/client/temporal-client.mdx

@@ -335,6 +335,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 </Tabs>
 
+Rotating an mTLS client certificate without restarting the Worker isn't currently supported by the Rust SDK — the
+certificate in `TlsOptions` is read once and baked into the connection at `Connection::connect`.To rotate a certificate, stage the new certificate alongside the old one on your Temporal Cloud Namespace, then restart your Worker with the new certificate before removing the old one; see
+[Update certificates using Temporal Cloud UI/tcld](/cloud/certificates#manage-certificates) for the zero-downtime
+staging sequence.
+
 ## Start a Workflow Execution {/* #start-workflow-execution */}
 
 To start a Workflow Execution, supply:

docs/develop/typescript/client/temporal-client.mdx

@@ -598,6 +598,29 @@ const worker = await Worker.create({
 });
 ```
 
+`@temporalio/worker` v1.15.0 and later support replacing a running Worker's connection, which lets you rotate an mTLS
+client certificate without restarting the Worker. gRPC's TLS credentials don't support dynamic certs, so instead of
+updating the existing `NativeConnection` you create a new one with the new certificate and assign it to `worker.connection`:
+
+```ts
+import { readFileSync } from 'fs';
+
+const newConnection = await NativeConnection.connect({
+    address: <endpoint>,
+    tls: {
+        clientCertPair: {
+            crt: readFileSync('client-cert-new.pem'),
+            key: readFileSync('client-key-new.pem'),
+        },
+    },
+});
+
+worker.connection = newConnection;
+```
+
+The Worker starts using `newConnection` for subsequent calls to the Temporal Service; calls already in flight on the old
+connection finish normally.
+
 </TabItem>
 
 </Tabs>