Improve explanation of client cert authn #53408

lmktfy · 2025-11-23T15:42:13Z

Add more text to explain how clients can authenticate to the Kubernetes API by presenting a peer certificate.

Also uses Ada Lovelace as the example user, rather than @jbeda. Countess Lovelace is no longer a data subject and so privacy legislation definitely won't apply.

See the preview vs original

Split out of PR #50364

/sig auth
/language en

k8s-ci-robot · 2025-11-23T15:42:20Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign urvashi0109 for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

content/en/docs/OWNERS

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

netlify · 2025-11-23T15:52:45Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`052fb8a`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/6925e933115ba30008335895
😎 Deploy Preview	https://deploy-preview-53408--kubernetes-io-main-staging.netlify.app
📱 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 project configuration.

content/en/docs/reference/access-authn-authz/authentication.md

aman4433 · 2025-11-24T17:27:25Z

content/en/docs/reference/access-authn-authz/authentication.md

+
+{{< note >}}
+Machine identities for nodes are not the same as
+{{< glossary_tooltip text="ServiceAccounts" term_id="service-account" >}}.


Suggested change

{{< glossary_tooltip text="ServiceAccounts" term_id="service-account" >}}.

{{< glossary_tooltip text="service accounts" term_id="service-account" >}}.

Our style guide recommends "ServiceAccounts" (and I do want to emphasize that ServiceAccounts exist in the API). I'll leave it as-is.

aman4433 · 2025-11-24T17:29:53Z

content/en/docs/reference/access-authn-authz/authentication.md

-This would create a CSR for the username "jbeda", belonging to two groups, "app1" and "app2".
-
-See [Managing Certificates](/docs/tasks/administer-cluster/certificates/) for how to generate a client cert.
+This would create a signing request for the username "alovelace", belonging to two groups, "app1" and "app2". You could then use that signing request to obtain


We can use active voice.
Something like : This command creates a certificate signing request…

We can, but I don't need to fix that in this PR. I'm retaining some of the wording from the original text here.

pmengelbert · 2025-11-24T17:34:30Z

/assign @stlaz

lmktfy · 2025-11-24T19:13:19Z

@aman4433 my feedback on your feedback is based on our reviewing checklist. I do appreciate it, but I also plan to skip a couple of the points you made.

aman4433 · 2025-11-24T19:27:04Z

@aman4433 my feedback on your feedback is based on our reviewing checklist. I do appreciate it, but I also plan to skip a couple of the points you made.

All good, @lmktfy! I get your point. Appreciate the feedback, and no problem skipping those bits.

stlaz · 2025-11-25T13:09:18Z

content/en/docs/reference/access-authn-authz/authentication.md

+Client certificate authentication is enabled by passing the `--client-ca-file=<SOMEFILE>`
+option to the API server. The referenced file must contain one or more certificate authorities


To tie this to the previous paragraph, I would mention the client trust certificate authority here again:

Suggested change

Client certificate authentication is enabled by passing the `--client-ca-file=<SOMEFILE>`

option to the API server. The referenced file must contain one or more certificate authorities

Client certificate authentication is enabled by passing the `--client-ca-file=<SOMEFILE>`

option to the API server. This option configures the cluster's _client trust_ certificate authority. The referenced file must contain one or more certificate authorities

stlaz · 2025-11-25T13:15:47Z

content/en/docs/reference/access-authn-authz/authentication.md

+
+#### Kubernetes-compatible client certificates {#x509-client-certificates-k8s}
+
+Kubernetes expects to find a client certificate with a common name field.


Suggested change

Kubernetes expects to find a client certificate with a common name field.

Kubernetes expects a client certificates with a subject that contains a commonName attribute,

stlaz · 2025-11-25T13:18:19Z

content/en/docs/reference/access-authn-authz/authentication.md

+Kubernetes expects to find a client certificate with a common name field.
+The API server maps the _common name_ (OID `2.5.4.3`) field to the client's username.
+For example, if you have a certificate with the common name set to "Ada Lovelace"
+and the certificate also has a _uid_ attribute, (OID `0.9.2342.19200300.100.1.1`)


Is there a reason to include the uid here? Is it to show that Kubernetes will ignore it?

Yes, that's right. You might have a client cert issuing process that you need to change, because Kubernetes only pays attention to commonName.

stlaz · 2025-11-25T13:21:03Z

content/en/docs/reference/access-authn-authz/authentication.md

+
+You can map a user into groups by statically including group information into
+the certificate. For each group that the user is a member of, add the group
+name as an organization (OID `2.5.6.4`).


Suggested change

name as an organization (OID `2.5.6.4`).

name as an organization (OID `2.5.6.4`) in your certificate's subject.

stlaz · 2025-11-25T13:22:05Z

content/en/docs/reference/access-authn-authz/authentication.md

+You can map a user into groups by statically including group information into
+the certificate. For each group that the user is a member of, add the group
+name as an organization (OID `2.5.6.4`).
+To include multiple group memberships for a user, include multiple organization fields in the certificate (the order does not matter).


Suggested change

To include multiple group memberships for a user, include multiple organization fields in the certificate (the order does not matter).

To include multiple group memberships for a user, include multiple organization attributes (RDNs?) in the certificate (the order does not matter).

stlaz · 2025-11-25T13:27:18Z

content/en/docs/reference/access-authn-authz/authentication.md

+To include multiple group memberships for a user, include multiple organization fields in the certificate (the order does not matter).
+For the example user, the distinguished name might be CN=Ada Lovelace,O=Users,O=Staff,O=Programmers, which would place her into the groups "Programmers", "Staff", "system:authenticated", and "Users".
+
+Kubernetes can use the same approach for server identities. For example: a node with the domain name "server-1a-antartica42.cluster.example" and using node name "server-1a-antartica42" could use a certificate issued to "CN=system:node:server-1a-antartica42,O=system:nodes". The node's username is then "system:node:server-1a-antartica42", and the node is a member of "system:authenticated" and "system:nodes".


This paragraph is a bit confusing. Is this still discussing client certs? Why mention servers?

I wanted people to know that you typically set the commonName based on the Node name, not its FQDN; that's not otherwise obvious.

Anyway, I reworded it.

The commit makes a minimal number of less related changes, to ensure that the page still makes sense.

stlaz · 2025-11-26T08:59:39Z

content/en/docs/reference/access-authn-authz/authentication.md

+#### Kubernetes-compatible client certificates {#x509-client-certificates-k8s}

-This would create a CSR for the username "jbeda", belonging to two groups, "app1" and "app2".
+You can present a valid certificate, issued with a trust chain that the API server accepts


Suggested change

You can present a valid certificate, issued with a trust chain that the API server accepts

You can present a valid certificate, issued by a CA in a trust chain that the API server accepts

stlaz · 2025-11-26T09:07:25Z

content/en/docs/reference/access-authn-authz/authentication.md

+with uid set to "aaking1815", Kubernetes considers that the client's username is "Ada Lovelace";
+Kubernetes ignores the `uid` attribute.
+
+##### Group mapping {#x509-client-certificates-k8s-group}


Didn't you originally also include guide to map user UID? I think we would want all of username/group/uid mapping mentioned.

stlaz · 2025-11-26T09:17:03Z

content/en/docs/reference/access-authn-authz/authentication.md

+Kubernetes can use the same approach for node identity; nodes are clients of the Kubernetes API server
+(also, although less relevant here, the API server is usually also a client of each node).
+For example: a Node "server-1a-antartica42", with the domain name "server-1a-antartica42.cluster.example", could use a certificate issued to "CN=system:node:server-1a-antartica42,O=system:nodes". The node's username is then "system:node:server-1a-antartica42", and the node is a member of "system:authenticated" and "system:nodes".


This is now much better 👍

I wonder if we should mention anywhere that these node identities are typically used by kubelets to be extra explicit.

stlaz · 2025-11-26T09:20:26Z

content/en/docs/reference/access-authn-authz/authentication.md

+This would create a signing request for the username "alovelace", belonging to two groups, "app1" and "app2". You could then use that signing request to obtain
+a certificate.


Suggested change

This would create a signing request for the username "alovelace", belonging to two groups, "app1" and "app2". You could then use that signing request to obtain

a certificate.

This would create a signing request for the username "alovelace", belonging to two groups, "app1" and "app2". You could then have that signing request be signed by your cluster's client trust certificate authority to obtain a certificate you can use for client authentication to your cluster.

k8s-ci-robot added sig/auth Categorizes an issue or PR as relevant to SIG Auth. language/en Issues or PRs related to English language labels Nov 23, 2025

k8s-ci-robot requested a review from deads2k November 23, 2025 15:42

k8s-ci-robot requested a review from liggitt November 23, 2025 15:42

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Nov 23, 2025

enj added this to SIG Auth Nov 24, 2025

enj moved this to Needs Triage in SIG Auth Nov 24, 2025

aman4433 reviewed Nov 24, 2025

View reviewed changes

k8s-ci-robot assigned stlaz Nov 24, 2025

lmktfy force-pushed the 20251123_improve_client_cert_authn_advice branch from 2ad6db0 to 19e3d64 Compare November 24, 2025 19:11

stlaz reviewed Nov 25, 2025

View reviewed changes

Improve explanation of client cert authn

052fb8a

The commit makes a minimal number of less related changes, to ensure that the page still makes sense.

lmktfy force-pushed the 20251123_improve_client_cert_authn_advice branch from 19e3d64 to 052fb8a Compare November 25, 2025 17:36

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Nov 25, 2025

stlaz reviewed Nov 26, 2025

View reviewed changes

	{{< glossary_tooltip text="ServiceAccounts" term_id="service-account" >}}.
	{{< glossary_tooltip text="service accounts" term_id="service-account" >}}.

		Client certificate authentication is enabled by passing the `--client-ca-file=<SOMEFILE>`
		option to the API server. The referenced file must contain one or more certificate authorities


		#### Kubernetes-compatible client certificates {#x509-client-certificates-k8s}

		Kubernetes expects to find a client certificate with a common name field.

	Kubernetes expects to find a client certificate with a common name field.
	Kubernetes expects a client certificates with a subject that contains a commonName attribute,

	name as an organization (OID `2.5.6.4`).
	name as an organization (OID `2.5.6.4`) in your certificate's subject.

	To include multiple group memberships for a user, include multiple organization fields in the certificate (the order does not matter).
	To include multiple group memberships for a user, include multiple organization attributes (RDNs?) in the certificate (the order does not matter).

	You can present a valid certificate, issued with a trust chain that the API server accepts
	You can present a valid certificate, issued by a CA in a trust chain that the API server accepts

		This would create a signing request for the username "alovelace", belonging to two groups, "app1" and "app2". You could then use that signing request to obtain
		a certificate.

Improve explanation of client cert authn #53408

Are you sure you want to change the base?

Improve explanation of client cert authn #53408

Uh oh!

Conversation

lmktfy commented Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Nov 23, 2025

Uh oh!

netlify bot commented Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmktfy Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pmengelbert commented Nov 24, 2025

Uh oh!

lmktfy commented Nov 24, 2025

Uh oh!

aman4433 commented Nov 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lmktfy commented Nov 23, 2025 •

edited

Loading

netlify bot commented Nov 23, 2025 •

edited

Loading

lmktfy Nov 24, 2025 •

edited

Loading