From 2a3a72e16cbf617b8767d4356d512b84d59c3561 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Tue, 4 Mar 2025 20:22:32 +0000 Subject: [PATCH] Move CSR for client certificate to tasks section The moved documentation describes a task, so move it to the documentation section that describes tasks. --- .../access-authn-authz/authentication.md | 5 +- .../certificate-signing-requests.md | 125 +----------- .../tasks/tls/certificate-issue-client-csr.md | 185 ++++++++++++++++++ 3 files changed, 188 insertions(+), 127 deletions(-) create mode 100644 content/en/docs/tasks/tls/certificate-issue-client-csr.md diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index 1f52aea279..d32e9dbb5f 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -33,9 +33,7 @@ presents a valid certificate signed by the cluster's certificate authority the username from the common name field in the 'subject' of the cert (e.g., "/CN=bob"). From there, the role based access control (RBAC) sub-system would determine whether the user is authorized to perform a specific operation on a -resource. For more details, refer to the normal users topic in -[certificate request](/docs/reference/access-authn-authz/certificate-signing-requests/#normal-user) -for more details about this. +resource. In contrast, service accounts are users managed by the Kubernetes API. They are bound to specific namespaces, and created automatically by the API server or @@ -1815,5 +1813,6 @@ You can only make `SelfSubjectReview` requests if: ## {{% heading "whatsnext" %}} +* To learn about issuing certificates for users, read [Issue a Certificate for a Kubernetes API Client Using A CertificateSigningRequest](/docs/tasks/tls/certificate-issue-client-csr/) * Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/) * Read the [client authentication reference (v1)](/docs/reference/config-api/client-authentication.v1/) diff --git a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md index d9bf572d49..66ee3149e0 100644 --- a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md +++ b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md @@ -489,133 +489,10 @@ signer-unlinked ClusterTrustBundles **must not** contain a colon (`:`). The contents of ClusterTrustBundles can be injected into the container filesystem, similar to ConfigMaps and Secrets. See the [clusterTrustBundle projected volume source](/docs/concepts/storage/projected-volumes#clustertrustbundle) for more details. - -## How to issue a certificate for a user {#normal-user} - -A few steps are required in order to get a normal user to be able to -authenticate and invoke an API. First, this user must have a certificate issued -by the Kubernetes cluster, and then present that certificate to the Kubernetes API. - -### Create private key - -The following scripts show how to generate PKI private key and CSR. It is -important to set CN and O attribute of the CSR. CN is the name of the user and -O is the group that this user will belong to. You can refer to -[RBAC](/docs/reference/access-authn-authz/rbac/) for standard groups. - -```shell -openssl genrsa -out myuser.key 2048 -openssl req -new -key myuser.key -out myuser.csr -subj "/CN=myuser" -``` - -### Create a CertificateSigningRequest {#create-certificatessigningrequest} - -Create a [CertificateSigningRequest](/docs/reference/kubernetes-api/authentication-resources/certificate-signing-request-v1/) -and submit it to a Kubernetes Cluster via kubectl. Below is a script to generate the -CertificateSigningRequest. - -```shell -cat < myuser.crt -``` - -### Create Role and RoleBinding - -With the certificate created it is time to define the Role and RoleBinding for -this user to access Kubernetes cluster resources. - -This is a sample command to create a Role for this new user: - -```shell -kubectl create role developer --verb=create --verb=get --verb=list --verb=update --verb=delete --resource=pods -``` - -This is a sample command to create a RoleBinding for this new user: - -```shell -kubectl create rolebinding developer-binding-myuser --role=developer --user=myuser -``` - -### Add to kubeconfig - -The last step is to add this user into the kubeconfig file. - -First, you need to add new credentials: - -```shell -kubectl config set-credentials myuser --client-key=myuser.key --client-certificate=myuser.crt --embed-certs=true - -``` - -Then, you need to add the context: - -```shell -kubectl config set-context myuser --cluster=kubernetes --user=myuser -``` - -To test it, change the context to `myuser`: - -```shell -kubectl config use-context myuser -``` - ## {{% heading "whatsnext" %}} * Read [Manage TLS Certificates in a Cluster](/docs/tasks/tls/managing-tls-in-a-cluster/) +* Read [Issue a Certificate for a Kubernetes API Client Using A CertificateSigningRequest](/docs/tasks/tls/certificate-issue-client-csr/) * View the source code for the kube-controller-manager built in [signer](https://github.com/kubernetes/kubernetes/blob/32ec6c212ec9415f604ffc1f4c1f29b782968ff1/pkg/controller/certificates/signer/cfssl_signer.go) * View the source code for the kube-controller-manager built in diff --git a/content/en/docs/tasks/tls/certificate-issue-client-csr.md b/content/en/docs/tasks/tls/certificate-issue-client-csr.md new file mode 100644 index 0000000000..b5fc9f1ed3 --- /dev/null +++ b/content/en/docs/tasks/tls/certificate-issue-client-csr.md @@ -0,0 +1,185 @@ +--- +title: Issue a Certificate for a Kubernetes API Client Using A CertificateSigningRequest +api_metadata: +- apiVersion: "certificates.k8s.io/v1" + kind: "CertificateSigningRequest" + override_link_text: "CSR v1" +weight: 80 + +# Docs maintenance note +# +# If there is a future page /docs/tasks/tls/certificate-issue-client-manually/ then this page +# should link there, and the new page should link back to this one. +--- + + + +Kubernetes lets you use a public key infrastructure (PKI) to authenticate to your cluster +as a client. + +A few steps are required in order to get a normal user to be able to +authenticate and invoke an API. First, this user must have an [X.509](https://www.itu.int/rec/T-REC-X.509) certificate +issued by an authority that your Kubernetes cluster trusts. The client must then present that certificate to the Kubernetes API. + +You use a [CertificateSigningRequest](/concepts/security/certificate-signing-requests/) +as part of this process, and either you or some other principal must approve the request. + + +You will create a private key, and then get a certificate issued, and finally configure +that private key for a client. + +## {{% heading "prerequisites" %}} + +* {{< include "task-tutorial-prereqs.md" >}} + +* You need the `kubectl`, `openssl` and `base64` utilities. + +This page assumes you are using Kubernetes {{< glossary_tooltip term_id="rbac" text="role based access control" >}} (RBAC). +If you have alternative or additional security mechanisms around authorization, you need to account for those as well. + + + +## Create private key + +In this step, you create a private key. You need to keep this document secret; anyone who has it can impersonate the user. + +```shell +# Create a private key +openssl genrsa -out myuser.key 3072 +``` + +## Create an X.509 certificate signing request {#create-x.509-certificatessigningrequest} + +{{< note >}} +This is not the same as the similarly-named CertificateSigningRequest API; the file you generate here goes into the +CertificateSigningRequest. +{{< /note >}} + +It is important to set CN and O attribute of the CSR. CN is the name of the user and O is the group that this user will belong to. +You can refer to [RBAC](/docs/reference/access-authn-authz/rbac/) for standard groups. + +```shell +# Change the common name "myuser" to the actual username that you want to use +openssl req -new -key myuser.key -out myuser.csr -subj "/CN=myuser" +``` + +## Create a Kubernetes CertificateSigningRequest {#create-k8s-certificatessigningrequest} + +Encode the CSR document using this command: + +```shell +cat myuser.csr | base64 | tr -d "\n" +``` + +Create a [CertificateSigningRequest](/docs/reference/kubernetes-api/authentication-resources/certificate-signing-request-v1/) +and submit it to a Kubernetes Cluster via kubectl. Below is a snippet of shell that you can use to generate the +CertificateSigningRequest. + +```shell +cat < myuser.crt +``` + +## Configure the certificate into kubeconfig + +The next step is to add this user into the kubeconfig file. + +First, you need to add new credentials: + +```shell +kubectl config set-credentials myuser --client-key=myuser.key --client-certificate=myuser.crt --embed-certs=true + +``` + +Then, you need to add the context: + +```shell +kubectl config set-context myuser --cluster=kubernetes --user=myuser +``` + +To test it: + +```shell +kubectl --context myuser auth whoami +``` + +You should see output confirming that you are “myuser“. + +## Create Role and RoleBinding + +{{< note >}} +If you don't use Kubernetes RBAC, skip this step and make the appropriate changes for the authorization mechanism +your cluster actually uses. +{{< /note >}} + +With the certificate created it is time to define the Role and RoleBinding for +this user to access Kubernetes cluster resources. + +This is a sample command to create a Role for this new user: + +```shell +kubectl create role developer --verb=create --verb=get --verb=list --verb=update --verb=delete --resource=pods +``` + +This is a sample command to create a RoleBinding for this new user: + +```shell +kubectl create rolebinding developer-binding-myuser --role=developer --user=myuser +``` + +## {{% heading "whatsnext" %}} + +* Read [Manage TLS Certificates in a Cluster](/docs/tasks/tls/managing-tls-in-a-cluster/) +* For details of X.509 itself, refer to [RFC 5280](https://tools.ietf.org/html/rfc5280#section-3.1) section 3.1 +* For information on the syntax of PKCS#10 certificate signing requests, refer to [RFC 2986](https://tools.ietf.org/html/rfc2986) +* Read about [ClusterTrustBundles](/docs/reference/access-authn-authz/certificate-signing-requests/#cluster-trust-bundles)