Certification Authorities

This section details how to configure the Certification Authorities known by EverTrust Horizon.

Prerequisites

Certification Authorities will be needed beforehand, in one of these formats:

  • Certificate file (PEM or DER).

  • Certificate string (PEM).

You might also need the URL of the CRL issued by the CA, and/or the URL of the OCSP Responder for that CA.

How to configure a Certification Authority

1. Log in to Horizon Administration Interface.

2. Access Certification Authorities from the drawer or card: Certification Authorities.

3. Click on Add Certificate Authorities.

Certificate Tab:

4. Either

  • Fill in the certificate section with certificate string (PEM) OR

  • Import the certificate file (PEM or DER).

Then click on the next button.

Details Tab:

5. Check the information from your CA certificate. Then click on the next button.

Configuration Tab:

6. Fill in the information you want to add.

  • Name* (string input):
    Enter a meaningful certificate authority name. It must be unique for each certificate authority.

  • OCSP responder URL (string):
    URL to request an OCSP responder.

  • CRL URL (string):
    URL to download the CA CRL.

  • Refresh Period (finite duration):
    CRL or OCSP Refresh Period. Must be a valid finite duration.

  • Timeout (finite duration):
    Connection timeout when reaching CRL or OCSP. Must be a valid finite duration.

  • Proxy (string select):
    The HTTP/HTTPS proxy to use to reach the CRL or the OCSP Responder, if any.

  • Is exposed on Registration Authority (boolean):
    Display the CA in the Trust chains view on the RA side. The default value is set to false.

  • Is trusted for server authentication (boolean):
    Tells whether the CA should be trusted for server authentication, aka SSL/TLS server trust. The default value is set to false.

  • Is trusted for client authentication (boolean):
    Tells whether the CA should be trusted for client authentication. The default value is set to false.

When Is trusted for client authentication is enabled and the expert mode is active, three template-string fields are displayed to control how Horizon derives the authenticated identity from a client certificate. They use the standard template string syntax, with access to the raw certificate dictionary entries.

  • Identifier mapping (template string):
    Template used to compute the unique identifier of the authenticated principal. Default: {{certificate.dn}}.

  • Display name mapping (template string):
    Template used to compute the display name of the authenticated principal. Default: {{certificate.subject.cn.1}}.

  • Email mapping (template string):
    Template used to compute the email of the authenticated principal. Default: {{certificate.san.rfc822name.1}}.

  • Outdated Revocation Status Policy (option):
    Select "Revoked" if you want all certificates to be handled as revoked if the CRL/OCSP are unavailable. Select "Last available status" if you want Horizon to use the last available revocation status for the certificates.

7. Click on the import button.

You can edit Edit Certification Authorities, download Download Certification Authorities or delete Delete Certification Authorities the Certification Authorities.

You will not be able to delete a Certification Authority if it is referenced in any other configuration element. Pay also attention that the CA might be used (e.g. for TLS trust chain building), even if it is not explicitly referenced in configuration items.

Exporting client authentication CAs

Horizon requires a reverse proxy for client certificate authentication (mTLS). To let the reverse proxy advertise the list of CAs that Horizon trusts for client authentication, Horizon can export the bundle of all CAs flagged as Is trusted for client authentication to one or more destinations.

Exporters are declared in the HOCON configuration. Each exporter writes the bundle of all client authentication CAs in a configurable format, and Horizon refreshes the destination whenever a CA is added, updated or removed.

Supported destinations:

  • file: a file on the local filesystem, suitable for nginx running on a VM (see ssl_client_certificate).

  • k8s-configmap: a Kubernetes ConfigMap, suitable for the OpenShift Router which expects a ca-bundle.pem key.

  • k8s-secret: a Kubernetes Secret, suitable for ingress-nginx which expects a ca.crt key referenced through the nginx.ingress.kubernetes.io/auth-tls-secret annotation.

The exporter is configured under horizon.ca.exporters:

horizon {
  ca.exporters = [
    {
      enabled = true

      type = "file"          # file | k8s-configmap | k8s-secret
      format = "pem-blocks"  # concatenated PEM blocks

      file {
        path = "/etc/nginx/horizon-client-cas.pem"
      }

      k8s-configmap {
        name = "horizon-client-cas"
        key  = "ca-bundle.pem"
      }

      k8s-secret {
        name = "horizon-client-cas"
        key  = "ca.crt"
      }
    }
  ]
}
Kubernetes destinations require the cluster API access configuration described under horizon.kubernetes (namespace, API host, service account token, and CA file). Full configuration reference
If the targeted ConfigMap or Secret does not exist, Horizon creates it the first time the bundle is exported. Make sure the service account used by Horizon has the corresponding create, update and get permissions on the target object.