Certificate-based Kubernetes authentication

This topic describes how to set up a Kubernetes Authenticator for certificate-based authentication of Kubernetes environments.

The Kubernetes Authenticator enables the following components to authenticate to Conjur using certificate-based authentication:

  • Conjur Kubernetes Follower

  • Conjur Follower deployed inside Kubernetes

  • Kubernetes workloads

    • Unless specifically noted otherwise, all references to Kubernetes apply to Self-hosted Kubernetes as well as Red Hat OpenShift and other supported Kubernetes-based implementations.
    • All references to Kubernetes namespaces intentionally include the OpenShift concept of project.


  • Conjur cluster: This configuration assumes you have access to an up-and-running Conjur cluster. For details, see Setup.

  • This configuration assumes you are working from a Linux Shell or macOS.

  • To perform this task, you need:

    • Conjur admin permissions

    • Kubernetes cluster admin permissions OR the help of an available Kubernetes cluster admin

  • Make sure you have the Conjur CLI (v7.x+) installed and that you are logged in. For details, see Set up the Conjur CLI.

  • Make sure you have access to the Helm charts or raw manifests for preparing Kubernetes clusters and namespaces. These are available from the following locations:

Configure and enable a Kubernetes Authenticator

This section describes how to configure and enable a Kubernetes Authenticator.

  • This procedure involves tasks for both the Conjur admin and the Kubernetes cluster admin.

  • In the examples in this procedure, we use dev-cluster for the service ID. You can replace this service ID with any unique name for the webservice that describes the Kubernetes cluster that it's scoped for, for example, dev-cluster, test1, qa, prod.

Authentication steps

The following describes the security-related flow:


Establish mutual TLS

Before retrieving secrets, the authentication client establishes mutual TLS with the Kubernetes Authenticator in Conjur to ensure that both parties can verify their intended recipients. The mutual TLS protocol requires the client to have a client certificate that has been signed by a trusted CA (in this case, Conjur itself).

To retrieve this certificate, the client sends a Certificate Signing Request (CSR) to Conjur. The CSR metadata includes the host identity that the pod would like to use to authenticate, as well as information about the pod making the request.

Conjur checks the pod information against Kubernetes to verify that the pod is legitimate, and verifies that the pod should be allowed to authenticate as the host identity from the CSR.

If this verification succeeds, the client certificate is injected into the application Pod using the Kubernetes API. By using the API to perform this injection out-of-band (instead of returning it in the request response), the Kubernetes Authenticator ensures that the client certificate is delivered to the pod that matches the metadata in the CSR.

The certificate expires and is renewed automatically on a regular basis to reduce the chances of a malicious third party being able to use a compromised certificate to assume the application Pod's identity.


Get an access token

After receiving a client certificate, the authentication client uses it to establish a mutual TLS connection with Conjur and requests a short-lived access token. The access token is written to shared pod memory and can be used with one of the secret retrieval methods to retrieve secrets from Conjur. The token is short-lived to reduce the possibility that it can be used by a malicious third party if it is somehow compromised.


Retrieve secrets

The workflow can now use the access token to retrieve secrets with one of the secret retrieval methods.

Troubleshoot the certificate-based Kubernetes Authenticator

This section lists issues that may arise and recommended solutions.

Unable to authenticate using Azure Authenticator:

  1. Check the authenticator status using the Authenticator Status API. For details, see Authenticator Status Webservice.
  2. View the authenticator logs. For details, see Filter authentication errors.

If you have not yet deployed a Follower, see Set up Follower.

If you have already deployed a Follower, the integration setup is complete. App owners can now use this cert-based authentication endpoint when setting up their workloads to authenticate to and retrieve secrets from Conjur. For details, see Set up workloads (cert-based authentication).