Add Orleans Transport Layer Security (TLS) documentation

docs/orleans/host/snippets/transport-layer-security/.gitignore

@@ -0,0 +1,2 @@
+bin/
+obj/

docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/ClientExample.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Orleans.Client" Version="9.2.1" />
+    <PackageReference Include="Microsoft.Orleans.Connections.Security" Version="9.2.1" />
+  </ItemGroup>
+
+</Project>

docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/Program.cs

@@ -0,0 +1,87 @@
+using System.Security.Authentication;
+using System.Security.Cryptography.X509Certificates;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Orleans.Connections.Security;
+using Orleans.Hosting;
+
+// <BasicClientTlsConfiguration>
+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();
+// </BasicClientTlsConfiguration>
+
+class ClientDevelopmentExample
+{
+    public static async Task ConfigureDevelopmentTls()
+    {
+        // <ClientDevelopmentTlsConfiguration>
+        var isDevelopment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development";
+
+        using IHost host = Host.CreateDefaultBuilder()
+            .UseOrleansClient(builder =>
+            {
+                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();
+        // </ClientDevelopmentTlsConfiguration>
+    }
+}
+
+class ClientCertificateExample
+{
+    public static async Task ConfigureTlsWithCertificate()
+    {
+        // <ClientCertificateTlsConfiguration>
+        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();
+        // </ClientCertificateTlsConfiguration>
+    }
+}

docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs

@@ -0,0 +1,135 @@
+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;
+
+// <BasicTlsConfiguration>
+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();
+// </BasicTlsConfiguration>
+
+class DevelopmentExample
+{
+    public static async Task ConfigureDevelopmentTls()
+    {
+        // <DevelopmentTlsConfiguration>
+        var isDevelopment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development";
+
+        using IHost host = Host.CreateDefaultBuilder()
+            .UseOrleans(builder =>
+            {
+                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();
+        // </DevelopmentTlsConfiguration>
+    }
+}
+
+class CertificateExample
+{
+    public static async Task ConfigureTlsWithCertificate()
+    {
+        // <CertificateTlsConfiguration>
+        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();
+        // </CertificateTlsConfiguration>
+    }
+}
+
+class AdvancedExample
+{
+    public static async Task ConfigureAdvancedTls()
+    {
+        // <AdvancedTlsConfiguration>
+        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();
+        // </AdvancedTlsConfiguration>
+    }
+}

docs/orleans/host/snippets/transport-layer-security/csharp/SiloExample/SiloExample.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Orleans.Connections.Security" Version="9.2.1" />
+    <PackageReference Include="Microsoft.Orleans.Server" Version="9.2.1" />
+  </ItemGroup>
+
+</Project>

docs/orleans/host/snippets/transport-layer-security/vb/ClientExample/ClientExample.vbproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <RootNamespace>ClientExample</RootNamespace>
+    <TargetFramework>net9.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Orleans.Client" Version="9.2.1" />
+    <PackageReference Include="Microsoft.Orleans.Connections.Security" Version="9.2.1" />
+  </ItemGroup>
+
+</Project>

docs/orleans/host/snippets/transport-layer-security/vb/ClientExample/Program.vb

@@ -0,0 +1,85 @@
+Imports System
+
+Imports System.Security.Authentication
+Imports System.Security.Cryptography.X509Certificates
+Imports Microsoft.Extensions.Hosting
+Imports Microsoft.Extensions.Logging
+Imports Orleans.Connections.Security
+Imports Orleans.Hosting
+
+Module Program
+    ' <BasicClientTlsConfiguration>
+    Sub Main(args As String())
+        Dim hostBuilder = Microsoft.Extensions.Hosting.Host.CreateDefaultBuilder(args)
+        hostBuilder.UseOrleansClient(Sub(builder)
+                                         builder _
+                                             .UseLocalhostClustering() _
+                                             .UseTls(StoreName.My, "my-certificate-subject", allowInvalid:=False, StoreLocation.CurrentUser,
+                                                 Sub(options)
+                                                     options.OnAuthenticateAsServer = Sub(connection, sslOptions)
+                                                                                          sslOptions.ClientCertificateRequired = True
+                                                                                      End Sub
+                                                 End Sub)
+                                     End Sub)
+        hostBuilder.ConfigureLogging(Sub(logging) logging.AddConsole())
+        Dim host = hostBuilder.Build()
+
+        host.RunAsync().Wait()
+    End Sub
+    ' </BasicClientTlsConfiguration>
+End Module
+
+Class ClientDevelopmentExample
+    ' <ClientDevelopmentTlsConfiguration>
+    Public Shared Async Function ConfigureDevelopmentTls() As Task
+        Dim isDevelopment As Boolean = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") = "Development"
+
+        Dim hostBuilder = Microsoft.Extensions.Hosting.Host.CreateDefaultBuilder()
+        hostBuilder.UseOrleansClient(Sub(builder)
+                                         builder _
+                                             .UseLocalhostClustering() _
+                                             .UseTls(StoreName.My, "localhost", allowInvalid:=isDevelopment, StoreLocation.CurrentUser,
+                                                 Sub(options)
+                                                     If isDevelopment Then
+                                                         options.AllowAnyRemoteCertificate()
+                                                     End If
+
+                                                     options.OnAuthenticateAsServer = Sub(connection, sslOptions)
+                                                                                          sslOptions.ClientCertificateRequired = True
+                                                                                      End Sub
+                                                 End Sub)
+                                     End Sub)
+        hostBuilder.ConfigureLogging(Sub(logging) logging.AddConsole())
+        Dim host = hostBuilder.Build()
+
+        Await host.RunAsync()
+        host.Dispose()
+    End Function
+    ' </ClientDevelopmentTlsConfiguration>
+End Class
+
+Class ClientCertificateExample
+    ' <ClientCertificateTlsConfiguration>
+    Public Shared Async Function ConfigureTlsWithCertificate() As Task
+        Dim cert As X509Certificate2 = X509CertificateLoader.LoadPkcs12FromFile("path/to/certificate.pfx", "password")
+
+        Dim hostBuilder = Microsoft.Extensions.Hosting.Host.CreateDefaultBuilder()
+        hostBuilder.UseOrleansClient(Sub(builder)
+                                         builder _
+                                             .UseLocalhostClustering() _
+                                             .UseTls(cert,
+                                                 Sub(options)
+                                                     options.OnAuthenticateAsServer = Sub(connection, sslOptions)
+                                                                                          sslOptions.ClientCertificateRequired = True
+                                                                                      End Sub
+                                                 End Sub)
+                                     End Sub)
+        hostBuilder.ConfigureLogging(Sub(logging) logging.AddConsole())
+        Dim host = hostBuilder.Build()
+
+        Await host.RunAsync()
+        host.Dispose()
+        cert.Dispose()
+    End Function
+    ' </ClientCertificateTlsConfiguration>
+End Class