mTLS Authentication in Spring Boot Microservices

by Adrian Machado

Mutual TLS (mTLS) is a critical security measure for microservices, ensuring two-way authentication between clients and servers. Unlike standard TLS, which only verifies the server, mTLS requires both parties to present valid certificates, creating a secure and trusted connection.

Why mTLS Matters#

• Stronger Security: Verifies both client and server identities.
• Encrypted Communication: Protects sensitive data during service-to-service interactions.
• Service Authentication: Ensures only legitimate microservices can communicate.

Key Steps to Implement mTLS in Spring Boot#

1. Generate Certificates: Use OpenSSL to create a Certificate Authority (CA) and server/client certificates.
2. Configure Spring Boot:
   • Set up keystore and truststore.
   • Update application.yml to enable mTLS with client-auth: need.
3. Client-Side Setup: Use RestTemplate or WebClient to configure SSL and load certificates.
4. Test Connections: Verify using curl or OpenSSL commands.
5. Manage Certificates: Automate renewal and monitor expiration to avoid disruptions.

mTLS is essential for securing microservices, meeting compliance requirements, and preventing unauthorized access. Proper setup and ongoing certificate management ensure a robust and secure system. For detailed steps, troubleshooting, and optimization tips, keep reading.

mTLS Setup in Spring Boot#

Here's a guide to setting up mTLS in a Spring Boot application.

Certificate Creation Steps#

You’ll need to create the required certificates using OpenSSL. Follow these steps:

1. Create Certificate Authority

Generate a private key and certificate for the Certificate Authority (CA):

# Generate CA private key
openssl genrsa -out ca.key 4096

# Create CA certificate
openssl req -new -x509 -days 365 -key ca.key -out ca.crt

2. Generate Server Certificate

Create the server certificate and sign it with the CA:

# Create server private key
openssl genrsa -out server.key 2048

# Generate CSR
openssl req -new -key server.key -out server.csr

# Sign with CA
openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

3. Create Keystore and Truststore

Set up the keystore and truststore for your server:

# Import server certificate into a keystore
keytool -import -file server.crt -alias serverCert -keystore server.keystore.jks

# Import CA certificate into a truststore
keytool -import -file ca.crt -alias caCert -keystore truststore.jks

Once the certificates are ready, configure the server for mTLS.

Server-Side mTLS Setup#

Update your Spring Boot server application configuration to enable mTLS:

server:
  port: 8443
  ssl:
    key-store: classpath:server.keystore.jks
    key-store-password: yourpassword
    key-alias: serverCert
    trust-store: classpath:truststore.jks
    trust-store-password: yourpassword
    client-auth: need

Additionally, include these properties in application.properties to enforce SSL:

security.require-ssl=true
server.ssl.enabled=true

Next, configure the client to support this setup.

Client-Side mTLS Setup#

Set up the client application to authenticate using mTLS. Below are configurations for RestTemplate and WebClient.

RestTemplate Configuration:

@Configuration
public class RestTemplateConfig {
    @Bean
    public RestTemplate restTemplate() throws Exception {
        SSLContext sslContext = SSLContextBuilder
            .create()
            .loadTrustMaterial(trustStore.getFile(), trustStorePassword)
            .loadKeyMaterial(keyStore.getFile(), keyStorePassword, keyPassword)
            .build();

        HttpClient client = HttpClients.custom()
            .setSSLContext(sslContext)
            .build();

        return new RestTemplate(new HttpComponentsClientHttpRequestFactory(client));
    }
}

WebClient Configuration:

@Bean
public WebClient webClient() {
    HttpClient httpClient = HttpClient.create()
        .secure(sslContextSpec -> sslContextSpec
            .sslContext(sslContext)
            .defaultConfiguration(SslProvider.DefaultConfigurationType.TCP)
            .handshakeTimeout(Duration.ofSeconds(30))
        );

    return WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .build();
}

Testing and Verification#

After setup, test and verify the mTLS configuration:

1. Basic Connection Test

Use curl to test the connection:

curl --cert client.crt --key client.key --cacert ca.crt https://localhost:8443/api/test

2. Certificate Validation

Validate the certificate chain using OpenSSL:

openssl s_client -connect localhost:8443 -tls1_2 -cert client.crt -key client.key -CAfile ca.crt

Common Issues and Fixes#

Here’s a quick troubleshooting guide for common mTLS issues:

mTLS Implementation Guidelines#

Certificate Lifecycle Management#

Automating certificate renewal is crucial to avoid service interruptions. Here's an example of automating certificate rotation:

@Configuration
public class CertificateRotationConfig {
    @Scheduled(cron = "0 0 1 * * ?") // Runs daily at 1 AM
    public void checkCertificateExpiration() {
        // Identify certificates expiring within 30 days
        LocalDate expirationThreshold = LocalDate.now().plusDays(30);

        // Trigger renewal if expiration is near
        if (isCertificateExpiring(expirationThreshold)) {
            renewCertificates();
        }
    }
}

To stay ahead of potential issues, set up monitoring alerts for certificate renewals:

management:
  endpoints:
    web:
      exposure:
        include: health,metrics
  health:
    ssl:
      enabled: true
      threshold: 30d # Notify 30 days before expiration

With automated renewal and alerts in place, centralize SSL settings to ensure consistent security across all services.

SSL Configuration Management#

Here's an example of configuring SSL settings programmatically:

@Configuration
public class SSLBundleConfig {
    @Bean
    public SSLBundle customSSLBundle() {
        return SSLBundle.builder()
            .withProtocol("TLS")
            .withKeyStore(keyStore())
            .withTrustStore(trustStore())
            .withCipherSuites("TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256")
            .build();
    }
}

The table below outlines recommended SSL settings for better security:

By standardizing SSL configurations, you can improve both security and performance.

Security and Speed Optimization#

Strengthen security and improve speed with hostname verification and session caching. Here's how to set it up:

@Bean
public SSLContext optimizedSSLContext() {
    return SSLContext.builder()
        .withHostnameVerifier(new StrictHostnameVerifier())
        .withSessionCacheSize(1000)
        .withSessionTimeout(300)
        .build();
}

For configuration, use the following properties:

server.ssl.session-timeout=300
server.ssl.session-cache-size=1000
server.ssl.enabled-protocols=TLSv1.3

Session caching and ticket-based resumption minimize the overhead of full handshakes, maintaining security while improving performance.

mTLS Advantages#

Two-Way Authentication#

Mutual TLS (mTLS) authentication ensures secure communication by requiring both parties to verify each other's identity. Unlike traditional TLS, which authenticates only the server, mTLS mandates that both the client and server present valid certificates.

Here's an example configuration for Spring Boot:

@Configuration
public class MTLSAuthConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) {
        return http
            .x509()
            .subjectPrincipalRegex("CN=(.*?)(?:,|$)")
            .userDetailsService(userDetailsService())
            .and()
            .build();
    }
}

This setup enforces certificate validation for all service interactions, creating a secure foundation for microservices communication.

Microservice Security#

In distributed systems, mTLS is essential for securing communication between services. By assigning each microservice a unique certificate, mTLS allows for precise access control and service isolation.

Key Security Layers of mTLS:

mTLS not only secures interactions but also helps meet strict regulatory and compliance needs.

Compliance Requirements#

With its strong authentication and encrypted communication, mTLS supports organizations in meeting data protection regulations and security standards. It provides an audit trail, protects data with end-to-end encryption, and offers detailed access control.

Integrating mTLS with tools like Zuplo's API management simplifies compliance by automating certificate management and security checks, reducing manual effort while maintaining high security standards.

Common Issues and Solutions#

SSL Error Resolution#

SSL errors usually occur due to problems with certificate validation. To identify these issues, enable SSL debug logging in your application.properties file:

logging.level.javax.net.ssl=DEBUG
logging.level.org.apache.http.wire=DEBUG

Here are some common SSL error scenarios and ways to resolve them:

After resolving these issues, review your configurations to minimize future errors.

Setup Error Prevention#

To avoid errors during mutual TLS (mTLS) setup in Spring Boot, ensure these key configurations are in place:

@Configuration
public class MTLSConfig {
    @Bean
    public SSLContext sslContext() throws Exception {
        // Validate certificate paths
        System.setProperty("javax.net.debug", "ssl,handshake");
        // Enforce strict hostname verification
        HttpsURLConnection.setDefaultHostnameVerifier(new StrictHostnameVerifier());
        return SSLContext.getDefault();
    }
}

Proactive management of certificate expiration is critical to prevent service interruptions.

Certificate Expiration Management#

To stay ahead of certificate expiration, adopt these monitoring practices:

• Set up daily checks and configure alerts at least 30 days before expiration.
• Maintain a detailed inventory of all certificates.
• Log every certificate-related event for tracking and auditing.
• Continuously monitor certificate status across all services.

These steps, combined with earlier lifecycle management strategies, help maintain secure and uninterrupted communication between services.

Simplifying mTLS Integration#

If you feel like the guide above involves a lot of work (and maintenance) we agree! That's why our API gateway includes a built-in mTLS Authentication policy making mTLS integration easier and more secure for Spring Boot microservices. It's just one of the many policies Zuplo offers to make developing APIs easier.

What is Zuplo?#

Zuplo is a programmable, OpenAPI-native API gateway that is built for developers like you. The programmability layer allows developers to design custom security measures that fit their specific needs - but we also include the most common use-cases out-of-the-box. Some key features include:

• Pre-built Security Policies: Easy-to-use, drag-and-drop controls for setting up mTLS.
• Advanced Authentication Framework: Supports mTLS alongside other authentication methods (ex. API keys, OAuth).
• Native OpenAPI Integration: Ensures your authentication methods are automatically documented so your users can follow along.

Conclusion#

Using mTLS authentication in Spring Boot microservices strengthens security by enabling two-way verification between clients and servers. Here are some of its core benefits:

• Stronger Security: Verifies both ends of the connection, ensuring trust.
• Regulatory Compliance: Helps align with strict authentication standards.
• Support for Distributed Systems: Enables secure communication across multiple microservices.

However, implementing mTLS requires careful certificate management, proper setup, and continuous upkeep. If you want to accelerate your mTLS adoption, grab time with our team of API experts to learn how Zuplo can help you do that.