Skip to main content
Mapagam

Implementing Peer Authentication

1. Creating Peer Authentication Policies

Property Values Description
metadata.name peer-authn-policy Name of the peer authentication policy
spec.mtls.mode PERMISSIVE, STRICT, DISABLE MTLS mode for peer authentication
spec.mtls.ports [8080, 9090] Ports to apply mTLS to

Example: Peer Authentication Policy Configuration

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: peer-authn-policy
spec:
  mtls:
    mode: STRICT
  ports:
  - number: 8080
  - number: 9090

2. Configuring mTLS Mode in Peer Authentication

Mode Description Configuration Notes
DISABLE Peer authentication is disabled. peerAuthentication.mtls.mode: DISABLE No mutual TLS is enforced.
PERMISSIVE Allows both mTLS and plaintext traffic. peerAuthentication.mtls.mode: PERMISSIVE Useful for gradual migration.
STRICT Enforces mTLS for all traffic. peerAuthentication.mtls.mode: STRICT Recommended for production environments.

Example: Configuring mTLS Mode

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
spec:
  mtls:
    mode: STRICT

3. Setting Port-Level mTLS Settings

Property Value Description
port 8080 Port number to apply mTLS settings to
mode PERMISSIVE | STRICT mTLS mode for this port: PERMISSIVE allows both mTLS and plaintext, STRICT enforces mTLS only
clientCertificate optional | required Whether client certificate is required for mTLS on this port

Example: Configure mTLS on a specific port

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: mtls-on-port
spec:
  selector:
    matchLabels:
      app: frontend
  portLevelMtls:
    8080:
      mode: STRICT
      clientCertificate: required

4. Implementing Workload Selectors

Selector Type Description Example Notes
workloadSelector Defines the set of workloads to which the policy applies 
{
  "matchLabels": {
    "app": "frontend",
    "version": "v1"
  }
}
 Used to target specific workloads by labels
namespaceSelector Applies policy to workloads in specific namespaces 
{
  "matchLabels": {
    "env": "production"
  }
}
 Can be combined with workload selectors

Example: Workload Selector Configuration

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: "strict"
  namespace: "istio-system"
spec:
  selector:
    matchLabels:
      app: "frontend"
  mtls:
    mode: STRICT
Note: Workload selectors use label-based matching to apply policies. Ensure labels are consistently applied across workloads.

5. Configuring Namespace-Level Peer Authentication

Property Value Description
peerAuthentication.namespace istio-system Namespace where the peer authentication policy is applied
peerAuthentication.mtls.mode STRICT Enforces mutual TLS for all workloads in the namespace
peerAuthentication.mtls.ports [80, 443] Specific ports to enforce mTLS on

Example: Namespace-Level Peer Authentication Policy

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system
spec:
  mtls:
    mode: STRICT
  ports:
  - number: 80
  - number: 443
Note: Setting mode: STRICT requires all workloads in the namespace to use mutual TLS for communication.

6. Setting Mesh-Wide Peer Authentication

Property Value Description
peerAuthentication.mtls.mode PERMISSIVE, STRICT, DISABLE Configures the mTLS mode for all workloads in the mesh. STRICT enforces mTLS, PERMISSIVE allows both mTLS and plaintext, DISABLE disables mTLS entirely.
peerAuthentication.mtls.ports 8080, 9090 Specifies the ports on which mTLS is enforced. If not set, applies to all ports.
peerAuthentication.mtls.caBundle /etc/certs/ca.crt Path to the CA certificate bundle used for mTLS validation. Required when using custom CA.

Example: Setting Mesh-Wide Peer Authentication

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default-mesh-peerauthn
  namespace: istio-system
spec:
  mtls:
    mode: STRICT
Note: Setting mode: STRICT ensures all traffic between services in the mesh is encrypted and authenticated.

7. Managing Peer Authentication Precedence

Scope Priority Level Description
MeshConfig DEPRECATED Global default settings; legacy approach, not recommended for new deployments
PeerAuthentication High Applies to specific workloads or namespaces; overrides MeshConfig
Workload-specific Higher Directly applied to individual workloads; highest precedence

Example: Setting Peer Authentication at Workload Level

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: workload-pa
  namespace: production
spec:
  selector:
    matchLabels:
      app: frontend
  mtls:
    mode: STRICT
Note: When multiple PeerAuthentication resources apply to the same workload, the most specific (workload-level) takes precedence over namespace-level and mesh-wide settings.

8. Implementing mTLS Migration Strategy

Example: mTLS Migration Plan

# Example migration strategy in Istio
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: mtls-migration
spec:
  selector:
    matchLabels:
      app: backend
  mtls:
    mode: PERMISSIVE # Start with permissive to allow both mTLS and plaintext
  portLevelMtls:
    8080:
      mode: DISABLE # Disable mTLS on specific port
Mode Description Use Case Notes
DISABLE mTLS is disabled for the workload Migration from plaintext to mTLS Useful for gradual migration
PERMISSIVE Workload accepts both mTLS and plaintext traffic Migration from plaintext to mTLS Allows coexistence of old and new clients
STRICT Workload only accepts mTLS traffic Full mTLS adoption Enforces security policy

Migration Strategy Steps

  • Start with PERMISSIVE mode to allow mixed traffic
  • Gradually enforce STRICT mode once all clients support mTLS
  • Use DISABLE for specific ports that don't require mTLS
  • Monitor traffic and logs during migration
Note: The PERMISSIVE mode allows for a smooth transition by accepting both mTLS and plaintext traffic, ensuring no disruption to existing services while migrating to full mTLS.
Warning: Switching to STRICT mode before all clients support mTLS will cause traffic failures. Ensure all services are updated before enforcing strict mode.

9. Verifying Peer Authentication

Property Description Values Notes
peerAuthentication.mtls.mode Configures mutual TLS mode for peer authentication DISABLED, PERMISSIVE, STRICT Default is PERMISSIVE in Istio
peerAuthentication.mtls.ports Port-specific mutual TLS settings 8080, 9090 Can override global mTLS settings per port

Example: Verifying mTLS in Peer Authentication

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
spec:
  mtls:
    mode: STRICT
  ports:
    - number: 8080
      mtls:
        mode: DISABLED
Note: Enforcing STRICT mode requires all services to support mTLS.
Warning: Disabling mTLS on specific ports may introduce security vulnerabilities.

10. Troubleshooting Peer Authentication

Common Issues and Solutions

  1. Authentication Fails Due to Certificate Mismatch
    • Verify that the certificate used for peer authentication matches the expected identity.
    • Check if the certificate has expired or is not yet valid.
  2. Connection Timeout or TLS Handshake Failure
    • Ensure that the service mesh control plane is correctly configured to handle TLS.
    • Validate that all services in the mesh have proper mTLS configurations.
  3. Incorrect Peer Authentication Policy
    • Review the PeerAuthentication policy to ensure it is applied to the correct namespace or service.
    • Confirm that policies are not conflicting with each other (e.g., STRICT vs PERMISSIVE modes).
  4. Service-to-Service Communication Fails
    • Use istioctl proxy-config to inspect the proxy configuration and verify that mTLS is enabled.
    • Check logs in the sidecar proxies for TLS-related errors or warnings.
Issue Possible Cause Solution
Certificate Expiry PeerAuthentication uses certificates that may have expired. Rotate certificates and update the mesh configuration accordingly.
Misconfigured Policy Applying PERMISSIVE mode where STRICT is expected. Adjust policy to enforce desired mTLS behavior.
Proxy Misconfiguration Sidecar proxies not receiving updated configuration. Restart proxies or force config refresh using istioctl.

Example: Inspecting Proxy Configuration

istioctl proxy-config cluster <pod-name> -n <namespace>
Note: Use istioctl proxy-config commands to inspect and debug proxy configurations in real-time.

Troubleshooting Checklist

  • Verify that all services in the mesh have mTLS enabled.
  • Check for conflicting PeerAuthentication policies in different namespaces.
  • Ensure that certificates are valid and not expired.
  • Confirm that sidecar proxies have received updated configurations.

11. Implementing Peer Authentication Testing

Example: mTLS Test with curl

curl -v --cert /path/to/client.crt --key /path/to/client.key https://backend-service:8443/secure-endpoint
Test Type Description Command Status
mTLS Test Verifies mutual TLS handshake between client and server curl --cert client.crt --key client.key https://backend:8443 NEW
Certificate Validation Checks if server certificate matches expected CA openssl s_client -connect backend:8443 -CAfile ca.crt DEPRECATED
Note: Ensure that all services in the mesh have valid certificates issued by the same CA.
Warning: mTLS testing requires proper certificate management and key rotation.

Testing Best Practices

  • Use curl with client certificates to simulate mTLS
  • Validate certificate chains using openssl s_client
  • Test with both mutual and one-way TLS configurations

12. Managing Peer Authentication Updates

Property Description Values Notes
peerAuthentication.mtls.mode Configures the mTLS mode for peer authentication DISABLED, PERMISSIVE, STRICT Default is PERMISSIVE
peerAuthentication.mtls.ports Defines ports to apply mTLS to 8080, 9090 Applies to specific port ranges or individual ports
peerAuthentication.mtls.caBundle Path to CA bundle for mTLS verification /etc/certs/ca.crt Required when using custom CA

Example: Update mTLS mode to STRICT

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
spec:
  mtls:
    mode: STRICT

Example: Configure mTLS per port

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: port-specific-mtls
spec:
  mtls:
    mode: PERMISSIVE
  ports:
    - number: 8080
      mtls:
        mode: STRICT
Note: Changes to PeerAuthentication are propagated to all sidecars in the mesh. Ensure updates are tested in a staging environment before applying to production.

Was this article helpful?

Related Cheat Sheets