From a34c9a738cbb44cfbeebc3f9efe3de1f594fda9b Mon Sep 17 00:00:00 2001 From: Reuben Bond Date: Sat, 8 Aug 2026 07:48:03 -0700 Subject: [PATCH] docs: restore TLS certificate loading guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../csharp/SiloExample/Program.cs | 44 +++++++++++++++++++ .../docs/host/transport-layer-security.md | 24 +++++++++- 2 files changed, 67 insertions(+), 1 deletion(-) diff --git a/docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs b/docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs index bfff407288d..96c75624662 100644 --- a/docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs +++ b/docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs @@ -7,6 +7,50 @@ internal static class TlsExamples { + // + public static IHost CreateServerAuthenticatedSiloFromStore() + { + var builder = Host.CreateApplicationBuilder(); + + builder.UseOrleans(siloBuilder => + { + siloBuilder + .UseLocalhostClustering() + .UseTls( + StoreName.My, + "orleans.example.net", + allowInvalid: false, + StoreLocation.CurrentUser, + options => + { + options.RemoteCertificateMode = + RemoteCertificateMode.NoCertificate; + options.ClientCertificateMode = + RemoteCertificateMode.NoCertificate; + options.OnAuthenticateAsClient = (_, sslOptions) => + { + sslOptions.TargetHost = "orleans.example.net"; + sslOptions.CertificateRevocationCheckMode = + X509RevocationMode.Online; + }; + }); + }); + + return builder.Build(); + } + // + + // + public static X509Certificate2 LoadPkcs12Certificate( + string certificatePath, + ReadOnlySpan certificatePassword) + { + return X509CertificateLoader.LoadPkcs12FromFile( + certificatePath, + certificatePassword); + } + // + public static IHost CreateServerAuthenticatedSilo(X509Certificate2 serverCertificate) { // diff --git a/docs/site/src/content/docs/host/transport-layer-security.md b/docs/site/src/content/docs/host/transport-layer-security.md index 3330fe45c66..d8f3559ba10 100644 --- a/docs/site/src/content/docs/host/transport-layer-security.md +++ b/docs/site/src/content/docs/host/transport-layer-security.md @@ -1,7 +1,7 @@ --- title: Secure Orleans connections with TLS description: Configure server-authenticated TLS or mutual TLS for Orleans silo and client connections. -ms.date: 08/02/2026 +ms.date: 08/08/2026 ms.topic: how-to --- @@ -32,6 +32,28 @@ Every silo both accepts and initiates connections. For mTLS, a silo certificate TLS provides confidentiality, integrity, and certificate-based peer authentication for the Orleans transport. It doesn't authorize grain calls, isolate tenants, protect data after either process receives it, or secure membership/storage provider traffic unless those providers are separately configured. Compromise of a trusted certificate or private key can let an attacker impersonate that workload. +## Load the local certificate + +The `UseTls` overloads accept an with an accessible private key. Load it from the certificate source supported by your deployment, and keep it undisposed for the lifetime of the Orleans host. + +### Operating system certificate store + +When the workload certificate is installed in an operating system certificate store, Orleans can load it by subject name. The following silo example searches the current user's Personal (`My`) store, requires the certificate to be currently valid, and configures server-authenticated TLS: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/SiloExample/Program.cs" id="CertificateStore"::: + +Set `allowInvalid` to `false` outside isolated development environments. The store overload requires an accessible private key and selects a certificate suitable for the workload role. Ensure the selected certificate has every EKU required by the authentication model; in particular, a silo certificate used for mTLS needs both Server Authentication and Client Authentication. + +Choose or according to the identity which runs the process, and grant that identity access to the private key. If a subject name can match more than one deployment certificate, load the intended certificate explicitly or use a certificate selector with an issuer, thumbprint, or other deployment-specific identity check. + +### PKCS#12/PFX file + +For a PKCS#12/PFX file, use : + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/SiloExample/Program.cs" id="LoadPkcs12Certificate"::: + +Obtain the path and password from protected configuration or a secret provider rather than source code or ordinary configuration files. Restrict access to the file and its private key to the workload identity. Pass the returned certificate to the appropriate silo or client `UseTls` configuration shown in the following sections, keep it alive while the host runs, and dispose it after the host stops. + ## Configure server-authenticated TLS The silo presents a server certificate. Connecting clients and silos validate its chain, validity period, EKU, and DNS name but don't present a client certificate. The silo configuration explicitly disables remote certificates for inbound connections and local client certificates for outbound silo-to-silo connections.