OCPBUGS#8882: configure an addditionl clientca for the openshiftapi s…

modules/configure-an-additional-clientCA.adoc

@@ -0,0 +1,46 @@
+// Module included in the following assemblies:
+//
+// * security/certificates/api-server.adoc
+
+:_content-type: PROCEDURE
+[id="configure-an-additional-clientCA-for-the-OpenShift-API-server_{context}"]
+
+= Replacing the installer-generated clientCA with a new clientCA for the OpenShift API server
+
+An existing kubeconfig is replaced by adding a new kubeconfig and configuring the existing kubeconfig to be invalid. The existing kubeconfig remains in place, but is not used due to its invalidating configuration. The existing, now invalid, kubeconfig cannot be removed.
+
+Optionally, you can replace the installer-generated kubeconfig. This process is also referred to as configuring the installer-generated kubceconfig to be invalid. 
+You might do this if any of the following conditions exist:
+
+* You do not trust who installed the cluster.
+* The kubeconfig is leaked.
++
+[NOTE]
+====
+A leak can occur if a third party installs the cluster. That third party has the kubeconfig and can potentially access the cluster. To increase security, replace the kubeconfig.
+====
++
+* Other security-related needs exist, such as the periodic rotation of the kubeconfig.
+
+.Procedure
+
+To replace the installer-generated kubeconfig, remove the installer-generated clientCA from the API server:
+
+. Use the following command to import an additional CA certificate in a configmap in the `openshift-config`` namespace. The CA file must be in PEM format.
++
+[source,terminal]
+----
+oc create configmap client-ca-custom -n openshift-config --from-file=ca-bundle.crt=ca.crt
+----
++
+. Use the following command to patch the APIServer instance:
++
+[source, terminal]
+----
+oc patch apiserver cluster --type=merge -p '{"spec": {"clientCA": {"name": "client-ca-custom"}}}'
+----
+
+. Test the new clientCA certificate with a certificate signed from the new clientCA.
+. If the test is successful, you can remove the installer-generated clientCA.
+
+

modules/customize-certificates-api-add-named.adoc

@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="customize-certificates-api-add-named_{context}"]
-= Add an API server named certificate
+= Adding an API server named certificate
 
 The default API server certificate is issued by an internal {product-title}
 cluster CA. You can add one or more alternative certificates that the API
@@ -22,13 +22,6 @@ certificate for the API server FQDN must be the first certificate in the file.
 It can then be followed with any intermediate certificates, and the file should
 end with the root CA certificate.
 
-[WARNING]
-====
-Do not provide a named certificate for the internal load balancer (host
-name `api-int.<cluster_name>.<base_domain>`). Doing so will leave your
-cluster in a degraded state.
-====
-
 .Procedure
 
 . Login to the new API as the `kubeadmin` user.

modules/replace-the-certificate-authority-clientca.adoc

@@ -0,0 +1,102 @@
+// Module included in the following assemblies:
+//
+// * security/certificates/api-server.adoc
+
+:_content-type: PROCEDURE
+[id="replace-the-certificate-authority_{context}"]
+
+= Invalidating the installer-generated kubeconfig before replacing it with a newly generated CA certificate
+
+The installer-generated kubeconfig cannot be removed, but it can be invalidated and replaced with a newly generated CA certificate.
+
+You can replace the installer-generated kubeconfig. You might do this if any of the following conditions exist:
+
+* You do not trust who installed the cluster.
+* The kubeconfig is leaked.
+* Other security-related needs exist, such as the periodic rotation of the kubeconfig.
+
+[IMPORTANT]
+====
+To avoid being locked out of the cluster, have an alternative way to login, such as, using an OAuth-authenticated administrator user or using a client certificate signed by an additional client CA.
+====
+
+.Procedure
+
+. Optional: Generate a new self-signed CA, unless an existing corporate or other CA is to be used.
+.. Export a name for the new self-signed CA.
+[source,terminal]
+----
+
+$ export NAME="custom"
+----
++
+.. Export the subject for the new self-signed CA.
+[source,terminal]
+----
+
+$ export CA_SUBJ="/OU=openshift/CN=admin-kubeconfig-signer-custom"
+----
++
+.. Set the CA validity to 10 years (in days).
+[source,terminal]
+----
+
+$ export VALIDITY=3650
+----
++
+.. Generate the CA private key.
+[source,terminal]
+----
+
+$ openssl genrsa -out ${NAME}-ca.key 4096
+----
++
+.. Create the CA certificate.
+[source,terminal]
+----
+
+$ openssl req -x509 -new -nodes -key ${NAME}-ca.key -sha256 -days $VALIDITY -out ${NAME}-ca.crt -subj "${CA_SUBJ}"
+----
++
+. Generate a new `system:admin` certificate. This X.509 certificate must include the user's name in the Common Name (*CN*) field and the group name in the Organization (*O*) field.
++
+[Note]
+====
+The information in the *CN* and *O* fields are required for authentication.
+====
+
++
+[source,terminal]
+----
+$ export USER=system:admin
+$ export GROUP=system:masters
+$ export USER_SUBJ="/O=${GROUP}/CN=${USER}"
+
+# create the user CSR
+$ openssl req -nodes -newkey rsa:2048 -keyout ${USER}.key -subj "${USER_SUBJ}" -out ${USER}.csr
+
+# sign the user CSR and generate the certificate, the certificate must have the `clientAuth` extension
+$ openssl x509 -extfile <(printf "extendedKeyUsage = clientAuth") -req -in ${USER}.csr \
+       -CA ${NAME}-ca.crt -CAkey ${NAME}-ca.key -CAcreateserial -out 
+${USER}.crt -days $VALIDITY -sha256
+----    
++
+. Use the following commands to add the new certificate as an additional clientCA:
++
+[source,terminal]
+----
+# create the client-ca ConfigMap"
+$ oc create configmap client-ca-custom -n openshift-config --from-file=ca-bundle.crt=${NAME}-ca.crt
+
+# patch the APIServer
+$ oc patch apiserver cluster --type=merge -p '{"spec": {"clientCA": {"name": "client-ca-custom"}}}'
+----
++
+. Use the following commands to import an additional CA certificate in a config map in the `openshift-config`` namespace. The CA file must be in PEM format.
++
+[source,terminal]
+----
+$ oc create --kubeconfig="$NEW_KUBECONFIG" configmap admin-kubeconfig-client-ca -n openshift-config --from-file=ca-bundle.crt=${NAME}-ca.crt \
+       --dry-run -o yaml | oc replace -f -
+----
+

security/certificates/api-server.adoc

@@ -16,4 +16,14 @@ by one that is issued by a CA that clients trust.
 In hosted control plane clusters, you cannot replace self-signed certificates from the API.
 ====
 
-include::modules/customize-certificates-api-add-named.adoc[leveloffset=+1]
+include::modules/customize-certificates-api-add-named.adoc[leveloffset=+1]
+
+include::modules/configure-an-additional-clientCA.adoc[leveloffset=+1]
+
+include::modules/replace-the-certificate-authority-clientca.adoc[leveloffset=+1]
+
+[discrete]
+[role="_additional-resources"]
+== Additional resources
+
+* link:https://access.redhat.com/solutions/6054981[Replacing the certificate authority for the installer system:admin kubeconfig]