Update Documentation for Client-Cert Authentication misleading #10687

[clauspruefer]

Update / restructure "Client Cert Authentication" Documentation sub-section

Types of changes

• Update client-auth documentation containing all needed information on one page / sub-sections

Which issue/s this PR fixes

fixes #10687

How Has This Been Tested?

Already tested.

Checklist:

• I have updated the documentation accordingly.
• I've read the CONTRIBUTION guide
• I have added unit and/or e2e tests to cover my changes.
• All new and existing tests passed.

Viewable Documentation / Page:

https://github.com/clauspruefer/ingress-nginx/tree/main/docs/examples/auth/client-certs

[netlify]

✅ Deploy Preview for kubernetes-ingress-nginx ready!

Name	Link
🔨 Latest commit	17b8830
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-ingress-nginx/deploys/656eff31691db90008e14b9d
😎 Deploy Preview	https://deploy-preview-10705--kubernetes-ingress-nginx.netlify.app/examples/auth/client-certs
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[k8s-ci-robot]

This issue is currently awaiting triage.

If Ingress contributors determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: clauspruefer / name: Claus Prüfer (349cbed, 764daa8, 07b8581, be9eb0f, 6e570f4, 1bffa1e, 17b8830)

[k8s-ci-robot]

Welcome @clauspruefer!

It looks like this is your first PR to kubernetes/ingress-nginx 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/ingress-nginx has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @clauspruefer. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[clauspruefer]

Sorry, currently the client-auth doc did not contain wrong information, it just was a bit misleading.
I updated to correct information.

[clauspruefer]

Currently verified working in End2End test (including whitelist filtering):

Cert Generation

kubectl -n spx-test create secret generic ca-spxcomserver-spx-webui-test-tls-cert --from-file=ca.crt=./ca-cert.pem --from-file=tls.crt=./server-cert.pem --from-file=tls.key=./server-key.pem

kubectl create secret tls spxcomserver-spx-webui-test-tls-cert --cert ./server-cert.pem --key ./server-key.pem

Ingress Definition

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
    nginx.ingress.kubernetes.io/auth-tls-secret: spx-test/ca-spxcomserver-spx-webui-test-tls-cert
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/whitelist-source-range: x.x.x.x/32
  creationTimestamp: "2023-11-30T12:53:58Z"
  generation: 1
  name: spxcomserver-spx-webui-test-tls-ingress
  namespace: spx-test
  resourceVersion: "4939686"
  uid: 98d5a78c-2b25-4424-b0eb-9c73cb63f795
spec:
  ingressClassName: class-ingress-webui-test
  rules:
  - host: xyz.click-it.online
    http:
      paths:
      - backend:
          service:
            name: spxcomserver-spx-webui-test-svc
            port:
              number: 80
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - spx-webui-test.click-it.online
    secretName: spxcomserver-spx-webui-test-tls-cert
status:
  loadBalancer:
    ingress:
    - ip: x.x.x.x

Client is Mozilla Firefox with imported .p12 (CA-cert, ClientCert, ClientKey).

[clauspruefer]

Hi, this PR seems to be stuck. Just a few words why this all came up (important!).

Our company runs a project where Client-Cert-Authentication is required. Our developers are expirienced with Apache-TLS, Client-Cert Authentication, also NGINX configurations which use TLS Client-Cert-Auth have been setup lately.

Now we switched to Kubernetes and ingress-nginx which relies on kubectl secret. The secret certificate handling and especially the ingress-nginx / .yaml integration seems quite unhandy if you have used the very simple Apache2 configuration, where you just have to link:

1. CA-Certificate
2. Server Certificate
3. Server Private Key / eventually Passphrase if encrypted

I think this is where the confusion starts with kubectl secret. The multiple import options for secrets (generic and TLS) and the dividing of ingress-nginx into "annotations" AND TLS configuration.

Especially if you are expirienced with SSL / TLS you always include a CA-Certificate for the "Transport" Layer in a Server-Configuration. Very seldom you use just Server-Cert and Server-Key without CA-Certificate.

But exactly this is pointed out in the Kubernetes-Documentaion importing TLS with kubectl create secret tls spxcomserver-spx-webui-test-tls-cert --cert ./server-cert.pem --key ./server-key.pem.

The way by doing kubectl -n spx-test create secret generic ca-spxcomserver-spx-webui-test-tls-cert --from-file=ca.crt=./ca-cert.pem --from-file=tls.crt=./server-cert.pem --from-file=tls.key=./server-key.pem on command line is a VERY-UNUSUAL (double =tls.crt=filename).

So the implementation in our Python-Kubernetes-Installer failed because the double = assignment (which also seems like a workaround of the Kubernetes OOP Backend-Handling). So our developers thought that the ingress-nginx behaviour / documentation was broken because the double = assignment :(

So my intention was to setup a clear documentation how to link certificates to ingress-nginx / Kubernetes with this PR (please check the rendered output in my fork, i added the link to the PR description).

In my oppinion the only thing which needs ajustment is to check, if you can link the same secret-reference in the following config:

nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secret-ref

and (config without namespace, secret needs to be inside correct namespace)

tls:
- hosts:
  - domain.com
  secretName: secret-ref

And afterwards emphasis the cert-import ALWAYS by following command:

kubectl -n spx-test create secret generic ca-spxcomserver-spx-webui-test-tls-cert --from-file=ca.crt=./ca-cert.pem --from-file=tls.crt=./server-cert.pem --from-file=tls.key=./server-key.pem

@strongjz I think this is really important for non-tls-experts and global internet-security should use such features more often, so please consider using my adapted documentation.

[longwuyuan]

@clauspruefer I could not find the key "ca.crt" type info in the help for the kubectl create secret command. So this information is a super helpful improvement to the docs. Thanks for the contribution.

/ok-to-test

[longwuyuan]

@clauspruefer I would even recommend that you submit a PR in the other sig that maintains the kubectl binary, to add the examples you have shown here.

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: clauspruefer, longwuyuan

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• docs/OWNERS [longwuyuan]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[clauspruefer]

@clauspruefer I would even recommend that you submit a PR in the other sig that maintains the kubectl binary, to add the examples you have shown here.

/lgtm

Thanx for the feedback :). I will open PR asap. TLS/SSL needs to be implemented correctly to increase global internet security.

[longwuyuan]

True. In this case though since those key:value pairs allowed for cert, chain and the key, it seems the implementation exists but precise docs for including 3 hashes is not common knowledge.

Maybe people were concatenating cert+chain in a single file (I may have tried that too once or twice, not sure).