diff --git a/docs/orleans/host/snippets/transport-layer-security/.gitignore b/docs/orleans/host/snippets/transport-layer-security/.gitignore new file mode 100644 index 0000000000000..cd42ee34e873b --- /dev/null +++ b/docs/orleans/host/snippets/transport-layer-security/.gitignore @@ -0,0 +1,2 @@ +bin/ +obj/ diff --git a/docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/ClientExample.csproj b/docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/ClientExample.csproj new file mode 100644 index 0000000000000..bb87d4a076c40 --- /dev/null +++ b/docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/ClientExample.csproj @@ -0,0 +1,15 @@ + + + + Exe + net9.0 + enable + enable + + + + + + + + diff --git a/docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/Program.cs b/docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/Program.cs new file mode 100644 index 0000000000000..e6fac4f7cc2cc --- /dev/null +++ b/docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/Program.cs @@ -0,0 +1,89 @@ +using System.Security.Authentication; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using Orleans.Connections.Security; +using Orleans.Hosting; + +// +using IHost host = Host.CreateDefaultBuilder(args) + .UseOrleansClient(builder => + { + builder + .UseLocalhostClustering() + .UseTls(StoreName.My, "my-certificate-subject", allowInvalid: false, StoreLocation.CurrentUser, options => + { + options.OnAuthenticateAsServer = (connection, sslOptions) => + { + sslOptions.ClientCertificateRequired = true; + }; + }); + }) + .ConfigureLogging(logging => logging.AddConsole()) + .Build(); + +await host.RunAsync(); +// + +class ClientDevelopmentExample +{ + public static async Task ConfigureDevelopmentTls() + { + // + var hostBuilder = Host.CreateDefaultBuilder(); + + using IHost host = hostBuilder + .UseOrleansClient((context, builder) => + { + var isDevelopment = context.HostingEnvironment.IsDevelopment(); + + builder + .UseLocalhostClustering() + .UseTls(StoreName.My, "localhost", allowInvalid: isDevelopment, StoreLocation.CurrentUser, options => + { + if (isDevelopment) + { + options.AllowAnyRemoteCertificate(); + } + + options.OnAuthenticateAsServer = (connection, sslOptions) => + { + sslOptions.ClientCertificateRequired = true; + }; + }); + }) + .ConfigureLogging(logging => logging.AddConsole()) + .Build(); + + await host.RunAsync(); + // + } +} + +class ClientCertificateExample +{ + public static async Task ConfigureTlsWithCertificate() + { + // + using var cert = X509CertificateLoader.LoadPkcs12FromFile("path/to/certificate.pfx", "password"); + + using IHost host = Host.CreateDefaultBuilder() + .UseOrleansClient(builder => + { + builder + .UseLocalhostClustering() + .UseTls(cert, options => + { + options.OnAuthenticateAsServer = (connection, sslOptions) => + { + sslOptions.ClientCertificateRequired = true; + }; + }); + }) + .ConfigureLogging(logging => logging.AddConsole()) + .Build(); + + await host.RunAsync(); + // + } +} diff --git a/docs/orleans/host/snippets/transport-layer-security/csharp/README.md b/docs/orleans/host/snippets/transport-layer-security/csharp/README.md new file mode 100644 index 0000000000000..0888a35bdc7d2 --- /dev/null +++ b/docs/orleans/host/snippets/transport-layer-security/csharp/README.md @@ -0,0 +1,27 @@ +# Transport Layer Security (TLS) Code Samples + +This directory contains code samples demonstrating how to configure Transport Layer Security (TLS) in Orleans applications. + +## Projects + +- **SiloExample**: Demonstrates TLS configuration for Orleans silos +- **ClientExample**: Demonstrates TLS configuration for Orleans clients + +## Building the Samples + +To build all samples: + +```bash +dotnet build transport-layer-security.sln +``` + +To build individual projects: + +```bash +dotnet build SiloExample/SiloExample.csproj +dotnet build ClientExample/ClientExample.csproj +``` + +## Note + +These samples are intended for documentation purposes and demonstrate various TLS configuration scenarios including basic setup, development environments, certificate files, and advanced configurations. diff --git a/docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs b/docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs new file mode 100644 index 0000000000000..d1a05cf59bcf0 --- /dev/null +++ b/docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs @@ -0,0 +1,137 @@ +using System.Net; +using System.Net.Security; +using System.Security.Authentication; +using System.Security.Cryptography.X509Certificates; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using Orleans.Connections.Security; +using Orleans.Hosting; + +// +using IHost host = Host.CreateDefaultBuilder(args) + .UseOrleans(builder => + { + builder + .UseLocalhostClustering() + .UseTls(StoreName.My, "my-certificate-subject", allowInvalid: false, StoreLocation.CurrentUser, options => + { + options.OnAuthenticateAsClient = (connection, sslOptions) => + { + sslOptions.TargetHost = "my-certificate-subject"; + }; + }); + }) + .ConfigureLogging(logging => logging.AddConsole()) + .Build(); + +await host.RunAsync(); +// + +class DevelopmentExample +{ + public static async Task ConfigureDevelopmentTls() + { + // + var hostBuilder = Host.CreateDefaultBuilder(); + + using IHost host = hostBuilder + .UseOrleans((context, builder) => + { + var isDevelopment = context.HostingEnvironment.IsDevelopment(); + + builder + .UseLocalhostClustering() + .UseTls(StoreName.My, "localhost", allowInvalid: isDevelopment, StoreLocation.CurrentUser, options => + { + options.OnAuthenticateAsClient = (connection, sslOptions) => + { + sslOptions.TargetHost = "localhost"; + }; + + if (isDevelopment) + { + options.AllowAnyRemoteCertificate(); + } + }); + }) + .ConfigureLogging(logging => logging.AddConsole()) + .Build(); + + await host.RunAsync(); + // + } +} + +class CertificateExample +{ + public static async Task ConfigureTlsWithCertificate() + { + // + using var cert = X509CertificateLoader.LoadPkcs12FromFile("path/to/certificate.pfx", "password"); + + using IHost host = Host.CreateDefaultBuilder() + .UseOrleans(builder => + { + builder + .UseLocalhostClustering() + .UseTls(cert, options => + { + options.OnAuthenticateAsClient = (connection, sslOptions) => + { + sslOptions.TargetHost = cert.GetNameInfo(X509NameType.DnsName, false); + }; + }); + }) + .ConfigureLogging(logging => logging.AddConsole()) + .Build(); + + await host.RunAsync(); + // + } +} + +class AdvancedExample +{ + public static async Task ConfigureAdvancedTls() + { + // + using IHost host = Host.CreateDefaultBuilder() + .UseOrleans(builder => + { + builder + .UseLocalhostClustering() + .UseTls(StoreName.My, "my-certificate-subject", allowInvalid: false, StoreLocation.LocalMachine, options => + { + options.LocalServerCertificateSelector = (sender, serverName) => + { + using var store = new X509Store(StoreName.My, StoreLocation.LocalMachine); + store.Open(OpenFlags.ReadOnly); + var certs = store.Certificates.Find(X509FindType.FindBySubjectName, serverName ?? "my-certificate-subject", validOnly: true); + return certs.Count > 0 ? certs[0] : null; + }; + + options.RemoteCertificateValidation = (certificate, chain, sslPolicyErrors) => + { + if (sslPolicyErrors == SslPolicyErrors.None) + { + return true; + } + + return false; + }; + + options.OnAuthenticateAsClient = (connection, sslOptions) => + { + sslOptions.TargetHost = "my-certificate-subject"; + }; + + options.CheckCertificateRevocation = true; + }); + }) + .ConfigureLogging(logging => logging.AddConsole()) + .Build(); + + await host.RunAsync(); + // + } +} diff --git a/docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/SiloExample.csproj b/docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/SiloExample.csproj new file mode 100644 index 0000000000000..32d814d0e75f6 --- /dev/null +++ b/docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/SiloExample.csproj @@ -0,0 +1,15 @@ + + + + Exe + net9.0 + enable + enable + + + + + + + + diff --git a/docs/orleans/host/snippets/transport-layer-security/csharp/transport-layer-security.sln b/docs/orleans/host/snippets/transport-layer-security/csharp/transport-layer-security.sln new file mode 100644 index 0000000000000..38d7cc75364a3 --- /dev/null +++ b/docs/orleans/host/snippets/transport-layer-security/csharp/transport-layer-security.sln @@ -0,0 +1,48 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 17 +VisualStudioVersion = 17.0.31903.59 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SiloExample", "SiloExample\SiloExample.csproj", "{FEC1D74E-6879-4473-8D45-A846339B8063}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ClientExample", "ClientExample\ClientExample.csproj", "{72192298-953F-4F4E-976D-A2C38A6175CC}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Debug|x64 = Debug|x64 + Debug|x86 = Debug|x86 + Release|Any CPU = Release|Any CPU + Release|x64 = Release|x64 + Release|x86 = Release|x86 + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|Any CPU.Build.0 = Debug|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x64.ActiveCfg = Debug|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x64.Build.0 = Debug|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x86.ActiveCfg = Debug|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Debug|x86.Build.0 = Debug|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Release|Any CPU.ActiveCfg = Release|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Release|Any CPU.Build.0 = Release|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x64.ActiveCfg = Release|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x64.Build.0 = Release|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x86.ActiveCfg = Release|Any CPU + {FEC1D74E-6879-4473-8D45-A846339B8063}.Release|x86.Build.0 = Release|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|Any CPU.Build.0 = Debug|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x64.ActiveCfg = Debug|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x64.Build.0 = Debug|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x86.ActiveCfg = Debug|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Debug|x86.Build.0 = Debug|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Release|Any CPU.ActiveCfg = Release|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Release|Any CPU.Build.0 = Release|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x64.ActiveCfg = Release|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x64.Build.0 = Release|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x86.ActiveCfg = Release|Any CPU + {72192298-953F-4F4E-976D-A2C38A6175CC}.Release|x86.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection +EndGlobal diff --git a/docs/orleans/host/transport-layer-security.md b/docs/orleans/host/transport-layer-security.md new file mode 100644 index 0000000000000..2104e4ad77712 --- /dev/null +++ b/docs/orleans/host/transport-layer-security.md @@ -0,0 +1,126 @@ +--- +title: Orleans Transport Layer Security (TLS) +description: Learn how to configure Transport Layer Security (TLS) and mutual TLS (mTLS) in .NET Orleans to secure network communication between hosts. +ms.date: 10/28/2025 +ms.topic: how-to +ai-usage: ai-assisted +--- + +# Orleans Transport Layer Security (TLS) + +Transport Layer Security (TLS) is a cryptographic protocol that secures network communication between Orleans silos and clients. Configure TLS to implement mutual authentication (mTLS) and encrypt data in transit, protecting your Orleans deployment from unauthorized access and eavesdropping. + +## Prerequisites + +Before configuring TLS, ensure you have: + +- An Orleans application with the [Microsoft.Orleans.Server](https://www.nuget.org/packages/Microsoft.Orleans.Server) NuGet package installed for silos. +- The [Microsoft.Orleans.Client](https://www.nuget.org/packages/Microsoft.Orleans.Client) NuGet package installed for clients. +- The [Microsoft.Orleans.Connections.Security](https://www.nuget.org/packages/Microsoft.Orleans.Connections.Security) NuGet package installed for both silos and clients. +- A valid X.509 certificate for authentication, either in the Windows certificate store or as a file. + +## Configure TLS on silos + +To enable TLS on an Orleans silo, use the extension method. This method provides several overloads for different certificate configuration scenarios. + +### Basic TLS configuration + +The following example shows how to configure TLS using a certificate from the Windows certificate store: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/SiloExample/Program.cs" id="BasicTlsConfiguration"::: + +In the preceding code: + +- The `StoreName.My` parameter specifies the certificate store location (Personal certificates). +- The `"my-certificate-subject"` parameter identifies the certificate by its subject name. +- The `allowInvalid: false` parameter ensures that only valid certificates are accepted in production. +- The `StoreLocation.CurrentUser` parameter specifies the certificate store scope. +- The `OnAuthenticateAsClient` callback sets the target host for client authentication. + +### Development environment configuration + +For development and testing, you might need to use self-signed certificates. The following example shows how to configure TLS with relaxed validation for development: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/SiloExample/Program.cs" id="DevelopmentTlsConfiguration"::: + +In the preceding code: + +- The `context.HostingEnvironment.IsDevelopment()` method checks if the application is running in a development environment. +- The method disables certificate validation in development. + +> [!WARNING] +> Never use `AllowAnyRemoteCertificate()` or `allowInvalid: true` in production deployments. These settings disable important security checks and expose your application to security vulnerabilities. + +### Certificate file configuration + +If you have a certificate file instead of using the certificate store, configure TLS as shown in the following example: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/SiloExample/Program.cs" id="CertificateTlsConfiguration"::: + +In the preceding code: + +- The method loads a certificate from a PKCS#12 file (PFX format). +- The certificate is passed directly to the `UseTls` method. + +### Advanced TLS configuration + +For production deployments, you might need more control over certificate validation and protocol selection. The following example demonstrates advanced TLS configuration: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/SiloExample/Program.cs" id="AdvancedTlsConfiguration"::: + +In the preceding code: + +- The callback dynamically selects the appropriate server certificate. +- The callback provides custom validation logic for remote certificates. +- The property enables certificate revocation checking. + +## Configure TLS on clients + +Orleans clients require similar TLS configuration to securely connect to TLS-enabled silos. + +### Basic client TLS configuration + +The following example shows how to configure TLS on an Orleans client: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/ClientExample/Program.cs" id="BasicClientTlsConfiguration"::: + +In the preceding code: + +- The extension method configures TLS for the client. +- The callback configures server authentication options. +- The `ClientCertificateRequired` property enables mutual TLS by requiring the client to present a certificate. + +### Development client configuration + +For development environments, configure the client with relaxed validation as shown in the following example: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/ClientExample/Program.cs" id="ClientDevelopmentTlsConfiguration"::: + +### Certificate file client configuration + +Configure a client using a certificate file as shown in the following example: + +:::code language="csharp" source="./snippets/transport-layer-security/csharp/ClientExample/Program.cs" id="ClientCertificateTlsConfiguration"::: + +## Best practices + +Follow these best practices when configuring TLS in Orleans: + +- **Use the latest TLS protocol**: Always prefer TLS 1.2 or TLS 1.3 for the strongest security. Avoid TLS 1.0 and TLS 1.1, which have known vulnerabilities. +- **Let the OS choose the protocol version**: Don't explicitly set TLS protocol versions in production code. Instead, defer to operating system defaults to automatically select the best protocol. Only explicitly set protocol versions if you have a specific compatibility requirement with legacy systems. When you explicitly set protocol versions, your application can't automatically benefit from newer protocols added in future OS updates. +- **Validate certificates**: Always validate certificate chains, expiration dates, and hostname matches in production. Never use `AllowAnyRemoteCertificate()` or disable certificate validation outside of development environments. +- **Enable certificate revocation checking**: Use to verify that certificates haven't been revoked. +- **Use strong certificates**: Ensure your X.509 certificates use strong key lengths (at least 2048 bits for RSA) and are signed by a trusted Certificate Authority (CA). +- **Secure certificate storage**: Protect private keys with appropriate file permissions or by using hardware security modules (HSMs). +- **Keep certificates current**: Monitor certificate expiration dates and renew certificates before they expire. +- **Keep software updated**: Regularly update your .NET runtime and operating system to receive the latest security patches and protocol support. + +For more information on .NET TLS best practices, see [Transport Layer Security (TLS) best practices with .NET](../../framework/network-programming/tls.md) and [TLS/SSL best practices](../../core/extensions/sslstream-best-practices.md). + +## See also + +- [Client configuration](configuration-guide/client-configuration.md) +- [Server configuration](configuration-guide/server-configuration.md) +- +- +- [Orleans Transport Layer Security (TLS) sample](/samples/dotnet/samples/orleans-transport-layer-security-tls/) diff --git a/docs/orleans/toc.yml b/docs/orleans/toc.yml index dfe8f075f6811..6f3d4f43b5fd3 100644 --- a/docs/orleans/toc.yml +++ b/docs/orleans/toc.yml @@ -128,6 +128,8 @@ items: href: host/grain-directory.md - name: PowerShell client module href: host/powershell-client.md + - name: Transport Layer Security (TLS) + href: host/transport-layer-security.md - name: Configuration guide items: - name: Overview