|
| 1 | +## About mutual Transport Layer Security (mTLS) |
| 2 | + |
| 3 | +Mutual Transport Layer Security (mTLS) is a protocol that enables two parties to authenticate each other. However, configuring mTLS settings can be confusing and a common source of misconfiguration. First, you need to understand the following Istio resources and concepts[1]. |
| 4 | + |
| 5 | +- `PeerAuthentication` is used to configure what type of mTLS traffic the sidecar will **accept**. |
| 6 | +Its `PERMISSIVE` mode[2] means plaintext or mTLS traffic will all be accepted by the sidecar. Its `STRICT` mode means only mTLS traffic will be accepted by the sidecar. |
| 7 | + |
| 8 | +- `DestinationRule` is used to configure what type of TLS traffic the sidecar will **send**. |
| 9 | +Its `DISABLE` mode will allow the sidecar to send plaintext, while its `SIMPLE`, `MUTUAL`, and `ISTIO_MUTUAL` mode will configure the sidecar to originate a TLS connection. |
| 10 | + |
| 11 | +- `Auto mTLS` means: without any configuration, all inter-mesh traffic will be mTLS encrypted. |
| 12 | +This is configured by a global mesh config field `enableAutoMtls` and it is enabled by default. |
| 13 | + |
| 14 | +## Default Settings |
| 15 | + |
| 16 | +Because `auto mTLS` is enabled by default. Traffic **sent** through a sidecar is mTLS encrypted. It doesn't matter which `PeerAuthentication` mode is configured. You can use mTLS without changes to the application or service code. The mTLS is handled entirely between the two sidecar proxies. |
| 17 | + |
| 18 | +On the other hand, `PeerAuthentication` is set to the `PERMISSIVE` mode by default, where the sidecars in Service Mesh **accept** both plain-text traffic and connections that are encrypted using mTLS. This mode provides greater flexibility for the mTLS on-boarding process. |
| 19 | + |
| 20 | +## Enabling strict mTLS mode by namespace |
| 21 | + |
| 22 | +If you need to lock down workloads to only **accept** mTLS traffic, you may apply the following change to enable the `STRICT` mode of `PeerAuthentication`. |
| 23 | + |
| 24 | +- PeerAuthentication Policy example for a namespace |
| 25 | + |
| 26 | +``` |
| 27 | +$ oc apply -n <namespace> -f - <<EOF |
| 28 | +apiVersion: security.istio.io/v1beta1 |
| 29 | +kind: PeerAuthentication |
| 30 | +metadata: |
| 31 | + name: default |
| 32 | + namespace: <namespace> |
| 33 | +spec: |
| 34 | + mtls: |
| 35 | + mode: STRICT |
| 36 | +EOF |
| 37 | +``` |
| 38 | + |
| 39 | +If you manually disabled the `auto mTLS` mesh config field and you are setting `PeerAuthentication` to `STRICT` mode, you also need to create a `DestinationRule` resource with `MUTUAL` or `ISTIO_MUTUAL` mode for your service. The following example enables mTLS to all destination hosts in the `<namespace>`. |
| 40 | + |
| 41 | +- DestinationRule example |
| 42 | + |
| 43 | +``` |
| 44 | +$ oc apply -n <namespace> -f - <<EOF |
| 45 | +apiVersion: networking.istio.io/v1alpha3 |
| 46 | +kind: DestinationRule |
| 47 | +metadata: |
| 48 | + name: enable-mtls |
| 49 | + namespace: <namespace> |
| 50 | +spec: |
| 51 | + host: "*.<namespace>.svc.cluster.local" |
| 52 | + trafficPolicy: |
| 53 | + tls: |
| 54 | + mode: ISTIO_MUTUAL |
| 55 | +EOF |
| 56 | +``` |
| 57 | +a. Replace <namespace> with the namespace where the service is located. |
| 58 | + |
| 59 | + |
| 60 | +## Enabling strict mTLS across the whole service mesh |
| 61 | + |
| 62 | +If you need to lock down mTLS for the whole mesh, you may apply the above PeerAuthentication Policy example for the istiod namespace, for example, `istio-system` namespace. Moreover, you also need to apply a `DestinationRule` to disable mTLS when talking to API server, as API server doesn't have sidecar. You should apply similar `DestinationRule` for other services that don't have sidecar in this mode. |
| 63 | + |
| 64 | +- PeerAuthentication Policy example for the whole mesh |
| 65 | + |
| 66 | +``` |
| 67 | +$ oc apply -n istio-system -f - <<EOF |
| 68 | +apiVersion: security.istio.io/v1 |
| 69 | +kind: PeerAuthentication |
| 70 | +metadata: |
| 71 | + name: default |
| 72 | + namespace: istio-system |
| 73 | +spec: |
| 74 | + mtls: |
| 75 | + mode: STRICT |
| 76 | +--- |
| 77 | +apiVersion: networking.istio.io/v1beta1 |
| 78 | +kind: DestinationRule |
| 79 | +metadata: |
| 80 | + name: api-server |
| 81 | + namespace: istio-system |
| 82 | +spec: |
| 83 | + host: kubernetes.default.svc.cluster.local |
| 84 | + trafficPolicy: |
| 85 | + tls: |
| 86 | + mode: DISABLE |
| 87 | +EOF |
| 88 | +``` |
| 89 | + |
| 90 | +## Setting the minimum and maximum protocol versions |
| 91 | + |
| 92 | +See the Istio documentation ["Istio Workload Minimum TLS Version Configuration"](https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/). |
| 93 | + |
| 94 | +## Validating encryption with Kiali |
| 95 | + |
| 96 | +The Kiali console offers several ways to validate whether or not your applications, services, and workloads have mTLS encryption enabled. |
| 97 | + |
| 98 | +The `Services Detail Overview` page displays a Security icon on the graph edges where at least one request with mTLS enabled is present. Also note that Kiali displays a lock icon in the `Network` section next to ports that are configured for mTLS. |
| 99 | + |
| 100 | +### Additional resources |
| 101 | + |
| 102 | +References: |
| 103 | +- [1] https://istio.io/latest/docs/ops/configuration/traffic-management/tls-configuration/ |
| 104 | +- [2] https://istio.io/latest/docs/concepts/security/#permissive-mode |
0 commit comments