Add Better Documentation for using AuthTLS (#3275)

Enhances the documentation for enabling and using Mutual Authentication.

docs/examples/auth/client-certs/README.md

@@ -1,11 +1,35 @@
 # Client Certificate Authentication
-It is possible to enable Client Certificate Authentication using additional annotations in Ingress resources, created by you.
 
+It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource.
+Before getting started you must have the following Certificates Setup:
+
+1. CA certificate and Key(Intermediate Certs need to be in CA)
+2. Server Certificate(Signed by CA) and Key (CN should be equal the the hostname you will use)
+3. Client Certificate(Signed by CA) and Key
+
+## Creating Certificate Secrets
+
+There are many different ways of configuring your secrets to enable Client-Certificate
+Authentication to work properly.
+
+1. You can create a secret containing just the CA certificate and another
+    Secret containing the Server Certificate which is Signed by the CA.
+    ```bash
+    $ kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt
+    $ kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key
+    ```
+
+2. You can create a secret containing CA certificate along with the Server
+    Certificate, that can be used for both TLS and Client Auth.
+    ```bash
+    $ kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
+    ```
+    
+Note: The CA Certificate must contain the trusted certificate authority chain to verify client certificates.
+    
 ## Setup Instructions
-1. Create a file named `ca.crt` containing the trusted certificate authority chain to verify client certificates. All of the certificates must be in PEM format.  
-   *NB:* The file containing the trusted certificates must be named `ca.crt` exactly - this is expected to be found in the secret.
 
-2. Create a secret from this file:  
+1. Add the annotations as provided in the [ingress.yaml](ingress.yaml) example to your own ingress resources as required.
-`kubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default`
+2. Test by performing a curl against the Ingress Path without the Client Cert and expect a Status Code 400.
+3. Test by performing a curl against the Ingress Path with the Client Cert and expect a Status Code 200.
 
-3. Add the annotations as provided in the [ingress.yaml](ingress.yaml) example to your own ingress resources as required.

docs/examples/auth/client-certs/ingress.yaml

@@ -4,9 +4,8 @@ metadata:
   annotations:
     # Enable client certificate authentication
     nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
-    # Create the secret containing the trusted ca certificates with `kubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default`
+    # Create the secret containing the trusted ca certificates
-    # NB: The file _must_ be named "ca.crt" and nothing else. This filename is expected to be found in the secret.
+    nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
-    nginx.ingress.kubernetes.io/auth-tls-secret: "default/auth-tls-chain"
     # Specify the verification depth in the client certificates chain
     nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
     # Specify an error page to be redirected to verification errors