--- title: PeerAuthentication description: Peer authentication configuration for workloads. location: https://istio.io/docs/reference/config/security/peer_authentication.html layout: protoc-gen-docs generator: protoc-gen-docs schema: istio.security.v1beta1.PeerAuthentication aliases: [/docs/reference/config/security/v1beta1/peer_authentication] number_of_entries: 3 ---

## PeerAuthentication

PeerAuthentication defines how traffic will be tunneled (or not) to the sidecar.

Examples:

Policy to allow mTLS traffic for all workloads under namespace `foo`:

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

For mesh level, put the policy in root-namespace according to your Istio installation.

Policies to allow both mTLS & plaintext traffic for all workloads under namespace `foo`, but require mTLS for workload `finance`.

    apiVersion: security.istio.io/v1beta1
    kind: PeerAuthentication
    metadata:
      name: default
      namespace: foo
    spec:
      mtls:
        mode: PERMISSIVE
    ---
    apiVersion: security.istio.io/v1beta1
    kind: PeerAuthentication
    metadata:
      name: finance
      namespace: foo
    spec:
      selector:
        matchLabels:
          app: finance
      mtls:
        mode: STRICT

Policy to allow mTLS strict for all workloads, but leave port 8080 to plaintext:

    apiVersion: security.istio.io/v1beta1
    kind: PeerAuthentication
    metadata:
      name: default
      namespace: foo
    spec:
      selector:
        matchLabels:
          app: finance
      mtls:
        mode: STRICT
      portLevelMtls:
        8080:
          mode: DISABLE

Policy to inherit mTLS mode from namespace (or mesh) settings, and overwrite settings for port 8080

    apiVersion: security.istio.io/v1beta1
    kind: PeerAuthentication
    metadata:
      name: default
      namespace: foo
    spec:
      selector:
        matchLabels:
          app: finance
      mtls:
        mode: UNSET
      portLevelMtls:
        8080:
          mode: DISABLE

Field | Type | Description | Required
--- | --- | --- | ---
`selector` | `WorkloadSelector` | The selector determines the workloads to apply the ChannelAuthentication on. If not set, the policy will be applied to all workloads in the same namespace as the policy. | No
`mtls` | `MutualTLS` | Mutual TLS settings for workload. If not defined, inherit from parent. | No
`portLevelMtls` | `map<uint32, MutualTLS>` | Port specific mutual TLS settings. These only apply when a workload selector is specified. | No

## PeerAuthentication.MutualTLS

Mutual TLS settings.

Field | Type | Description | Required
--- | --- | --- | ---
`mode` | `Mode` | Defines the mTLS mode used for peer authentication. | No

## PeerAuthentication.MutualTLS.Mode

Name | Description
--- | ---
`UNSET` | Inherit from parent, if has one. Otherwise treated as PERMISSIVE.
`DISABLE` | Connection is not tunneled.
`PERMISSIVE` | Connection can be either plaintext or mTLS tunnel.
`STRICT` | Connection is an mTLS tunnel (TLS with client cert must be presented).