cert-manager-essendi-xc-issuer

README

essendi-xc-issuer

essendi-xc-issuer is a cert-manager's CertificateRequest controller that uses essendi xc to sign certificates. essendi xc is a service that provides multiple interfaces for requesting certificates from different CAs, like Microsoft ADCS or public CAs like D-Trust, DigiCert, QuoVadis, SwissSign. essendi xc provides both ACME, SCEP and proprietary REST API; This implementation is a HTTP client that interacts with the essendi xc API sending appropriately prepared HTTP requests and interpreting the server's HTTP responses.

Requirements

Current operator version was tested with the following versions of the dependencies:

Component	Tested versions
Kubernetes	1.29 .. 1.34
cert-manager	1.15 .. 1.19
essendi xc	1.26.2 - 2.2.3

and currently supports CertificateRequest CRD API version v1 only.

Configuration and usage

Issuers

The essendi xc service data can be configured in Issuer or ClusterIssuer CRD objects e.g.:

apiVersion: essendixc.angeloxx.ch/v1alpha1
kind: ClusterIssuer
metadata:
  name: test-integration
spec:
  authSecretName: <auth-secret-reference-in-cert-manager-namespace>
  ignoreHostInApiResponse: true|false
  profileName: <issuing-profile-name>
  subscriberName: <subscriber-name>
  url: <essendi-xc-api-url>

Required parameters are:

• authSecretName: name of the secret that contains the credentials used to authenticate with the essendi xc API
• ignoreHostInApiResponse: if set to true, the issuer will ignore the host in the API response. This is useful when using a load balancer or reverse proxy in front of the essendi xc API.
• profileName: name of the profile defined in the essendi xc. This is the profile that will be used to issue the certificate.
• subscriberName: name of the subscriber defined in the essendi xc.
• url: the base URL of the essendi xc API server.

optionally you can define also a set of custom fields that will be passed to the essendi xc API and added as metadata to all the requests. Custom fields must be previously defined in the essendi xc, then the CRD can be used to set it, eg:

apiVersion: essendixc.angeloxx.ch/v1alpha1
kind: ClusterIssuer
metadata:
  name: test-integration
spec:
  authSecretName: <auth-secret-reference-in-cert-manager-namespace>
  ignoreHostInApiResponse: true|false
  profileName: <issuing-profile-name>
  subscriberName: <subscriber-name>
  url: <essendi-xc-api-url>
  customFields:
  - name: Application
    value: '{{ .Csr.CommonName }}'
  - name: DeploymentTarget
    value: Kubernetes
  - name: Environment
    value: Testing Environment
  - name: NotificationMail
    value: cloudnatives@bigcorp.ch

You have also to define the secret containing the credentials used to authenticate with the essendi xc API. The secret must be in the same namespace as the cert-manager controller:

apiVersion: v1
kind: Secret
metadata:
  name: essendixc-cert-manager
  namespace: cert-manager
data:
  client-id: <essendi-xc-client-id>
  client-secret: <client-secret>
  signature-key: <request-signature-key>
  token: eyJhbGciOiJIUzI1NiIsInR5cCIgOi[...]

The secret must be Opaque and contain the following fields:

• client-id: the client ID used to authenticate with the essendi xc API
• client-secret: the client secret used to authenticate with the essendi xc API
• signature-key: the key used to sign the request
• token: the token used to authenticate

Template support for customFields

CustomFields can be used to pass additional information to the Essendi-XC API. The customFields are rendered using Go templates and you can use the following variables:

• Csr.CommonName: the common name of the requested certificate
• Csr.Organization: the organization of the requested certificate
• Csr.OrganizationalUnit: the organizational unit of the requested certificate
• Csr.Country: the country of the requested certificate
• Csr.Locality: the locality of the requested certificate
• Csr.Province: the province of the requested certificate
• Issuer.ProfileName: the profile name of the issuer
• Issuer.SubscriberName: the subscriber name of the issuer

Install

We recommend to use the Helm chart to install the Essendi-XC Issuer. The Helm chart is available in the cert-manager Helm repository.

helm install essendi-xc-issuer oci://registry-1.docker.io/angeloxx/cert-manager-essendi-xc-issuer --version <version>-helm --namespace cert-manager

See also

• When cert-manager meets essendi xc

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.