feat(remote): implement mutual TLS authentication support (#7851) #7855
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…#7851) * Add mutual TLS authentication support for DotNetty transport Implements mutual TLS (mTLS) authentication as a defense-in-depth security measure for Akka.Remote TLS connections. When enabled, both client and server must present valid certificates with accessible private keys during the TLS handshake, ensuring symmetric authentication. Key Changes: - Add require-mutual-authentication config option (default: true) - Update SslSettings to include RequireMutualAuthentication property - Modify client TLS handler to provide certificate only when mutual TLS enabled - Modify server TLS handler to require and validate client certificates when enabled - Add comprehensive test suite for mutual TLS scenarios Security Benefits: - Prevents nodes with inaccessible private keys from connecting as clients - Ensures complete bidirectional authentication (not just server-side) - Works in conjunction with startup certificate validation for fail-fast behavior - Provides defense-in-depth security for production deployments Configuration: akka.remote.dot-netty.tcp.ssl { require-mutual-authentication = true # Default: secure by default } Set to false only if your environment cannot support client certificate authentication. Related: Freshdesk akkadotnet#538 - TLS certificate private key validation * Update Akka.Remote security documentation Major overhaul of the security documentation to reflect new TLS features and provide comprehensive security guidance for production deployments. Changes: - Document new startup certificate validation feature (v1.5.52+) - Document new mutual TLS authentication support (v1.5.52+) - Add detailed suppress-validation guidance with security implications - Provide Windows Certificate Store configuration examples - Include PowerShell scripts for certificate management - Add troubleshooting section for common TLS issues - Update configuration examples from insecure to secure defaults - Fix deprecated external links (Microsoft Learn, IETF, OWASP) - Add security analysis for different configuration levels - Include migration guide for upgrading to mutual TLS - Add best practices summary with 10 key recommendations - Document common pitfalls and their solutions Security improvements: - Changed example configs to use suppress-validation = false by default - Added warnings about using suppress-validation = true in production - Emphasized defense-in-depth with VPNs + TLS + mutual TLS - Documented proper self-signed certificate usage for development The documentation now provides clear guidance on: - What TLS protects against (and what it doesn't) - When to use mutual TLS vs standard TLS - How to properly configure certificates in production - How to troubleshoot common certificate permission issues Related: Freshdesk akkadotnet#538 - TLS certificate validation improvements * Add proper code samples for TLS configuration documentation - Create TlsConfigurationSample.cs with proper HOCON configuration examples - Update security.md to reference code samples using DocFX syntax - Add context explaining when TLS is needed vs optional - Remove poorly designed region tags from test file The documentation now follows Akka.NET documentation guidelines with proper code references instead of inline configuration blocks. * feat(remote): implement mutual TLS authentication support Added configurable mutual TLS (mTLS) authentication for Akka.Remote to provide bidirectional certificate validation between client and server nodes. This feature enhances security by ensuring both sides of a connection authenticate with valid certificates. Changes: - Added `require-mutual-authentication` config option (defaults to true for security-by-default) - Updated DotNettyTransport to enforce mutual TLS in both client and server pipelines - Added comprehensive test suite for mutual TLS scenarios - Updated security documentation with detailed TLS/mTLS configuration guidance - Added code samples for various TLS configurations (standard, mutual, Windows cert store) - Included Mermaid sequence diagrams for TLS vs mTLS flows (pending Mermaid support on site) The implementation ensures backward compatibility while encouraging secure defaults. When mutual TLS is disabled, the system falls back to standard server-only authentication. Related to Freshdesk ticket akkadotnet#538 * Fix markdown linting issues in security documentation * Fix remaining markdown linting issues - convert bold text to proper headings * Fix title case issues in security.md documentation - Fixed all heading title case to comply with markdownlint-rule-titlecase - Changed 'suppress-validation' to 'Suppress-Validation' in headings - Fixed error message headings to use proper title case - All CI/CD checks should now pass * Add Tailscale and ZeroTier to cSpell dictionary Added VPN provider names to the accepted words list to fix CI spellcheck failures * Address PR review feedback on mutual TLS implementation - Fixed binary compatibility by adding overloaded SslSettings constructor - Added config test to verify RequireMutualAuthentication defaults to true - Added test for mutual TLS failure when client has no certificate - Added test to verify mutual TLS can be disabled for backward compatibility - Enhanced DotNettyMutualTlsSpec with more comprehensive test scenarios * Add test for mutual TLS failure with different certificates - Generated new self-signed certificate (akka-client-cert.pfx) for testing - Modified CreateConfig to accept custom certificate paths - Added test to verify mutual TLS fails when client and server have different valid certificates - This ensures proper certificate validation in mutual TLS mode * Add client certificate for mutual TLS testing - Generated new self-signed certificate (akka-client-cert.pfx) to test scenarios where client and server have different valid certificates - Added certificate to project file as build output - Force-added certificate to git (normally ignored by .gitignore) * fixed `RemoteConfigSpec` * Fix RemoteConfigSpec and add SSL defaults test - Added new test SSL_should_have_secure_defaults_when_enabled to verify secure defaults when SSL is enabled - Removed SSL checks from non-SSL test Remoting_should_contain_correct_heliosTCP_values_in_ReferenceConf - Fixed certificate path resolution using full path - Tests now properly verify that require-mutual-authentication defaults to true and suppress-validation defaults to false * remove redundant tests * Restore DotNettySslSetupSpec and add mutual TLS Setup API test - Restored DotNettySslSetupSpec which tests SSL configuration via Setup API - This is distinct from HOCON-based configuration tested in DotNettySslSupportSpec - Added test for configuring mutual TLS via DotNettySslSetup - Enhanced TestActorSystemSetup to support mutual authentication parameter * Fix DotNettySslSetupSpec compilation errors - Removed unsupported requireMutualAuth parameter from DotNettySslSetup constructor - Updated test to combine Setup API certificate with HOCON mutual TLS configuration - Fixed shutdown method call to use correct API * Revert "Fix DotNettySslSetupSpec compilation errors" This reverts commit 6503391. * Revert "Restore DotNettySslSetupSpec and add mutual TLS Setup API test" This reverts commit b23c3cd. * Revert "remove redundant tests" This reverts commit 7a7f3ca.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
port of #7851 to
v1.5Implements mutual TLS (mTLS) authentication as a defense-in-depth security measure for Akka.Remote TLS connections. When enabled, both client and server must present valid certificates with accessible private keys during the TLS handshake, ensuring symmetric authentication.
Key Changes:
Security Benefits: