From ae6711d06cca77503cb7541d0bd404314f99b31f Mon Sep 17 00:00:00 2001 From: Fernando Diaz Date: Fri, 19 Oct 2018 14:20:50 -0500 Subject: [PATCH] Add Better Documentation for using AuthTLS Enhances the documentation for enabling and using Mutual Authentication. --- docs/examples/auth/client-certs/README.md | 36 ++++++++++++++++---- docs/examples/auth/client-certs/ingress.yaml | 5 ++- 2 files changed, 32 insertions(+), 9 deletions(-) diff --git a/docs/examples/auth/client-certs/README.md b/docs/examples/auth/client-certs/README.md index e0dd1efe07..baa91eccdf 100644 --- a/docs/examples/auth/client-certs/README.md +++ b/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: -`kubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default` +1. Add the annotations as provided in the [ingress.yaml](ingress.yaml) example to your own ingress resources as required. +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. diff --git a/docs/examples/auth/client-certs/ingress.yaml b/docs/examples/auth/client-certs/ingress.yaml index 559a483daf..6d7a9f52e1 100644 --- a/docs/examples/auth/client-certs/ingress.yaml +++ b/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` - # 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/auth-tls-chain" + # Create the secret containing the trusted ca certificates + nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret" # 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