API key / HMAC:
  caller proves knowledge of a shared secret

mTLS:
  caller proves possession of a private key whose certificate chains to a trusted authority

browser/client verifies server certificate
server usually does not verify client certificate

client verifies server certificate
server verifies client certificate

Is the peer controlling the private key corresponding to this certificate,
and does that certificate represent an identity trusted for this endpoint?

Is this peer authorized to call this business operation?
Is the human user behind the peer authenticated?
Is the request semantically safe?
Is the workload uncompromised?

Trust Anchor / CA
  root/intermediate certificate authority trusted by both sides

Certificate
  public identity document signed by CA

Private Key
  private proof material held only by workload/client

Certificate Chain
  leaf certificate + intermediate CA certificates

Identity Claim
  subject, DNS SAN, URI SAN, SPIFFE ID, custom extension, or mapped principal

Trust Store
  certificates/CA used to verify peer certificates

Key Store
  local private key + certificate chain used by this workload

KeyStore      = where my private key + cert chain live
TrustStore    = who I trust as issuer of peer certificates
KeyManager    = chooses my certificate during TLS handshake
TrustManager  = validates peer certificate during TLS handshake
SSLContext    = runtime TLS configuration built from key/trust material

Keystore:   who am I?
Truststore: who do I trust?

HTTP request
  arrives over TLS
  server obtains peer certificate from TLS session
  app maps certificate identity to principal/client/service account
  app builds Authentication object / Principal
  app continues authorization and business processing

A certificate is not a permission set.
A certificate is evidence for an identity.
Permission must be resolved from policy.

If the caller is a workload, service, device, or enterprise client:
  mTLS may be appropriate.

If the caller is a human in a browser:
  OIDC/session/passkey is usually more appropriate.

Where is the client certificate validated?
Does the application receive the verified certificate or only a forwarded header?
Can any caller spoof that header?
Is the app reachable except through the gateway?
Is gateway-to-app traffic mutually authenticated too?
Is certificate identity normalized consistently?

client -> Java app over mTLS

client -> gateway over mTLS
 gateway -> app over mTLS/plain internal transport

Only accept forwarded client identity headers from a mutually authenticated trusted proxy.
Strip inbound identity headers at the edge before setting canonical headers.

workload sidecar -> sidecar mTLS -> workload sidecar

Subject DN
  CN=client-a,O=partner

DNS SAN
  DNS:client-a.partner.example

URI SAN
  URI:spiffe://prod.example/ns/payments/sa/invoice-api

Custom extension
  enterprise-specific identity attribute

Thumbprint
  hash of certificate bytes; useful for pinning but problematic as logical identity

Use SAN-based identity, especially URI SAN for workload identity.
Avoid relying only on CN for new systems.

raw certificate
  -> validate chain and usage
  -> extract allowed SAN type
  -> canonicalize identity string
  -> map to client/service account
  -> load policy metadata

if (certificate.getSubjectX500Principal().getName().contains("admin")) {
    allow();
}

spiffe://trust-domain/path

spiffe://example.com/ns/payments/sa/invoice-api

Trust Domain
  administrative identity boundary, e.g. example.com

Workload Attestation
  proof that a running workload is who it claims to be

SVID
  SPIFFE Verifiable Identity Document, often X.509-SVID or JWT-SVID

Workload API
  local API used by workloads to obtain identities

client has X.509-SVID
server has X.509-SVID
both validate peer chain against trust bundle
authorization uses peer SPIFFE ID

SPIFFE identity is workload identity.
It is not automatically end-user identity.

workload identity: spiffe://example.com/ns/api/sa/service-a
user identity: sub=user-123 from token/session context

1. Client authentication to authorization server
2. Certificate-bound access tokens

{
  "iss": "https://auth.example.com",
  "sub": "client:billing-worker",
  "aud": "payments-api",
  "cnf": {
    "x5t#S256": "base64url-sha256-cert-thumbprint"
  }
}

Is the token valid?
Is issuer trusted?
Is audience correct?
Is token unexpired?
Does token cnf match the presented client certificate?

KeyStore
KeyManagerFactory
TrustStore
TrustManagerFactory
SSLContext

import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManagerFactory;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.KeyStore;

public final class MtlsSslContextFactory {

    public static SSLContext create(
            Path keyStorePath,
            char[] keyStorePassword,
            Path trustStorePath,
            char[] trustStorePassword
    ) throws Exception {
        KeyStore keyStore = KeyStore.getInstance("PKCS12");
        try (InputStream in = Files.newInputStream(keyStorePath)) {
            keyStore.load(in, keyStorePassword);
        }

        KeyManagerFactory kmf = KeyManagerFactory.getInstance(
                KeyManagerFactory.getDefaultAlgorithm()
        );
        kmf.init(keyStore, keyStorePassword);

        KeyStore trustStore = KeyStore.getInstance("PKCS12");
        try (InputStream in = Files.newInputStream(trustStorePath)) {
            trustStore.load(in, trustStorePassword);
        }

        TrustManagerFactory tmf = TrustManagerFactory.getInstance(
                TrustManagerFactory.getDefaultAlgorithm()
        );
        tmf.init(trustStore);

        SSLContext sslContext = SSLContext.getInstance("TLS");
        sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);
        return sslContext;
    }
}

server:
  ssl:
    enabled: true
    key-store: file:/etc/tls/server.p12
    key-store-password: ${SERVER_KEYSTORE_PASSWORD}
    key-store-type: PKCS12
    trust-store: file:/etc/tls/client-ca.p12
    trust-store-password: ${CLIENT_TRUSTSTORE_PASSWORD}
    trust-store-type: PKCS12
    client-auth: need

none  -> no client certificate requested
want  -> request client cert but allow absence
need  -> require valid client cert

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.web.SecurityFilterChain;

@Configuration
class SecurityConfig {

    @Bean
    SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/health").permitAll()
                .anyRequest().authenticated()
            )
            .x509(x509 -> x509
                .subjectPrincipalRegex("CN=(.*?)(?:,|$)")
                .userDetailsService(new CertificateClientDetailsService())
            );

        return http.build();
    }
}

import jakarta.servlet.http.HttpServletRequest;
import java.security.cert.X509Certificate;
import java.util.List;

public final class ClientCertificateExtractor {

    public static List<X509Certificate> certificates(HttpServletRequest request) {
        Object attribute = request.getAttribute("jakarta.servlet.request.X509Certificate");
        if (attribute instanceof X509Certificate[] chain) {
            return List.of(chain);
        }
        return List.of();
    }
}

import jakarta.annotation.Priority;
import jakarta.ws.rs.Priorities;
import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.container.ContainerRequestFilter;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.SecurityContext;
import jakarta.ws.rs.ext.Provider;
import jakarta.servlet.http.HttpServletRequest;
import java.security.Principal;
import java.security.cert.X509Certificate;

@Provider
@Priority(Priorities.AUTHENTICATION)
public final class MtlsAuthenticationFilter implements ContainerRequestFilter {

    @Context
    HttpServletRequest servletRequest;

    private final CertificateIdentityService identityService;

    public MtlsAuthenticationFilter(CertificateIdentityService identityService) {
        this.identityService = identityService;
    }

    @Override
    public void filter(ContainerRequestContext requestContext) {
        X509Certificate certificate = firstClientCertificate(servletRequest);

        if (certificate == null) {
            requestContext.abortWith(Response.status(Response.Status.UNAUTHORIZED).build());
            return;
        }

        AuthenticatedClient client = identityService.authenticate(certificate);
        if (client == null) {
            requestContext.abortWith(Response.status(Response.Status.FORBIDDEN).build());
            return;
        }

        SecurityContext previous = requestContext.getSecurityContext();
        requestContext.setSecurityContext(new SecurityContext() {
            @Override
            public Principal getUserPrincipal() {
                return () -> client.principalName();
            }

            @Override
            public boolean isUserInRole(String role) {
                return client.roles().contains(role);
            }

            @Override
            public boolean isSecure() {
                return previous != null && previous.isSecure();
            }

            @Override
            public String getAuthenticationScheme() {
                return "MTLS";
            }
        });
    }

    private X509Certificate firstClientCertificate(HttpServletRequest request) {
        Object chain = request.getAttribute("jakarta.servlet.request.X509Certificate");
        if (chain instanceof X509Certificate[] certificates && certificates.length > 0) {
            return certificates[0];
        }
        Object legacy = request.getAttribute("javax.servlet.request.X509Certificate");
        if (legacy instanceof X509Certificate[] certificates && certificates.length > 0) {
            return certificates[0];
        }
        return null;
    }
}

import java.security.MessageDigest;
import java.security.cert.X509Certificate;
import java.time.Instant;
import java.util.HexFormat;
import java.util.List;

public final class CertificateIdentityService {

    private final ClientCertificateRepository repository;

    public CertificateIdentityService(ClientCertificateRepository repository) {
        this.repository = repository;
    }

    public AuthenticatedClient authenticate(X509Certificate cert) {
        CertificateIdentity identity = extractIdentity(cert);
        if (identity == null) {
            return null;
        }

        String thumbprint = sha256Thumbprint(cert);

        RegisteredClientCertificate registered = repository.findActiveByIdentity(identity.value());
        if (registered == null) {
            auditReject("unknown_identity", identity.value(), thumbprint);
            return null;
        }

        if (!registered.allowedThumbprints().isEmpty()
                && !registered.allowedThumbprints().contains(thumbprint)) {
            auditReject("thumbprint_not_allowed", identity.value(), thumbprint);
            return null;
        }

        if (registered.notAfter().isBefore(Instant.now())) {
            auditReject("registration_expired", identity.value(), thumbprint);
            return null;
        }

        return new AuthenticatedClient(
                registered.clientId(),
                identity.value(),
                registered.roles(),
                thumbprint
        );
    }

    private CertificateIdentity extractIdentity(X509Certificate cert) {
        // Prefer URI SAN / SPIFFE ID in production.
        // This is pseudo-code because SAN parsing is verbose.
        List<String> uriSans = CertificateSanReader.uriSubjectAlternativeNames(cert);
        return uriSans.stream()
                .filter(uri -> uri.startsWith("spiffe://example.com/"))
                .findFirst()
                .map(CertificateIdentity::new)
                .orElse(null);
    }

    private String sha256Thumbprint(X509Certificate cert) {
        try {
            byte[] encoded = cert.getEncoded();
            byte[] digest = MessageDigest.getInstance("SHA-256").digest(encoded);
            return HexFormat.of().formatHex(digest);
        } catch (Exception e) {
            throw new IllegalStateException("Cannot compute certificate thumbprint", e);
        }
    }

    private void auditReject(String reason, String identity, String thumbprint) {
        // emit structured audit event; do not log full certificate or private data
    }
}

import java.time.Instant;
import java.util.Set;

public record CertificateIdentity(String value) {}

public record AuthenticatedClient(
        String clientId,
        String identity,
        Set<String> roles,
        String certificateThumbprint
) {}

public record RegisteredClientCertificate(
        String clientId,
        String identity,
        Set<String> roles,
        Set<String> allowedThumbprints,
        Instant notAfter
) {}

certificate cryptographic validity
  from
identity registration validity
  from
authorization policy

create table mtls_client (
    client_id text primary key,
    tenant_id text,
    display_name text not null,
    status text not null check (status in ('ACTIVE', 'SUSPENDED', 'REVOKED')),
    created_at timestamptz not null default now(),
    updated_at timestamptz not null default now()
);

create table mtls_client_identity (
    identity_id uuid primary key,
    client_id text not null references mtls_client(client_id),
    identity_type text not null check (identity_type in ('URI_SAN', 'DNS_SAN', 'SUBJECT_DN', 'SPIFFE_ID')),
    identity_value text not null,
    trust_domain text,
    status text not null check (status in ('ACTIVE', 'RETIRED', 'REVOKED')),
    valid_from timestamptz not null,
    valid_until timestamptz not null,
    created_at timestamptz not null default now(),
    unique (identity_type, identity_value)
);

create table mtls_certificate_pin (
    pin_id uuid primary key,
    client_id text not null references mtls_client(client_id),
    sha256_thumbprint text not null,
    status text not null check (status in ('ACTIVE', 'RETIRED', 'REVOKED')),
    valid_from timestamptz not null,
    valid_until timestamptz not null,
    created_at timestamptz not null default now(),
    unique (sha256_thumbprint)
);

create table mtls_auth_event (
    event_id uuid primary key,
    occurred_at timestamptz not null default now(),
    client_id text,
    identity_value text,
    cert_thumbprint text,
    outcome text not null,
    reason text,
    remote_addr inet,
    route text,
    correlation_id text
);

old cert expires at 12:00
new cert deployed at 12:00
all clients reconnect at once
some fail due clock skew/cache/restart delay

T-14d  issue new cert
T-7d   client deploys new cert
T-7d..T+7d server accepts old and new identity/material
T      old cert expires
T+7d   remove old registration/pin/trust

A client must be able to prove identity with old or new certificate during overlap.
A compromised certificate must be revocable immediately.
A trust anchor rotation must be tested before production cutover.
Expired certificates must not be accepted because registration says active.

Use short-lived certificates where possible.
Keep local client registration state.
Support emergency deny-list by identity/thumbprint.
Monitor expiry before it becomes an incident.

X-Forwarded-Client-Cert
X-Client-Cert-SAN
X-Client-Cert-Verify
X-Authenticated-Client-Id

Strip all incoming identity headers from external clients.
Validate client certificate.
Normalize identity.
Set a canonical internal identity header.
Send request to app over trusted channel.

Accept identity headers only from known gateway network and/or gateway mTLS identity.
Reject if request is direct.
Use one canonical header schema.
Audit forwarded identity source.
Never parse raw untrusted certificate PEM header from arbitrary clients.

public final class TrustedGatewayIdentityVerifier {

    private final Set<String> trustedGatewaySpiffeIds;

    public VerifiedForwardedIdentity verify(InternalRequest request) {
        String gatewayIdentity = request.peerWorkloadIdentity();
        if (!trustedGatewaySpiffeIds.contains(gatewayIdentity)) {
            throw new AuthenticationException("untrusted_forwarder");
        }

        String clientIdentity = request.header("X-Authenticated-Client-Identity");
        String verification = request.header("X-Client-Cert-Verified");

        if (!"SUCCESS".equals(verification) || clientIdentity == null || clientIdentity.isBlank()) {
            throw new AuthenticationException("missing_verified_client_identity");
        }

        return new VerifiedForwardedIdentity(clientIdentity, gatewayIdentity);
    }
}

user browser -> API Gateway -> Order Service -> Payment Service

Service identity:
  Order Service calling Payment Service

User identity:
  Alice on behalf of whom the operation is performed

Allow service-a to call payment-api.capture
only if user token has tenant_id matching request tenant
and service-a is allowed to act for that tenant.

public final class CertificateBoundTokenValidator {

    public void validate(JwtAccessToken token, X509Certificate peerCertificate) {
        String tokenThumbprint = token.confirmationCertificateThumbprint();
        if (tokenThumbprint == null) {
            throw new AuthenticationException("missing_cnf");
        }

        String actualThumbprint = Thumbprints.sha256Base64Url(peerCertificate);
        if (!constantTimeEquals(tokenThumbprint, actualThumbprint)) {
            throw new AuthenticationException("certificate_bound_token_mismatch");
        }
    }

    private boolean constantTimeEquals(String a, String b) {
        return java.security.MessageDigest.isEqual(
                a.getBytes(java.nio.charset.StandardCharsets.UTF_8),
                b.getBytes(java.nio.charset.StandardCharsets.UTF_8)
        );
    }
}

Resource server validates token signature but ignores cnf claim.
Attacker with stolen token can use it without certificate.

client cert missing
client cert expired
unknown issuer
unknown identity
identity disabled
thumbprint mismatch
certificate-bound token mismatch
truststore reload failure
certificate near expiry
handshake failure spike
route denied due mTLS policy

correlation_id
route
outcome
reason
peer_identity
cert_thumbprint_sha256
issuer_fingerprint
not_before
not_after
source_ip
trusted_forwarder_identity

private key
full certificate unless explicitly redacted and required
raw authorization token
full user PII

auth_mtls_attempt_total{outcome,reason,route}
auth_mtls_handshake_failure_total{reason}
auth_mtls_certificate_days_until_expiry{client_id}
auth_mtls_unknown_identity_total{trust_domain}
auth_mtls_token_binding_mismatch_total{route}

Any production server certificate expires in < 14 days.
Any active client certificate expires in < 7 days.
Unknown client identity spike > baseline.
Certificate-bound token mismatch > 0 for privileged APIs.
Handshake failure rate > threshold after deployment.

Attacker sends X-Authenticated-Client-Identity: partner-a

Application trusts identity header without verifying gateway origin.

Strip headers at edge.
Accept identity headers only from trusted mTLS gateway.
Block direct app ingress.

Expired partner contract but certificate still valid.

Certificate acceptance treated as authorization.

Map certificate identity to registered client account and active policy.

Partner integration outage at certificate cutover.

Server accepts only one thumbprint/cert at a time.

Support overlapping identities/material during planned rotation.

Route accepts anonymous TLS because client-auth=want and app forgets to enforce presence.

Use client-auth=need where all routes require mTLS, or enforce route-level certificate presence.

Any certificate from public/enterprise CA can authenticate as client.

Trust narrow client CA roots and map identity to explicit registration.

Payment service trusts Order service mTLS and performs user operation without user context.

Authenticate service and user/delegation context separately.

[ ] TLS termination point is explicit.
[ ] Direct app access cannot bypass gateway/mTLS policy.
[ ] Server verifies client certificate chain, expiry, key usage, and trusted CA.
[ ] Identity extraction uses SAN/URI SAN/SPIFFE ID where possible.
[ ] Certificate identity is mapped to registered client/service account.
[ ] Authorization is not embedded only in certificate subject.
[ ] Certificate rotation supports overlap.
[ ] Emergency revoke/deny-list exists.
[ ] Certificate expiry monitoring exists.
[ ] Gateway-forwarded identity headers are stripped and re-set by trusted proxy only.
[ ] App accepts forwarded identity only from trusted gateway identity/channel.
[ ] Service identity and user identity are modeled separately.
[ ] Token binding cnf is validated when certificate-bound tokens are used.
[ ] Unknown/expired/revoked certificate events are audited.
[ ] Full certificate/private key/token are not logged.
[ ] Integration tests cover valid, missing, expired, unknown CA, wrong SAN, spoofed header.

A payments platform exposes APIs to enterprise partners.
Partners call through an API gateway.
Gateway supports mTLS.
Internal services use service mesh mTLS.
Some APIs also require OAuth access tokens.

external partner identity:
  certificate URI SAN / registered partner client

gateway identity:
  trusted internal forwarder workload

internal service identity:
  SPIFFE/SPIRE or mesh workload identity

end-user/delegated subject:
  OAuth/OIDC token subject where applicable

trust anchor
  + certificate lifecycle
  + identity extraction
  + registration mapping
  + TLS termination boundary
  + header trust model
  + rotation/revocation
  + service/user identity separation
  + observability

mTLS authenticates a peer identity at a channel boundary.
It does not replace authorization, user authentication, or business policy.