Import a Custom Certificate Authority to Sign New Certificates

This procedure allows you to import a custom intermediate Certificate Authority (CA) to sign new certificates for ARTESCA services.

When importing a new custom CA, all existing certificates will be automatically re-issued. Certificates that were previously visible in the ARTESCA UI, issued by the ARTESCA Root CA, will no longer be visible after the import, as they are replaced by new certificates issued by the new custom CA.

To import a custom CA, follow this workflow:

• prepare the Certificate Authority

• create a ClusterIssuer

• update Ingress Resources

Prepare the Certificate Authority

To be able to automatically sign and renew certificates securing ARTESCA services, you need to import an intermediate CA trusted by your clients (browsers and other tools).

1. Contact your security team to obtain a private key and certificate signed by a root CA you control, with the following x509 extensions:

   • basicConstraints = critical, CA:true, pathlen:0

     (pathlen:0 prevents this intermediate CA from signing other CAs)

   • keyUsage = critical, digitalSignature, cRLSign, keyCertSign

2. Make sure to have a sufficiently distant expiration date, to avoid having to renew it too often (which would defeat the purpose of giving ARTESCA its own intermediate CA).

   Important

   Make sure that this intermediate certificate contains the full chain up to the root CA trusted by clients. This ensures that all server certificates also contain it and can be recognized properly.

3. (Optional) Add these recommended additional extensions to the intermediate CA certificate for enhanced protection.

   • Define some nameConstraints to exclude the 0.0.0.0/0.0.0.0 and 0:0:0:0:0:0:0:0/0:0:0:0:0:0:0:0 IP addresses, and allow specifically some domains (e.g. permitted;DNS.0=.my-company.com).

   • Add a Certificate Revocation List (CRL) distribution point, and make sure that you can quickly revoke this intermediate CA in case the ARTESCA platform becomes compromised.

   • Alternatively or in addition, add an Online Certificate Status Protocol (OCSP) responder and reference it in the intermediate CA certificate.

4. Upon generation of the intermediate CA certificate, collect the files locally. We will assume they are named ca.crt and ca.key in the following steps.

Create a ClusterIssuer

1. Store the certificate and key in a Secret (named my-ca in this example).

   [artesca-os@bootstrap ~]$
   

   sudo kubectl --kubeconfig /etc/kubernetes/admin.conf \
       create secret tls my-ca --namespace metalk8s-certs \
       --cert ca.crt --key ca.key
   

2. Create a ClusterIssuer referencing this Secret.

   [artesca-os@bootstrap ~]$
   

   sudo kubectl --kubeconfig /etc/kubernetes/admin.conf apply -f - <<EOF
   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: my-ca-issuer
     namespace: metalk8s-certs
   spec:
     ca:
       secretName: my-ca
   EOF
   

   Tip

   Optionally, you can specify CRL distribution points when creating the ClusterIssuer (make sure to specify your own URLs instead of the http://certs.my-company.com/my-ca.crl example shown):

   [artesca-os@bootstrap ~]$
   

   sudo kubectl --kubeconfig /etc/kubernetes/admin.conf apply -f - <<EOF
   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: my-ca-issuer
     namespace: metalk8s-certs
   spec:
     ca:
       secretName: my-ca
       crlDistributionPoints:
       - "http://certs.my-company.com/my-ca.crl"
   EOF
   

Update Ingress Resources

Update all Ingress resources to ensure that they use new certificates signed by your intermediate CA.

• [artesca-os@bootstrap ~]$
  

  sudo kubectl --kubeconfig /etc/kubernetes/admin.conf \
      annotate --namespace artesca-auth ingress/keycloak-public \
      cert-manager.io/cluster-issuer=my-ca-issuer \
      --overwrite
  

• [artesca-os@bootstrap ~]$
  

  sudo kubectl --kubeconfig /etc/kubernetes/admin.conf \
      patch --namespace zenko zenko/artesca-data \
      --type merge --patch '
      spec:
        ingress:
          annotations:
            cert-manager.io/cluster-issuer: my-ca-issuer
            cert-manager.io/renew-before: 1h
      '
  

If S3 endpoints are already secured using the built-in CA, there is no additional step to follow.