Merge pull request #35473 from skrthomas/OSDOCS-2415

OSDOCS-2415: Adding mTLS info

Author: mikemckiernan

modules/nw-ingress-controller-configuration-parameters.adoc

@@ -106,6 +106,14 @@ The Ingress Operator also converts the TLS `1.0` of an `Old` or `Custom` profile
 Ciphers and the minimum TLS version of the configured security profile are reflected in the `TLSProfile` status.
 ====
 
+|`clientTLS`
+|`clientTLS` authenticates client access to the cluster and services; as a result, mutual TLS authentication is enabled. If not set, then client TLS is not enabled.
+
+`clientTLS` has the required subfields, `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA`.
+
+The `ClientCertificatePolicy` subfield accepts one of the two values: `Required` or `Optional`. The `ClientCA` subfield specifies a config map that is in the openshift-config namespace. The config map should contain a CA certificate bundle.
+The `AllowedSubjectPatterns` is an optional value that specifies a list of regular expressions, which are matched against the distinguished name on a valid client certificate to filter requests.  The regular expressions must use PCRE syntax. At least one pattern must match a client certificate's distinguished name; otherwise, the ingress controller rejects the certificate and denies the connection. If not specified, the ingress controller does not reject certificates based on the distinguished name.
+
 |`routeAdmission`
 |`routeAdmission` defines a policy for handling new route claims, such as allowing or denying claims across namespaces.
 

modules/nw-mutual-tls-auth.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * ingress/ingress-operator.adoc
+
+[id=nw-mutual-tls-auth_{context}]
+= Configuring mutual TLS authentication
+
+You can configure the Ingress Controller to enable mutual TLS (mTLS) authentication by setting a `spec.clientTLS` value. The `clientTLS` value configures the Ingress Controller to verify client certificates. This configuration includes setting a `clientCA` value, which is a reference to a config map. The config map contains the PEM-encoded CA certificate bundle that is used to verify a client's certificate. Optionally, you can configure a list of certificate subject filters.
+
+If the `clientCA` value specifies an X509v3 certificate revocation list (CRL) distribution point, the Ingress Operator downloads the CRL and configures the Ingress Controller to acknowledge it. Requests that do not provide valid certificates are rejected.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+
+.Procedure
+. Create a config map that is in the `openshift-config` namespace:
++
+[source,terminal]
+----
+$ oc create configmap router-ca-certs-default --from-file=ca-bundle.pem=client-ca.crt -n openshift-config
+----
++
+[NOTE]
+====
+The config map data key must be `ca-bundle.pem`, and the data value must be a CA certificate in PEM format.
+====
+
+. Edit the `IngressController` resource in the `openshift-ingress-operator` project:
++
+[source,terminal]
+----
+$ oc edit IngressController default -n openshift-ingress-operator
+----
+
+. Add the spec.clientTLS field and subfields to configure mutual TLS:
++
+.Sample `IngressController` CR for a `clientTLS` profile that specifies filtering patterns
+[source,yaml]
+----
+  apiVersion: operator.openshift.io/v1
+  kind: IngressController
+  metadata:
+    name: default
+    namespace: openshift-ingress-operator
+  spec:
+    clientTLS:
+      clientCertificatePolicy: Required
+      clientCA:
+        name: router-ca-certs-default
+      allowedSubjectPatterns:
+      - "^/CN=example.com/ST=NC/C=US/O=Security/OU=OpenShift$"
+----

networking/ingress-operator.adoc

@@ -28,6 +28,8 @@ include::modules/tls-profiles-understanding.adoc[leveloffset=+3]
 // Configuring the TLS profile for the Ingress Controller
 include::modules/tls-profiles-ingress-configuring.adoc[leveloffset=+3]
 
+include::modules/nw-mutual-tls-auth.adoc[leveloffset=+3]
+
 include::modules/nw-ingress-controller-endpoint-publishing-strategies.adoc[leveloffset=+2]
 
 include::modules/nw-ingress-view.adoc[leveloffset=+1]