Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Security and mTLS

mTLS and Peer Authentication

Understand mutual TLS in Istio, how automatic mTLS works, and how to move a namespace from PERMISSIVE to STRICT with PeerAuthentication step by step.

In ordinary TLS, only the server proves its identity: your browser checks the website's certificate, and the website does not check yours. In mutual TLS (mTLS) both sides present certificates. The server knows exactly which workload is calling, and the connection is encrypted. Istio makes this automatic between sidecars: you get it without changing application code.

Cluster commands are read-only here. Python stand-ins illustrate the logic and do no real cryptography.

What mTLS gives you

Encryption Nobody can read traffic in transit.
Identity Both sides prove who they are.
Integrity Tampering is detected.

Istio does it in the proxies, not in your app.

1 / 2

How automatic mTLS works

  1. Each workload has a certificate that names its identity (see Workload Identity and Certificates).
  2. When web calls catalog, the outbound proxy looks up the destination. If the destination has a sidecar, the proxy automatically uses mTLS (Istio sends the ALPN protocol istio to signal this).
  3. The inbound proxy of catalog checks the caller's certificate against the mesh's root of trust, then forwards plain traffic to the local app over the loopback interface.

The traffic between the application and its own proxy never leaves the pod, so the encrypted hop is proxy to proxy.

flowchart LR
    A["web app"] -- "plain (localhost)" --> PA["web proxy"]
    PA -- "mTLS over the network" --> PB["catalog proxy"]
    PB -- "plain (localhost)" --> B["catalog app"]

The network segment, where eavesdropping is possible, is the encrypted one.

PeerAuthentication modes

A PeerAuthentication resource sets what a workload accepts:

Mode Accepts
PERMISSIVE (default) Both mTLS and plain text
STRICT Only mTLS
DISABLE Plain text, no mTLS
UNSET Inherit from the parent scope

Permissive is the default so that you can adopt the mesh gradually: workloads outside the mesh (or without sidecars) can still call in. Once every client is in the mesh, switch to STRICT.

Mesh-wide strict mode, placed in the root namespace:

YAML
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system
spec:
  mtls:
    mode: STRICT

Namespace-wide and per-workload variants:

YAML
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: legacy-batch
  namespace: shop
spec:
  selector:
    matchLabels:
      app: batch
  mtls:
    mode: PERMISSIVE
  portLevelMtls:
    9090:
      mode: DISABLE

The most specific scope wins, and portLevelMtls can relax a single port (for example a metrics port scraped by a client outside the mesh). Note that portLevelMtls refers to the workload port, and requires a selector.

Related: the client side is controlled by the DestinationRule's trafficPolicy.tls.mode (ISTIO_MUTUAL to use Istio's certificates). With automatic mTLS you rarely set it; you set it when you must force or disable mTLS toward a destination.

A safe path to STRICT

  1. Install with default PERMISSIVE. Inject sidecars everywhere that can have them.
  2. Use the mesh's metrics (connection_security_policy label in istio_requests_total) or Kiali to see which calls are still plain text.
  3. Fix or exclude those callers (add sidecars, or use portLevelMtls).
  4. Apply STRICT to one namespace, watch for connection reset / 503 and UF errors.
  5. Apply STRICT mesh-wide.

Be aware of health probes: Kubernetes' kubelet is not in the mesh and cannot present a certificate. Istio rewrites probes by default so that the sidecar agent forwards them, which keeps STRICT mode working. If probes fail after enabling STRICT, check that the probe rewrite has not been disabled.

Stand-ins

Python Stand-in: which connections does each mode accept?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: is the namespace ready for STRICT?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does mutual TLS add compared with ordinary TLS?

    In mTLS both parties authenticate with certificates.
  2. 2. Which PeerAuthentication mode refuses plain-text connections?

    STRICT accepts only mTLS.
  3. 3. Why is PERMISSIVE the default?

    PERMISSIVE accepts both, so workloads without sidecars keep working during migration.
  4. 4. Where does traffic between the app and its own sidecar travel?

    The app and proxy share a pod; the encrypted hop is proxy to proxy.

Summary

  • mTLS encrypts traffic and authenticates both ends; Istio does it in the sidecars automatically.
  • PeerAuthentication modes: PERMISSIVE (default), STRICT, DISABLE, UNSET.
  • Scope: mesh (root namespace), namespace, workload, and port-level exceptions.
  • Migrate by observing plain-text callers, fixing them, then enforcing STRICT.
  • Kubelet probes are rewritten so STRICT keeps working.

Next: Workload Identity and Certificates