Secure Orleans connections with TLS

Orleans can protect client-to-silo and silo-to-silo connections with Transport Layer Security (TLS). TLS encrypts traffic and authenticates the endpoint acting as the TLS server. Mutual TLS (mTLS) additionally requires and authenticates the endpoint acting as the TLS client.

Important

RemoteCertificateMode defaults to RequireCertificate. On a silo’s inbound connections, this default requires the connecting silo or Orleans client to present a certificate. To configure server-authenticated TLS without client certificates, explicitly set it to NoCertificate on every silo.

Install Microsoft.Orleans.Connections.Security in every silo and client process.

Choose an authentication model

Model	Inbound silo policy	Outbound local-certificate policy	Typical boundary
Server-authenticated TLS	RemoteCertificateMode = NoCertificate	ClientCertificateMode = NoCertificate	Clients already authenticate at an application gateway or another trusted layer
mTLS	RemoteCertificateMode = RequireCertificate (the default)	ClientCertificateMode = RequireCertificate	Direct connections across a network where both workloads need cryptographic identity

The two similarly named options apply at different stages:

• RemoteCertificateMode controls whether the remote endpoint must present a certificate. In server middleware, RequireCertificate requires a certificate from an inbound Orleans client or silo, AllowCertificate requests one but permits none, and NoCertificate doesn’t request one. Silo configuration uses this same value for outbound middleware; the TLS server still presents a certificate and platform validation authenticates it when no custom callback is installed.
• ClientCertificateMode controls selection of the local client certificate in client middleware. On a silo, it applies when the silo initiates a silo-to-silo connection. On an Orleans client, it applies when the client initiates a gateway connection. It doesn’t control inbound silo behavior.

ClientCertificateMode defaults to AllowCertificate: a configured local certificate is sent when it’s valid for client authentication, but a missing or unsuitable local certificate is tolerated. Setting it to RequireCertificate makes the outbound requirement explicit and fails configuration or connection setup when an appropriate local certificate isn’t available.

Every silo both accepts and initiates connections. For mTLS, a silo certificate therefore needs the Server Authentication extended key usage (EKU) for inbound connections and the Client Authentication EKU for outbound connections. For server-authenticated TLS, the silo certificate only needs Server Authentication. An Orleans client certificate used for mTLS needs Client Authentication. Certificate identity, issuance, and trust should reflect workload roles rather than reusing one certificate and private key across the cluster.

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 X509Certificate2 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:

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();
}

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 CurrentUser or LocalMachine 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 LoadPkcs12FromFile:

public static X509Certificate2 LoadPkcs12Certificate(
    string certificatePath,
    ReadOnlySpan<char> certificatePassword)
{
    return X509CertificateLoader.LoadPkcs12FromFile(
        certificatePath,
        certificatePassword);
}

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.

var builder = Host.CreateApplicationBuilder();

builder.UseOrleans(siloBuilder =>
{
    siloBuilder
        .UseLocalhostClustering()
        .UseTls(serverCertificate, options =>
        {
            options.RemoteCertificateMode =
                RemoteCertificateMode.NoCertificate;
            options.ClientCertificateMode =
                RemoteCertificateMode.NoCertificate;
            options.OnAuthenticateAsClient = (_, sslOptions) =>
            {
                sslOptions.TargetHost = "orleans.example.net";
                sslOptions.CertificateRevocationCheckMode =
                    X509RevocationMode.Online;
            };
        });
});

return builder.Build();

Configure an Orleans client without a local certificate:

var builder = Host.CreateApplicationBuilder();

builder.UseOrleansClient(clientBuilder =>
{
    clientBuilder
        .UseLocalhostClustering()
        .UseTls(options =>
        {
            options.RemoteCertificateMode =
                RemoteCertificateMode.RequireCertificate;
            options.ClientCertificateMode =
                RemoteCertificateMode.NoCertificate;
            options.OnAuthenticateAsClient = (_, sslOptions) =>
            {
                sslOptions.TargetHost = "orleans.example.net";
                sslOptions.CertificateRevocationCheckMode =
                    X509RevocationMode.Online;
            };
        });
});

return builder.Build();

TargetHost must match a DNS Subject Alternative Name (SAN) on the server certificate. Use the stable service name clients use to reach the silos, not an arbitrary certificate subject.

Configure mutual TLS

For mTLS, silos require a certificate from every inbound Orleans client or silo and require a local client certificate for every outbound silo-to-silo connection:

var builder = Host.CreateApplicationBuilder();

builder.UseOrleans(siloBuilder =>
{
    siloBuilder
        .UseLocalhostClustering()
        .UseTls(siloCertificate, options =>
        {
            options.RemoteCertificateMode =
                RemoteCertificateMode.RequireCertificate;
            options.ClientCertificateMode =
                RemoteCertificateMode.RequireCertificate;
            options.OnAuthenticateAsClient = (_, sslOptions) =>
            {
                sslOptions.TargetHost = "orleans.example.net";
                sslOptions.CertificateRevocationCheckMode =
                    X509RevocationMode.Online;
            };
            options.CheckCertificateRevocation = true;
        });
});

return builder.Build();

var builder = Host.CreateApplicationBuilder();

builder.UseOrleansClient(clientBuilder =>
{
    clientBuilder
        .UseLocalhostClustering()
        .UseTls(clientCertificate, options =>
        {
            options.RemoteCertificateMode =
                RemoteCertificateMode.RequireCertificate;
            options.ClientCertificateMode =
                RemoteCertificateMode.RequireCertificate;
            options.OnAuthenticateAsClient = (_, sslOptions) =>
            {
                sslOptions.TargetHost = "orleans.example.net";
                sslOptions.CertificateRevocationCheckMode =
                    X509RevocationMode.Online;
            };
        });
});

return builder.Build();

The default platform validation applies when RemoteCertificateValidation isn’t set. If you provide that callback, keep normal chain and name checks and add only the deployment-specific policy you require. A callback which returns true unconditionally defeats peer authentication.

Warning

AllowAnyRemoteCertificate is suitable only for isolated local development. It accepts any remote certificate and therefore doesn’t protect against impersonation or an active man-in-the-middle.

Establish certificate trust

Treat these as separate trust decisions:

• Clients trust silos: The issuing CA for silo server certificates is trusted by Orleans clients. The certificate SAN matches TargetHost.
• Silos trust clients: For mTLS, the issuing CA for client certificates is trusted by every silo. Use a private CA or an additional validation policy when possession of an arbitrary public certificate isn’t sufficient authorization.
• Silos trust silos: Each silo validates the server certificate on outbound silo-to-silo connections. With mTLS, each silo also presents a client-authentication certificate.

Keep trust stores narrow. Don’t place unrelated public or corporate roots in a workload-specific trust bundle when any certificate from those roots would be accepted as a cluster identity. Network policy should still restrict silo and gateway ports to expected peers.

Protocols and revocation

SslProtocols defaults to TLS 1.2 and TLS 1.3. Retain those defaults unless an interoperability or policy requirement calls for a narrower set. Orleans doesn’t enable TLS 1.0 or TLS 1.1 by default.

Set CheckCertificateRevocation to check remote certificates on inbound silo connections. For outbound connections, set CertificateRevocationCheckMode in OnAuthenticateAsClient. Before enabling revocation checks, verify that every workload can reach the certificate revocation list (CRL) or Online Certificate Status Protocol (OCSP) service and decide how outages should affect availability.

Rotate certificates

Plan rotation before deployment:

1. Issue the replacement certificate with the same required names and EKUs.
2. Distribute the new issuing chain to trust stores before any endpoint presents the new certificate.
3. Make both old and new chains valid during an overlap window.
4. Restart processes with the replacement certificate, or use LocalServerCertificateSelector and LocalClientCertificateSelector to select certificates dynamically.
5. Confirm new connections use the replacement, then remove the old certificate and obsolete trust roots.

Certificate selectors are called during authentication, but certificate loading, caching, disposal, and refresh are application responsibilities. Test rotation under normal reconnect and silo restart behavior. Alert on certificate expiration well before the overlap window closes.

Production checklist

• Give private-key files or key-store entries only to the workload identity that needs them.
• Prefer separate certificates per workload or instance over one exported cluster-wide private key.
• Validate SANs, EKUs, chain trust, validity, and revocation behavior.
• For server-authenticated TLS, set RemoteCertificateMode and ClientCertificateMode to NoCertificate on silos.
• For mTLS, set RemoteCertificateMode and ClientCertificateMode to RequireCertificate on silos and configure a client-authentication certificate on every connecting Orleans client.
• Protect gateway and silo ports with network policy even when TLS is enabled.
• Keep clocks synchronized because certificate validity checks depend on time.
• Monitor TLS handshake failures and certificate expiration; don’t log private keys or certificate passwords.
• Store PFX passwords in a secret store rather than source or ordinary configuration files.

See also

• Orleans security
• Network hardening
• TlsOptions
• UseTls
• Client configuration
• Server configuration
• .NET TLS/SSL best practices
• Orleans Transport Layer Security (TLS) sample