feat(client): support custom ServerCertVerifier in TlsOptions by brucearctor · Pull Request #1271 · temporalio/sdk-rust

brucearctor · 2026-05-14T03:25:28Z

Summary

Adds an optional server_cert_verifier field to TlsOptions that accepts an Arc<dyn ServerCertVerifier>. When set, the client uses tonic's tls_config_with_verifier() to replace the default WebPKI certificate verification.

Closes #1248

Motivation

The current TlsOptions API only supports static PEM-encoded certificates, which prevents advanced TLS patterns like:

Certificate pinning — verifying a specific certificate fingerprint
Custom trust-domain validation — e.g., SAN-URI extraction for SPIFFE/mesh environments
Federated root certificate stores — composing multiple trust roots from different sources

What this PR does

Adds server_cert_verifier: Option<Arc<dyn ServerCertVerifier>> to TlsOptions
Updates add_tls_to_channel to call Endpoint::tls_config_with_verifier() when the custom verifier is set
Re-exports ServerCertVerifier from the crate root for user convenience
Handles Debug impl — dyn ServerCertVerifier doesn't implement Debug, so TlsOptions gets a manual Debug impl

What this does NOT cover

ResolvesClientCert / dynamic client cert rotation — tonic 0.14 does not support injecting a pre-built Arc<rustls::ClientConfig>, so ResolvesClientCert cannot be passed through. This would require either:
- An upstream change to tonic to accept Arc<rustls::ClientConfig> directly
- Bypassing tonic's TLS config entirely to build the hyper/rustls connector manually

I scoped this PR to what tonic 0.14 supports today. If the maintainers want the full Arc<ClientConfig> passthrough, I'm happy to pursue the tonic upstream approach as a follow-up.

Design decisions

Optional field vs enum: Chose an optional field on the existing struct over an enum wrapper to avoid breaking the public API. An enum-based ClientTlsConfig could be a follow-up if preferred.
Feature-gating: Not feature-gated since tokio-rustls is already a transitive dependency via tonic. The ServerCertVerifier trait is always available when tonic's TLS features are enabled.
server_root_ca_cert ignored when verifier is set: This matches tonic's behavior — tls_config_with_verifier errors if CA certs are also configured.

Example usage

use std::sync::Arc;
use temporalio_client::{TlsOptions, ServerCertVerifier};

// Implement your custom verifier
struct MyCertPinner { /* ... */ }
impl ServerCertVerifier for MyCertPinner { /* ... */ }

let tls = TlsOptions {
    server_cert_verifier: Some(Arc::new(MyCertPinner { /* ... */ })),
    domain: Some("my-temporal.example.com".to_string()),
    ..Default::default()
};

Testing

cargo check — full workspace builds clean
cargo fmt --all — no formatting changes
cargo lint — no warnings
cargo test -p temporalio-client — 112 tests + 1 doctest pass

Sushisource · 2026-05-19T21:48:45Z

+        // When a custom verifier is set, server_root_ca_cert is ignored because
+        // tonic's tls_config_with_verifier replaces the default WebPKI verifier entirely.
+        if tls_cfg.server_cert_verifier.is_none() {


We should probably just have these options be mutually exclusive (in the sense that this can just produce an error) rather than silently ignoring.

Sushisource · 2026-05-19T21:51:11Z

+        #[test]
+        fn tls_options_with_verifier_default_is_none() {
+            let opts = TlsOptions::default();
+            assert!(opts.server_cert_verifier.is_none());
+        }
+
+        #[test]
+        fn tls_options_with_verifier_clone() {
+            let opts = TlsOptions {
+                server_cert_verifier: Some(Arc::new(MockVerifier)),
+                ..Default::default()
+            };
+            let cloned = opts.clone();
+            assert!(cloned.server_cert_verifier.is_some());
+        }
+
+        #[test]
+        fn tls_options_debug_shows_custom_when_verifier_set() {
+            let opts = TlsOptions {
+                server_cert_verifier: Some(Arc::new(MockVerifier)),
+                domain: Some("test.example.com".to_string()),
+                ..Default::default()
+            };
+            let debug_str = format!("{opts:?}");
+            assert!(
+                debug_str.contains("<custom>"),
+                "Debug output should show <custom> for verifier, got: {debug_str}"
+            );
+            assert!(
+                debug_str.contains("test.example.com"),
+                "Debug output should show domain, got: {debug_str}"
+            );
+        }
+
+        #[test]
+        fn tls_options_debug_shows_none_when_no_verifier() {
+            let opts = TlsOptions::default();
+            let debug_str = format!("{opts:?}");
+            assert!(
+                debug_str.contains("server_cert_verifier: None"),
+                "Debug output should show None for verifier, got: {debug_str}"
+            );
+        }


I think these can all just be dropped, very obvious tests.

Sushisource · 2026-05-19T21:56:37Z

+    /// This is useful for:
+    /// - Certificate pinning
+    /// - Custom trust-domain validation (e.g., SAN-URI extraction)
+    /// - Federated root certificate stores


I think we need to include some warning here about the fact that this allows you to make dangerously insecure connections

Sushisource · 2026-05-19T21:57:05Z

 pub use retry::RetryOptions;
+/// Re-export the `ServerCertVerifier` trait so that users can implement custom TLS
+/// server certificate verification without depending on `tokio-rustls` directly.
+pub use tokio_rustls::rustls::client::danger::ServerCertVerifier;


I'm not sure I want to re-export this specifically because this import path is communicating some important information with the danger segment. I think a little friction here isn't a bad thing.

Add an optional `server_cert_verifier` field to `TlsOptions` that accepts an `Arc<dyn ServerCertVerifier>`. When set, the client uses tonic's `tls_config_with_verifier()` to replace the default WebPKI certificate verification. This enables: - Certificate pinning - Custom trust-domain validation (e.g., SAN-URI extraction) - Federated root certificate stores When a custom verifier is set, `server_root_ca_cert` is ignored (since tonic enforces mutual exclusion), while `domain` is still respected for the `:authority` header / origin override. The `ServerCertVerifier` trait is re-exported from the crate root for convenience, so users don't need to depend on `tokio-rustls` directly. Note: This does not cover `ResolvesClientCert` (dynamic client cert rotation), which would require either bypassing tonic's TLS config or upstream changes to tonic. See discussion in the linked issue. Closes temporalio#1248

- Return InvalidConfig error when both server_root_ca_cert and server_cert_verifier are set (instead of silently ignoring) - Add WARNING doc comment about insecure connections - Move ServerCertVerifier re-export to pub mod danger to preserve the danger signal in the import path - Drop trivial tests per reviewer request

Sushisource · 2026-05-20T16:37:52Z

@brucearctor Thanks again! Looks like there's one small rustfmt needed.

By the way, you've been making a lot of useful contributions and we really appreciate that. We have a program for highlighting top contributors, we can ship you some swag or something too. I didn't immediately see you in our community Slack. If you join, you can DM me and we can set it up! https://t.mp/slack

Alternatively feel free to find me on LinkedIn and send me a message there too. Thanks!

brucearctor requested a review from a team as a code owner May 14, 2026 03:25

brucearctor force-pushed the feat/rustls-client-config branch from 4946144 to d3f3150 Compare May 14, 2026 03:42

Sushisource reviewed May 19, 2026

View reviewed changes

brucearctor added 2 commits May 19, 2026 18:34

brucearctor force-pushed the feat/rustls-client-config branch from f25841b to ef49309 Compare May 20, 2026 01:35

Sushisource reviewed May 20, 2026

View reviewed changes

Comment thread crates/client/src/lib.rs Outdated

Sushisource approved these changes May 20, 2026

View reviewed changes

Change module docstring

6e766f5

brucearctor added 2 commits May 21, 2026 18:26

style: cargo fmt --all

6566946

Merge branch 'main' into feat/rustls-client-config

2dea6f6

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(client): support custom ServerCertVerifier in TlsOptions#1271

feat(client): support custom ServerCertVerifier in TlsOptions#1271
brucearctor wants to merge 5 commits into
temporalio:mainfrom
brucearctor:feat/rustls-client-config

brucearctor commented May 14, 2026

Uh oh!

Sushisource May 19, 2026

Uh oh!

Sushisource May 19, 2026

Uh oh!

Sushisource May 19, 2026

Uh oh!

Sushisource May 19, 2026

Uh oh!

Uh oh!

Sushisource commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

brucearctor commented May 14, 2026

Summary

Motivation

What this PR does

What this does NOT cover

Design decisions

Example usage

Testing

Uh oh!

Sushisource May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Sushisource May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Sushisource May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Sushisource May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Sushisource commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants