Mutual TLS Authentication with Client Certificates in Java

Introduction

Mutual TLS (mTLS) authentication provides two-way security where both the client and server verify each other's identities using X.509 certificates. This creates a highly secure communication channel ideal for microservices, APIs, and enterprise systems. This guide explores how to implement mutual authentication with client certificates in Java applications.

Article: Implementing Mutual TLS Authentication with Client Certificates in Java

Mutual TLS extends standard TLS by requiring clients to present certificates that the server validates, ensuring both parties are trusted. Java's robust security APIs make it well-suited for implementing mTLS in various scenarios.

1. Mutual TLS Architecture Overview

Key Components:

Certificate Authority (CA) - Issues and signs certificates
Server Certificate - Identifies the server to clients
Client Certificate - Identifies the client to the server
Trust Stores - Store trusted CA certificates
Key Stores - Store private keys and certificates
SSL Context - Configures TLS parameters and authentication

mTLS Handshake Flow:

1. Client Hello → 2. Server Hello with Certificate → 3. Client Certificate Request 4. Client Certificate → 5. Certificate Verify → 6. Finished → Secure Communication

2. Maven Dependencies

pom.xml:

<properties> <spring-boot.version>3.1.0</spring-boot.version> <bouncycastle.version>1.76</bouncycastle.version> </properties> <dependencies> <!-- Spring Boot --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> <version>${spring-boot.version}</version> </dependency> <!-- Bouncy Castle for Crypto Operations --> <dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcpkix-jdk18on</artifactId> <version>${bouncycastle.version}</version> </dependency> <!-- HTTP Client --> <dependency> <groupId>org.apache.httpcomponents.client5</groupId> <artifactId>httpclient5</artifactId> <version>5.2.1</version> </dependency> <!-- Certificate Management --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> <version>42.6.0</version> </dependency> </dependencies>

3. Application Configuration

application.yml:

server: port: 8443 ssl: enabled: true key-store: classpath:keystore/server.p12 key-store-password: changeit key-store-type: PKCS12 key-alias: server key-password: changeit trust-store: classpath:keystore/truststore.p12 trust-store-password: changeit trust-store-type: PKCS12 client-auth: need # Options: need, want, none enabled-protocols: TLSv1.3,TLSv1.2 ciphers: TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256 app: mtls: # Certificate Validation crl-check-enabled: true ocsp-check-enabled: false certificate-expiry-warning-days: 30 # Client Certificate Mapping certificate-header: X-Client-Certificate subject-dn-header: X-Client-DN certificate-pinning-enabled: true # Security allowed-cipher-suites: - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - TLS_AES_128_GCM_SHA256 # Monitoring certificate-expiry-check-cron: "0 0 6 * * *" spring: datasource: url: jdbc:postgresql://localhost:5432/mtls_auth username: ${DB_USERNAME:postgres} password: ${DB_PASSWORD:password} jpa: hibernate: ddl-auto: update show-sql: true logging: level: com.myapp.mtls: DEBUG org.springframework.security: DEBUG

4. Certificate Domain Models

Client Certificate Entity:

package com.myapp.mtls.model; import jakarta.persistence.*; import jakarta.validation.constraints.NotNull; import java.security.cert.X509Certificate; import java.time.LocalDateTime; import java.util.HashSet; import java.util.Set; @Entity @Table(name = "client_certificates", uniqueConstraints = { @UniqueConstraint(columnNames = "serialNumber"), @UniqueConstraint(columnNames = "subjectDN") }) public class ClientCertificate { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @NotNull private String serialNumber; @NotNull private String subjectDN; private String issuerDN; private String commonName; private String organization; private String organizationalUnit; private String country; @Column(columnDefinition = "TEXT") private String certificatePem; @NotNull private LocalDateTime notBefore; @NotNull private LocalDateTime notAfter; @Enumerated(EnumType.STRING) private CertificateStatus status = CertificateStatus.ACTIVE; @ElementCollection(fetch = FetchType.EAGER) @CollectionTable(name = "certificate_roles", joinColumns = @JoinColumn(name = "certificate_id")) @Column(name = "role") private Set<String> roles = new HashSet<>(); private String clientId; private String description; @Column(name = "created_at") private LocalDateTime createdAt; @Column(name = "updated_at") private LocalDateTime updatedAt; @Column(name = "last_used_at") private LocalDateTime lastUsedAt; // Constructors public ClientCertificate() { this.createdAt = LocalDateTime.now(); this.updatedAt = LocalDateTime.now(); } public ClientCertificate(X509Certificate certificate) { this(); updateFromCertificate(certificate); } // Business Methods public void updateFromCertificate(X509Certificate certificate) { this.serialNumber = certificate.getSerialNumber().toString(); this.subjectDN = certificate.getSubjectX500Principal().getName(); this.issuerDN = certificate.getIssuerX500Principal().getName(); this.notBefore = certificate.getNotBefore().toInstant() .atZone(java.time.ZoneId.systemDefault()).toLocalDateTime(); this.notAfter = certificate.getNotAfter().toInstant() .atZone(java.time.ZoneId.systemDefault()).toLocalDateTime(); // Extract common name from subject DN this.commonName = extractCommonName(subjectDN); this.updatedAt = LocalDateTime.now(); } public boolean isActive() { return status == CertificateStatus.ACTIVE && !isExpired() && !isNotYetValid(); } public boolean isExpired() { return LocalDateTime.now().isAfter(notAfter); } public boolean isNotYetValid() { return LocalDateTime.now().isBefore(notBefore); } public boolean needsRenewal() { return notAfter.minusDays(30).isBefore(LocalDateTime.now()); } public boolean hasRole(String role) { return roles.contains(role) || roles.contains("ROLE_ADMIN"); } private String extractCommonName(String subjectDN) { // Simple extraction - in production, use a proper X500Name parser String[] parts = subjectDN.split(","); for (String part : parts) { if (part.trim().startsWith("CN=")) { return part.trim().substring(3); } } return subjectDN; } // Getters and Setters public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getSerialNumber() { return serialNumber; } public void setSerialNumber(String serialNumber) { this.serialNumber = serialNumber; } public String getSubjectDN() { return subjectDN; } public void setSubjectDN(String subjectDN) { this.subjectDN = subjectDN; } public String getIssuerDN() { return issuerDN; } public void setIssuerDN(String issuerDN) { this.issuerDN = issuerDN; } public String getCommonName() { return commonName; } public void setCommonName(String commonName) { this.commonName = commonName; } public String getOrganization() { return organization; } public void setOrganization(String organization) { this.organization = organization; } public String getOrganizationalUnit() { return organizationalUnit; } public void setOrganizationalUnit(String organizationalUnit) { this.organizationalUnit = organizationalUnit; } public String getCountry() { return country; } public void setCountry(String country) { this.country = country; } public String getCertificatePem() { return certificatePem; } public void setCertificatePem(String certificatePem) { this.certificatePem = certificatePem; } public LocalDateTime getNotBefore() { return notBefore; } public void setNotBefore(LocalDateTime notBefore) { this.notBefore = notBefore; } public LocalDateTime getNotAfter() { return notAfter; } public void setNotAfter(LocalDateTime notAfter) { this.notAfter = notAfter; } public CertificateStatus getStatus() { return status; } public void setStatus(CertificateStatus status) { this.status = status; } public Set<String> getRoles() { return roles; } public void setRoles(Set<String> roles) { this.roles = roles; } public String getClientId() { return clientId; } public void setClientId(String clientId) { this.clientId = clientId; } public String getDescription() { return description; } public void setDescription(String description) { this.description = description; } public LocalDateTime getCreatedAt() { return createdAt; } public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; } public LocalDateTime getUpdatedAt() { return updatedAt; } public void setUpdatedAt(LocalDateTime updatedAt) { this.updatedAt = updatedAt; } public LocalDateTime getLastUsedAt() { return lastUsedAt; } public void setLastUsedAt(LocalDateTime lastUsedAt) { this.lastUsedAt = lastUsedAt; } @PreUpdate public void preUpdate() { this.updatedAt = LocalDateTime.now(); } } enum CertificateStatus { ACTIVE, REVOKED, EXPIRED, SUSPENDED }

5. SSL Context Configuration

SSL Context Configuration:

package com.myapp.mtls.config; import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactory; import org.apache.hc.core5.ssl.SSLContexts; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.io.Resource; import org.springframework.util.ResourceUtils; import javax.net.ssl.*; import java.io.FileInputStream; import java.security.KeyStore; import java.security.SecureRandom; @Configuration public class SSLContextConfig { @Value("${server.ssl.key-store}") private Resource keyStoreResource; @Value("${server.ssl.key-store-password}") private String keyStorePassword; @Value("${server.ssl.trust-store}") private Resource trustStoreResource; @Value("${server.ssl.trust-store-password}") private String trustStorePassword; @Value("${server.ssl.key-alias}") private String keyAlias; @Bean public SSLContext sslContext() throws Exception { // Load server key store KeyStore keyStore = KeyStore.getInstance("PKCS12"); try (FileInputStream fis = new FileInputStream(ResourceUtils.getFile(keyStoreResource.getURL()))) { keyStore.load(fis, keyStorePassword.toCharArray()); } // Load trust store (CA certificates) KeyStore trustStore = KeyStore.getInstance("PKCS12"); try (FileInputStream fis = new FileInputStream(ResourceUtils.getFile(trustStoreResource.getURL()))) { trustStore.load(fis, trustStorePassword.toCharArray()); } // Create key manager factory KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); keyManagerFactory.init(keyStore, keyStorePassword.toCharArray()); // Create trust manager factory TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); trustManagerFactory.init(trustStore); // Create SSL context with mutual authentication SSLContext sslContext = SSLContext.getInstance("TLS"); sslContext.init( keyManagerFactory.getKeyManagers(), trustManagerFactory.getTrustManagers(), new SecureRandom() ); return sslContext; } @Bean public SSLSocketFactory sslSocketFactory(SSLContext sslContext) { return sslContext.getSocketFactory(); } @Bean public SSLConnectionSocketFactory sslConnectionSocketFactory(SSLContext sslContext) { return new SSLConnectionSocketFactory( sslContext, new String[]{"TLSv1.3", "TLSv1.2"}, null, SSLConnectionSocketFactory.getDefaultHostnameVerifier() ); } @Bean public SSLParameters sslParameters() { SSLParameters sslParameters = new SSLParameters(); sslParameters.setNeedClientAuth(true); // Require client authentication sslParameters.setWantClientAuth(true); // Request but don't require client auth sslParameters.setCipherSuites(new String[]{ "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", "TLS_AES_128_GCM_SHA256" }); sslParameters.setProtocols(new String[]{"TLSv1.3", "TLSv1.2"}); return sslParameters; } }

6. Client Certificate Authentication

Client Certificate Authentication Provider:

package com.myapp.mtls.auth; import com.myapp.mtls.model.ClientCertificate; import com.myapp.mtls.service.ClientCertificateService; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.authentication.AuthenticationProvider; import org.springframework.security.authentication.BadCredentialsException; import org.springframework.security.core.Authentication; import org.springframework.security.core.AuthenticationException; import org.springframework.security.core.authority.SimpleGrantedAuthority; import org.springframework.stereotype.Component; import java.security.cert.X509Certificate; import java.util.List; import java.util.Optional; import java.util.stream.Collectors; @Component public class ClientCertificateAuthenticationProvider implements AuthenticationProvider { private static final Logger logger = LoggerFactory.getLogger(ClientCertificateAuthenticationProvider.class); private final ClientCertificateService certificateService; public ClientCertificateAuthenticationProvider(ClientCertificateService certificateService) { this.certificateService = certificateService; } @Override public Authentication authenticate(Authentication authentication) throws AuthenticationException { if (!(authentication instanceof ClientCertificateAuthentication)) { return null; } ClientCertificateAuthentication clientCertAuth = (ClientCertificateAuthentication) authentication; X509Certificate[] clientCertificates = clientCertAuth.getClientCertificates(); if (clientCertificates == null || clientCertificates.length == 0) { throw new BadCredentialsException("No client certificate provided"); } // Use the first certificate in the chain (the client's certificate) X509Certificate clientCertificate = clientCertificates[0]; try { // Validate certificate against our database Optional<ClientCertificate> validatedCert = certificateService.validateCertificate(clientCertificate); if (validatedCert.isEmpty()) { throw new BadCredentialsException("Client certificate not authorized: " + clientCertificate.getSubjectX500Principal().getName()); } ClientCertificate certificate = validatedCert.get(); if (!certificate.isActive()) { throw new BadCredentialsException("Client certificate is not active: " + certificate.getStatus()); } // Extract authorities from certificate roles List<SimpleGrantedAuthority> authorities = certificate.getRoles().stream() .map(SimpleGrantedAuthority::new) .collect(Collectors.toList()); // Create successful authentication ClientCertificateAuthentication successfulAuth = new ClientCertificateAuthentication( clientCertificates, certificate.getSubjectDN(), authorities, certificate ); successfulAuth.setAuthenticated(true); // Update last used timestamp certificateService.updateLastUsed(certificate.getId()); logger.info("Client certificate authentication successful for: {}", certificate.getSubjectDN()); return successfulAuth; } catch (Exception e) { logger.error("Client certificate authentication failed", e); throw new BadCredentialsException("Certificate validation failed", e); } } @Override public boolean supports(Class<?> authentication) { return ClientCertificateAuthentication.class.isAssignableFrom(authentication); } }

Custom Authentication Object:

package com.myapp.mtls.auth; import com.myapp.mtls.model.ClientCertificate; import org.springframework.security.core.Authentication; import org.springframework.security.core.GrantedAuthority; import java.security.cert.X509Certificate; import java.util.Collection; import java.util.Collections; public class ClientCertificateAuthentication implements Authentication { private final X509Certificate[] clientCertificates; private final String principal; private final Collection<? extends GrantedAuthority> authorities; private final ClientCertificate clientCertificate; private boolean authenticated = false; public ClientCertificateAuthentication(X509Certificate[] clientCertificates) { this(clientCertificates, null, Collections.emptyList(), null); } public ClientCertificateAuthentication(X509Certificate[] clientCertificates, String principal, Collection<? extends GrantedAuthority> authorities, ClientCertificate clientCertificate) { this.clientCertificates = clientCertificates; this.principal = principal; this.authorities = authorities; this.clientCertificate = clientCertificate; } @Override public Collection<? extends GrantedAuthority> getAuthorities() { return authorities; } @Override public Object getCredentials() { return clientCertificates; } @Override public Object getDetails() { return clientCertificate; } @Override public Object getPrincipal() { return principal; } @Override public boolean isAuthenticated() { return authenticated; } @Override public void setAuthenticated(boolean authenticated) throws IllegalArgumentException { this.authenticated = authenticated; } @Override public String getName() { return principal; } // Custom getters public X509Certificate[] getClientCertificates() { return clientCertificates; } public ClientCertificate getClientCertificate() { return clientCertificate; } public String getSubjectDN() { return clientCertificates != null && clientCertificates.length > 0 ? clientCertificates[0].getSubjectX500Principal().getName() : null; } public String getIssuerDN() { return clientCertificates != null && clientCertificates.length > 0 ? clientCertificates[0].getIssuerX500Principal().getName() : null; } }

7. Client Certificate Filter

Certificate Extraction Filter:

package com.myapp.mtls.auth; import jakarta.servlet.FilterChain; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.web.filter.OncePerRequestFilter; import java.io.IOException; import java.security.cert.X509Certificate; public class ClientCertificateFilter extends OncePerRequestFilter { private static final Logger logger = LoggerFactory.getLogger(ClientCertificateFilter.class); @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // Extract client certificate from request X509Certificate[] clientCertificates = extractClientCertificates(request); if (clientCertificates != null && clientCertificates.length > 0) { try { // Create authentication object ClientCertificateAuthentication authentication = new ClientCertificateAuthentication(clientCertificates); // Set in security context for authentication provider to process SecurityContextHolder.getContext().setAuthentication(authentication); logger.debug("Extracted client certificate: {}", clientCertificates[0].getSubjectX500Principal().getName()); } catch (Exception e) { logger.error("Failed to process client certificate", e); SecurityContextHolder.clearContext(); } } filterChain.doFilter(request, response); } private X509Certificate[] extractClientCertificates(HttpServletRequest request) { // Try to get certificates from SSL attributes X509Certificate[] certs = (X509Certificate[]) request.getAttribute("jakarta.servlet.request.X509Certificate"); if (certs == null || certs.length == 0) { // Fallback to alternative attribute names certs = (X509Certificate[]) request.getAttribute("javax.servlet.request.X509Certificate"); } if (certs == null || certs.length == 0) { logger.debug("No client certificates found in request"); return null; } return certs; } @Override protected boolean shouldNotFilter(HttpServletRequest request) { String path = request.getRequestURI(); // Skip certificate authentication for health checks and public endpoints return path.startsWith("/actuator/health") || path.startsWith("/public/") || path.equals("/error"); } }

8. Client Certificate Service

Certificate Management Service:

package com.myapp.mtls.service; import com.myapp.mtls.model.ClientCertificate; import com.myapp.mtls.model.CertificateStatus; import com.myapp.mtls.repository.ClientCertificateRepository; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; import java.security.cert.X509Certificate; import java.time.LocalDateTime; import java.util.List; import java.util.Optional; @Service public class ClientCertificateService { private static final Logger logger = LoggerFactory.getLogger(ClientCertificateService.class); private final ClientCertificateRepository certificateRepository; public ClientCertificateService(ClientCertificateRepository certificateRepository) { this.certificateRepository = certificateRepository; } public Optional<ClientCertificate> validateCertificate(X509Certificate certificate) { String serialNumber = certificate.getSerialNumber().toString(); String subjectDN = certificate.getSubjectX500Principal().getName(); // Look up certificate by serial number and subject DN Optional<ClientCertificate> foundCert = certificateRepository .findBySerialNumberAndSubjectDN(serialNumber, subjectDN); if (foundCert.isPresent()) { ClientCertificate clientCert = foundCert.get(); // Verify certificate is active and valid if (clientCert.isActive()) { // Additional validation could include: // - Certificate chain validation // - CRL checks // - OCSP validation // - Certificate pinning return Optional.of(clientCert); } } return Optional.empty(); } @Transactional public ClientCertificate registerCertificate(X509Certificate certificate, String clientId, List<String> roles, String description) { String serialNumber = certificate.getSerialNumber().toString(); String subjectDN = certificate.getSubjectX500Principal().getName(); // Check if certificate already exists Optional<ClientCertificate> existingCert = certificateRepository .findBySerialNumberAndSubjectDN(serialNumber, subjectDN); if (existingCert.isPresent()) { throw new CertificateAlreadyExistsException( "Certificate already registered: " + subjectDN); } // Create new certificate record ClientCertificate clientCert = new ClientCertificate(certificate); clientCert.setClientId(clientId); clientCert.setRoles(roles != null ? new java.util.HashSet<>(roles) : new java.util.HashSet<>()); clientCert.setDescription(description); clientCert.setStatus(CertificateStatus.ACTIVE); return certificateRepository.save(clientCert); } @Transactional public void revokeCertificate(Long certificateId, String reason) { certificateRepository.findById(certificateId).ifPresent(certificate -> { certificate.setStatus(CertificateStatus.REVOKED); certificateRepository.save(certificate); logger.info("Certificate revoked: {} - Reason: {}", certificate.getSubjectDN(), reason); }); } @Transactional public void updateLastUsed(Long certificateId) { certificateRepository.findById(certificateId).ifPresent(certificate -> { certificate.setLastUsedAt(LocalDateTime.now()); certificateRepository.save(certificate); }); } public List<ClientCertificate> getExpiringCertificates(int daysThreshold) { LocalDateTime thresholdDate = LocalDateTime.now().plusDays(daysThreshold); return certificateRepository.findByNotAfterBeforeAndStatus(thresholdDate, CertificateStatus.ACTIVE); } public List<ClientCertificate> getRevokedCertificates() { return certificateRepository.findByStatus(CertificateStatus.REVOKED); } @Scheduled(cron = "${app.mtls.certificate-expiry-check-cron:0 0 6 * * *}") @Transactional public void expireCertificates() { LocalDateTime now = LocalDateTime.now(); List<ClientCertificate> expiredCerts = certificateRepository .findByNotAfterBeforeAndStatus(now, CertificateStatus.ACTIVE); for (ClientCertificate cert : expiredCerts) { cert.setStatus(CertificateStatus.EXPIRED); logger.info("Certificate expired: {}", cert.getSubjectDN()); } certificateRepository.saveAll(expiredCerts); } public Optional<ClientCertificate> getCertificateBySubjectDN(String subjectDN) { return certificateRepository.findBySubjectDN(subjectDN); } public List<ClientCertificate> getCertificatesByClientId(String clientId) { return certificateRepository.findByClientId(clientId); } // Custom Exceptions public static class CertificateAlreadyExistsException extends RuntimeException { public CertificateAlreadyExistsException(String message) { super(message); } } }

9. Security Configuration

Security Configuration:

package com.myapp.mtls.config; import com.myapp.mtls.auth.ClientCertificateAuthenticationProvider; import com.myapp.mtls.auth.ClientCertificateFilter; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.authentication.AuthenticationManager; import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration; import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.config.http.SessionCreationPolicy; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter; @Configuration @EnableWebSecurity @EnableMethodSecurity(prePostEnabled = true) public class SecurityConfig { private final ClientCertificateAuthenticationProvider certificateAuthProvider; public SecurityConfig(ClientCertificateAuthenticationProvider certificateAuthProvider) { this.certificateAuthProvider = certificateAuthProvider; } @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf(csrf -> csrf.disable()) .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(authz -> authz .requestMatchers("/actuator/health", "/public/**").permitAll() .requestMatchers("/api/admin/**").hasRole("ADMIN") .requestMatchers("/api/certificates/**").hasRole("ADMIN") .anyRequest().authenticated() ) .authenticationProvider(certificateAuthProvider) .addFilterBefore( new ClientCertificateFilter(), UsernamePasswordAuthenticationFilter.class ); return http.build(); } @Bean public AuthenticationManager authenticationManager(AuthenticationConfiguration authConfig) throws Exception { return authConfig.getAuthenticationManager(); } }

10. REST Controllers

Certificate Management Controller:

package com.myapp.mtls.controller; import com.myapp.mtls.model.ClientCertificate; import com.myapp.mtls.service.ClientCertificateService; import jakarta.validation.Valid; import org.springframework.http.ResponseEntity; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.web.bind.annotation.*; import java.security.cert.CertificateException; import java.security.cert.CertificateFactory; import java.security.cert.X509Certificate; import java.util.Base64; import java.util.List; @RestController @RequestMapping("/api/certificates") public class CertificateController { private final ClientCertificateService certificateService; public CertificateController(ClientCertificateService certificateService) { this.certificateService = certificateService; } @PostMapping @PreAuthorize("hasRole('ADMIN')") public ResponseEntity<?> registerCertificate(@Valid @RequestBody RegisterCertificateRequest request) { try { // Parse certificate from PEM X509Certificate certificate = parseCertificate(request.getCertificatePem()); // Register certificate ClientCertificate registeredCert = certificateService.registerCertificate( certificate, request.getClientId(), request.getRoles(), request.getDescription() ); return ResponseEntity.ok(new CertificateResponse(registeredCert)); } catch (CertificateException e) { return ResponseEntity.badRequest().body(new ErrorResponse("Invalid certificate: " + e.getMessage())); } catch (ClientCertificateService.CertificateAlreadyExistsException e) { return ResponseEntity.badRequest().body(new ErrorResponse(e.getMessage())); } } @GetMapping @PreAuthorize("hasRole('ADMIN')") public ResponseEntity<List<ClientCertificate>> getAllCertificates() { List<ClientCertificate> certificates = certificateService.getAllCertificates(); return ResponseEntity.ok(certificates); } @GetMapping("/expiring") @PreAuthorize("hasRole('ADMIN')") public ResponseEntity<List<ClientCertificate>> getExpiringCertificates( @RequestParam(defaultValue = "30") int days) { List<ClientCertificate> certificates = certificateService.getExpiringCertificates(days); return ResponseEntity.ok(certificates); } @DeleteMapping("/{certificateId}") @PreAuthorize("hasRole('ADMIN')") public ResponseEntity<?> revokeCertificate(@PathVariable Long certificateId, @RequestParam String reason) { certificateService.revokeCertificate(certificateId, reason); return ResponseEntity.ok().build(); } @GetMapping("/my-certificate") public ResponseEntity<?> getMyCertificate() { // This would be called by a client to get their own certificate info // Implementation depends on how you identify the client return ResponseEntity.ok().build(); } private X509Certificate parseCertificate(String pemCertificate) throws CertificateException { // Remove PEM headers and footers String base64Certificate = pemCertificate .replace("-----BEGIN CERTIFICATE-----", "") .replace("-----END CERTIFICATE-----", "") .replaceAll("\\s", ""); byte[] certBytes = Base64.getDecoder().decode(base64Certificate); CertificateFactory factory = CertificateFactory.getInstance("X.509"); return (X509Certificate) factory.generateCertificate(new java.io.ByteArrayInputStream(certBytes)); } // Request/Response DTOs public static class RegisterCertificateRequest { private String certificatePem; private String clientId; private List<String> roles; private String description; // Getters and setters public String getCertificatePem() { return certificatePem; } public void setCertificatePem(String certificatePem) { this.certificatePem = certificatePem; } public String getClientId() { return clientId; } public void setClientId(String clientId) { this.clientId = clientId; } public List<String> getRoles() { return roles; } public void setRoles(List<String> roles) { this.roles = roles; } public String getDescription() { return description; } public void setDescription(String description) { this.description = description; } } public static class CertificateResponse { private final Long id; private final String subjectDN; private final String status; private final String clientId; public CertificateResponse(ClientCertificate certificate) { this.id = certificate.getId(); this.subjectDN = certificate.getSubjectDN(); this.status = certificate.getStatus().name(); this.clientId = certificate.getClientId(); } // Getters public Long getId() { return id; } public String getSubjectDN() { return subjectDN; } public String getStatus() { return status; } public String getClientId() { return clientId; } } public static class ErrorResponse { private final String error; public ErrorResponse(String error) { this.error = error; } public String getError() { return error; } } }

Secure API Controller:

package com.myapp.mtls.controller; import com.myapp.mtls.auth.ClientCertificateAuthentication; import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.HashMap; import java.util.Map; @RestController @RequestMapping("/api/secure") public class SecureApiController { @GetMapping("/user-info") public Map<String, Object> getUserInfo(@AuthenticationPrincipal ClientCertificateAuthentication authentication) { Map<String, Object> userInfo = new HashMap<>(); userInfo.put("subjectDN", authentication.getSubjectDN()); userInfo.put("issuerDN", authentication.getIssuerDN()); userInfo.put("authorities", authentication.getAuthorities()); userInfo.put("authenticated", authentication.isAuthenticated()); if (authentication.getClientCertificate() != null) { userInfo.put("clientId", authentication.getClientCertificate().getClientId()); userInfo.put("certificateStatus", authentication.getClientCertificate().getStatus()); } return userInfo; } @GetMapping("/admin-data") public Map<String, String> getAdminData() { // This endpoint requires ADMIN role return Map.of( "message", "This is sensitive admin data", "accessLevel", "HIGH" ); } @GetMapping("/client-data") public Map<String, String> getClientData(@AuthenticationPrincipal ClientCertificateAuthentication authentication) { return Map.of( "message", "Data for client: " + authentication.getClientCertificate().getClientId(), "certificateSubject", authentication.getSubjectDN() ); } }

11. HTTP Client with mTLS

mTLS HTTP Client:

package com.myapp.mtls.client; import org.apache.hc.client5.http.classic.HttpClient; import org.apache.hc.client5.http.impl.classic.HttpClients; import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager; import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactory; import org.apache.hc.core5.ssl.SSLContexts; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.io.Resource; import org.springframework.http.client.HttpComponentsClientHttpRequestFactory; import org.springframework.web.client.RestTemplate; import javax.net.ssl.SSLContext; import java.io.FileInputStream; import java.security.KeyStore; @Configuration public class MtlsClientConfig { @Value("${client.ssl.key-store}") private Resource clientKeyStore; @Value("${client.ssl.key-store-password}") private String clientKeyStorePassword; @Value("${client.ssl.trust-store}") private Resource clientTrustStore; @Value("${client.ssl.trust-store-password}") private String clientTrustStorePassword; @Bean public RestTemplate mtlsRestTemplate() throws Exception { // Load client key store KeyStore keyStore = KeyStore.getInstance("PKCS12"); try (FileInputStream fis = new FileInputStream(clientKeyStore.getFile())) { keyStore.load(fis, clientKeyStorePassword.toCharArray()); } // Load trust store KeyStore trustStore = KeyStore.getInstance("PKCS12"); try (FileInputStream fis = new FileInputStream(clientTrustStore.getFile())) { trustStore.load(fis, clientTrustStorePassword.toCharArray()); } // Create SSL context with client certificate SSLContext sslContext = SSLContexts.custom() .loadKeyMaterial(keyStore, clientKeyStorePassword.toCharArray()) .loadTrustMaterial(trustStore, null) .build(); // Create SSL socket factory SSLConnectionSocketFactory socketFactory = new SSLConnectionSocketFactory(sslContext); // Create connection manager PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager(); connectionManager.setMaxTotal(100); connectionManager.setDefaultMaxPerRoute(20); // Create HTTP client HttpClient httpClient = HttpClients.custom() .setConnectionManager(connectionManager) .setSSLSocketFactory(socketFactory) .build(); // Create RestTemplate with mTLS client HttpComponentsClientHttpRequestFactory requestFactory = new HttpComponentsClientHttpRequestFactory(httpClient); requestFactory.setConnectTimeout(5000); requestFactory.setReadTimeout(30000); return new RestTemplate(requestFactory); } }

Example Client Usage:

package com.myapp.mtls.client; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.stereotype.Service; import org.springframework.web.client.RestTemplate; import java.util.Map; @Service public class SecureApiClient { private final RestTemplate mtlsRestTemplate; public SecureApiClient(@Qualifier("mtlsRestTemplate") RestTemplate mtlsRestTemplate) { this.mtlsRestTemplate = mtlsRestTemplate; } public Map<String, Object> callSecureApi(String url) { return mtlsRestTemplate.getForObject(url, Map.class); } public String callSecureEndpoint() { String apiUrl = "https://secure-api.mycompany.com:8443/api/secure/user-info"; Map<String, Object> response = callSecureApi(apiUrl); return "Response: " + response; } }

12. Repository Layer

Client Certificate Repository:

package com.myapp.mtls.repository; import com.myapp.mtls.model.ClientCertificate; import com.myapp.mtls.model.CertificateStatus; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.data.jpa.repository.Query; import org.springframework.stereotype.Repository; import java.time.LocalDateTime; import java.util.List; import java.util.Optional; @Repository public interface ClientCertificateRepository extends JpaRepository<ClientCertificate, Long> { Optional<ClientCertificate> findBySerialNumberAndSubjectDN(String serialNumber, String subjectDN); Optional<ClientCertificate> findBySubjectDN(String subjectDN); List<ClientCertificate> findByClientId(String clientId); List<ClientCertificate> findByStatus(CertificateStatus status); List<ClientCertificate> findByNotAfterBeforeAndStatus(LocalDateTime date, CertificateStatus status); @Query("SELECT c FROM ClientCertificate c WHERE c.notAfter < ?1 AND c.status = 'ACTIVE'") List<ClientCertificate> findExpiringSoon(LocalDateTime date); List<ClientCertificate> findByLastUsedAtBefore(LocalDateTime date); long countByStatus(CertificateStatus status); @Query("SELECT c FROM ClientCertificate c WHERE c.clientId = ?1 AND c.status = 'ACTIVE'") List<ClientCertificate> findActiveByClientId(String clientId); }

13. Benefits of Mutual TLS Authentication

Strong Authentication - Cryptographically proven identity
Eliminates Password Management - No passwords to store or rotate
Prevents Phishing - Certificates can't be easily stolen like passwords
Audit Trail - Clear identification of clients
Regulatory Compliance - Meets strict security requirements
Microservices Security - Ideal for service-to-service communication

Conclusion

Implementing mutual TLS authentication with client certificates in Java provides enterprise-grade security for your applications. By leveraging Spring Security and Java's robust SSL/TLS capabilities, you can create a secure system that validates both client and server identities.

The key to successful mTLS implementation is:

Proper certificate management with secure storage and validation
Comprehensive certificate lifecycle management including expiration and revocation
Secure configuration of SSL contexts and protocols
Robust error handling for certificate validation failures
Monitoring and alerting for certificate expiration and security events

Start with a development environment to test the mTLS setup, then gradually implement in production with proper certificate authority integration and monitoring.

Call to Action: Begin by setting up a test CA and generating test certificates. Implement basic mTLS authentication in a development environment, then gradually add features like certificate revocation, role-based access control, and comprehensive monitoring before deploying to production.