MACRO NEPAL
Secure Service Identity: Linkerd Identity Management in Java Applications
awiskar acharya
November 16, 2025
7:05 am

Linkerd's identity system provides secure, automatically rotating TLS certificates for all meshed services without requiring application code changes. This "magic" mutual TLS (mTLS) happens transparently at the proxy level, but Java applications can leverage and verify these identities for enhanced security. Understanding how this works is crucial for building secure, zero-trust microservice architectures.

This article explores Linkerd's identity model and demonstrates how Java applications can interact with and validate service identities within a Linkerd-meshed environment.

1. Linkerd Identity Fundamentals

Linkerd provides each pod with a cryptographically verifiable identity based on the Kubernetes Service Account mechanism.

Key Concepts:

  • Automated mTLS: All communication between Linkerd proxies is automatically encrypted and authenticated
  • Service Account Identity: Each pod's identity is derived from its Kubernetes service account
  • Short-lived Certificates: Certificates are automatically rotated (default: 24 hours)
  • Identity Verification: The control plane (destination service) acts as a Certificate Authority (CA)
  • Zero-Trust Security: Services must explicitly be allowed to communicate

How It Works:

  1. Each meshed pod gets an identity certificate from the Linkerd control plane
  2. The proxy uses this certificate to establish mTLS connections
  3. The certificate contains the Kubernetes service account identity
  4. Certificates are automatically refreshed before expiration

2. Identity Headers and Application-Layer Security

While mTLS happens at the transport layer, Linkerd proxies add critical identity headers that Java applications can inspect:

Linkerd Identity Headers:

  • l5d-client-id: The full identity of the calling service (e.g., webapp.default.serviceaccount.identity.linkerd.cluster.local)
  • l5d-server-id: The expected identity of the receiving service

Java Implementation: Extracting and Validating Identity

Here's how to access and validate Linkerd identity information in your Java application:

import javax.servlet.http.HttpServletRequest;
import java.util.Optional;
public class LinkerdIdentityHelper {
// Linkerd identity header constants
private static final String LINKERD_CLIENT_ID_HEADER = "l5d-client-id";
private static final String LINKERD_SERVER_ID_HEADER = "l5d-server-id";
/**
* Extract client identity from Linkerd headers
*/
public static Optional<String> getClientIdentity(HttpServletRequest request) {
return Optional.ofNullable(request.getHeader(LINKERD_CLIENT_ID_HEADER));
}
/**
* Extract server identity from Linkerd headers  
*/
public static Optional<String> getServerIdentity(HttpServletRequest request) {
return Optional.ofNullable(request.getHeader(LINKERD_SERVER_ID_HEADER));
}
/**
* Validate that the client is from an expected namespace
*/
public static boolean isClientFromNamespace(HttpServletRequest request, String expectedNamespace) {
return getClientIdentity(request)
.map(identity -> identity.contains("." + expectedNamespace + "."))
.orElse(false);
}
/**
* Validate that the client is a specific service account
*/
public static boolean isClientServiceAccount(HttpServletRequest request, 
String serviceAccount, 
String namespace) {
String expectedIdentity = String.format("%s.%s.serviceaccount.identity.linkerd.cluster.local", 
serviceAccount, namespace);
return getClientIdentity(request)
.map(identity -> identity.equals(expectedIdentity))
.orElse(false);
}
/**
* Extract service account name from identity string
*/
public static Optional<String> extractServiceAccount(String identity) {
if (identity == null || !identity.contains(".serviceaccount.identity.linkerd.cluster.local")) {
return Optional.empty();
}
try {
// Format: <service-account>.<namespace>.serviceaccount.identity.linkerd.cluster.local
String[] parts = identity.split("\\.");
if (parts.length >= 4) {
return Optional.of(parts[0]); // Service account name
}
} catch (Exception e) {
// Log warning about malformed identity
}
return Optional.empty();
}
/**
* Extract namespace from identity string
*/
public static Optional<String> extractNamespace(String identity) {
if (identity == null || !identity.contains(".serviceaccount.identity.linkerd.cluster.local")) {
return Optional.empty();
}
try {
String[] parts = identity.split("\\.");
if (parts.length >= 4) {
return Optional.of(parts[1]); // Namespace
}
} catch (Exception e) {
// Log warning about malformed identity
}
return Optional.empty();
}
}

3. Spring Boot Integration for Identity-Based Security

Here's how to integrate Linkerd identity validation into a Spring Boot application:

Spring Security Configuration:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.web.filter.OncePerRequestFilter;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Set;
@Configuration
@EnableWebSecurity
public class LinkerdSecurityConfig {
private final Set<String> allowedServiceAccounts = Set.of(
"frontend", "api-gateway", "internal-service"
);
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.addFilterBefore(linkerdIdentityFilter(), OncePerRequestFilter.class)
.authorizeRequests(authz -> authz
.antMatchers("/public/**").permitAll()
.antMatchers("/admin/**").access("@linkerdSecurityService.isAdminService(request)")
.antMatchers("/internal/**").access("@linkerdSecurityService.isInternalService(request)")
.anyRequest().authenticated()
)
.csrf().disable(); // CSRF typically handled at proxy level
return http.build();
}
@Bean
public LinkerdIdentityFilter linkerdIdentityFilter() {
return new LinkerdIdentityFilter();
}
}

Custom Identity Validation Filter:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
@Component
public class LinkerdIdentityFilter extends OncePerRequestFilter {
private static final Logger logger = LoggerFactory.getLogger(LinkerdIdentityFilter.class);
@Override
protected void doFilterInternal(HttpServletRequest request, 
HttpServletResponse response, 
FilterChain filterChain) throws ServletException, IOException {
String clientIdentity = request.getHeader("l5d-client-id");
// Log identity information for audit purposes
if (clientIdentity != null) {
logger.info("Request from identity: {} to path: {}", clientIdentity, request.getRequestURI());
// Basic validation - ensure identity header is present for sensitive endpoints
if (isSensitiveEndpoint(request.getRequestURI()) && clientIdentity.isBlank()) {
logger.warn("Missing identity header for sensitive endpoint: {}", request.getRequestURI());
response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Missing service identity");
return;
}
} else {
logger.debug("No Linkerd identity header present");
}
filterChain.doFilter(request, response);
}
private boolean isSensitiveEndpoint(String uri) {
return uri.startsWith("/admin") || uri.startsWith("/internal");
}
}

Security Service for Authorization Decisions:

import org.springframework.stereotype.Service;
import javax.servlet.http.HttpServletRequest;
import java.util.Set;
@Service
public class LinkerdSecurityService {
private final Set<String> adminServiceAccounts = Set.of(
"admin-service.production.serviceaccount.identity.linkerd.cluster.local",
"cicd-tool.tekton.serviceaccount.identity.linkerd.cluster.local"
);
private final Set<String> internalNamespaces = Set.of("internal", "backend", "processing");
public boolean isAdminService(HttpServletRequest request) {
String clientIdentity = request.getHeader("l5d-client-id");
return clientIdentity != null && adminServiceAccounts.contains(clientIdentity);
}
public boolean isInternalService(HttpServletRequest request) {
return LinkerdIdentityHelper.getClientIdentity(request)
.map(identity -> LinkerdIdentityHelper.extractNamespace(identity)
.map(internalNamespaces::contains)
.orElse(false))
.orElse(false);
}
public boolean isServiceAccount(HttpServletRequest request, String serviceAccount, String namespace) {
return LinkerdIdentityHelper.isClientServiceAccount(request, serviceAccount, namespace);
}
}

4. REST Client with Identity Headers Propagation

When making outbound calls from your Java service, you should propagate identity headers:

Spring RestTemplate with Header Propagation:

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
@Component
public class LinkerdHeaderPropagationInterceptor implements ClientHttpRequestInterceptor {
private static final String[] LINKERD_HEADERS_TO_PROPAGATE = {
"l5d-client-id",
"l5d-server-id",
"l5d-dst-override"
};
@Override
public ClientHttpResponse intercept(HttpRequest request, byte[] body, 
ClientHttpRequestExecution execution) throws IOException {
// Get current HTTP request from context
ServletRequestAttributes attributes = 
(ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
if (attributes != null) {
HttpServletRequest currentRequest = attributes.getRequest();
HttpHeaders outgoingHeaders = request.getHeaders();
// Propagate Linkerd headers
for (String headerName : LINKERD_HEADERS_TO_PROPAGATE) {
String headerValue = currentRequest.getHeader(headerName);
if (headerValue != null && !headerValue.trim().isEmpty()) {
outgoingHeaders.add(headerName, headerValue);
}
}
}
return execution.execute(request, body);
}
}

Configuration:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;
import java.util.Collections;
@Configuration
public class RestTemplateConfig {
@Bean
public RestTemplate restTemplate() {
RestTemplate restTemplate = new RestTemplate();
restTemplate.setInterceptors(
Collections.singletonList(new LinkerdHeaderPropagationInterceptor())
);
return restTemplate;
}
}

5. gRPC with Linkerd Identity

For gRPC services, you can access identity information through headers:

gRPC Server Interceptor:

import io.grpc.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class LinkerdGrpcInterceptor implements ServerInterceptor {
private static final Logger logger = LoggerFactory.getLogger(LinkerdGrpcInterceptor.class);
private static final Metadata.Key<String> CLIENT_ID_HEADER = 
Metadata.Key.of("l5d-client-id", Metadata.ASCII_STRING_MARSHALLER);
@Override
public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
String clientIdentity = headers.get(CLIENT_ID_HEADER);
if (clientIdentity != null) {
logger.info("gRPC call from identity: {} to method: {}", 
clientIdentity, call.getMethodDescriptor().getFullMethodName());
// Store identity in context for use in service implementation
Context context = Context.current().withValue(
ContextKeys.CLIENT_IDENTITY, clientIdentity);
return Contexts.interceptCall(context, call, headers, next);
}
return next.startCall(call, headers);
}
public static class ContextKeys {
public static final Context.Key<String> CLIENT_IDENTITY = 
Context.key("client-identity");
}
}

gRPC Service Implementation:

import io.grpc.stub.StreamObserver;
import net.devh.boot.grpc.server.service.GrpcService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import static LinkerdGrpcInterceptor.ContextKeys.CLIENT_IDENTITY;
@GrpcService
public class MyGrpcService extends MyServiceGrpc.MyServiceImplBase {
private static final Logger logger = LoggerFactory.getLogger(MyGrpcService.class);
@Override
public void processRequest(MyRequest request, StreamObserver<MyResponse> responseObserver) {
String clientIdentity = CLIENT_IDENTITY.get();
if (clientIdentity != null) {
logger.info("Processing gRPC request from identity: {}", clientIdentity);
// Implement identity-based logic
if (clientIdentity.contains(".production.")) {
// Apply production-specific logic
}
}
MyResponse response = MyResponse.newBuilder()
.setResult("Processed by: " + getServerIdentity())
.build();
responseObserver.onNext(response);
responseObserver.onCompleted();
}
private String getServerIdentity() {
// This would typically come from environment variables or configuration
return System.getenv("HOSTNAME") + ".production.serviceaccount.identity.linkerd.cluster.local";
}
}

6. Kubernetes Deployment with Service Accounts

Proper Kubernetes configuration is essential for Linkerd identity to work:

Deployment with Service Account:

apiVersion: v1
kind: ServiceAccount
metadata:
name: java-app-serviceaccount
namespace: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: java-app
namespace: production
labels:
app: java-app
spec:
replicas: 3
selector:
matchLabels:
app: java-app
template:
metadata:
labels:
app: java-app
annotations:
linkerd.io/inject: enabled  # Enable Linkerd sidecar injection
spec:
serviceAccountName: java-app-serviceaccount  # Critical for identity
containers:
- name: java-app
image: mycompany/java-app:1.0.0
env:
- name: SERVICE_IDENTITY
value: "java-app-serviceaccount.production.serviceaccount.identity.linkerd.cluster.local"
ports:
- containerPort: 8080

7. Testing and Verification

Unit Tests for Identity Logic:

import org.junit.jupiter.api.Test;
import org.springframework.mock.web.MockHttpServletRequest;
import static org.junit.jupiter.api.Assertions.*;
public class LinkerdIdentityHelperTest {
@Test
public void testExtractServiceAccount() {
String identity = "frontend.production.serviceaccount.identity.linkerd.cluster.local";
Optional<String> serviceAccount = LinkerdIdentityHelper.extractServiceAccount(identity);
assertTrue(serviceAccount.isPresent());
assertEquals("frontend", serviceAccount.get());
}
@Test
public void testIdentityValidation() {
MockHttpServletRequest request = new MockHttpServletRequest();
request.addHeader("l5d-client-id", 
"api-gateway.production.serviceaccount.identity.linkerd.cluster.local");
assertTrue(LinkerdIdentityHelper.isClientFromNamespace(request, "production"));
assertTrue(LinkerdIdentityHelper.isClientServiceAccount(request, "api-gateway", "production"));
}
}

8. Best Practices

  1. Always validate service identities for sensitive operations
  2. Use Kubernetes Network Policies in conjunction with identity validation
  3. Log identity information for audit trails
  4. Propagate identity headers in outbound calls
  5. Use short, descriptive service account names
  6. Implement proper error handling for missing identity headers
  7. Monitor for identity-related issues in your logging and monitoring systems

Conclusion

Linkerd's identity system provides a powerful foundation for zero-trust security in Kubernetes environments. While the mTLS encryption happens automatically at the proxy level, Java applications can leverage the identity information for application-layer authorization, auditing, and security enforcement. By integrating identity validation into your Spring Boot or gRPC services, you can build defense-in-depth security that works in harmony with Linkerd's service mesh capabilities.

The combination of transparent mTLS and application-aware identity validation creates a robust security posture that's essential for modern microservice architectures.

Further Reading:

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper