JWT-based Kubernetes authentication

To integrate with Kubernetes, you need to set up a JWT Authenticator to enable Kubernetes resources to authenticate to Conjur. This topic describes how to set up a JWT Authenticator.

    • 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.


When integrating with Kubernetes, you can leverage Conjur's JWT Authenticator to authenticate the following, using JWT-based authentication:

  • Conjur Kubernetes Follower

  • Conjur Follower deployed inside Kubernetes

  • Kubernetes workloads


  • 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

    • system:service-account-issuer-discovery ClusterRole permissions (see the Kubernetes documentation)
  • The following command line utilities must be installed: kubectl, curl, and jq.

  • To run the kubectl commands you must have the system:service-account-issuer-discovery ClusterRole.

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

Security considerations (JWT-based authn)

  • Do not use the same key pair in the --service-account-key-file and --service-account-signing-key-file kube-apiserver parameters for different Kubernetes clusters. This makes tokens from different clusters indistinguishable, and may lead to service account impersonation in the presence of an authenticator.

  • Base the authentication implementation on a projected service account token. For more information, see Service Account Token Volume Projection in the Kubernetes documentation.

    Always define an audience variable in the JWT Authenticator and respectively define the audience of the projected service account token. This way, the token that is sent to Conjur cannot be used against any other principals, including Kubernetes, that are configured to accept service account tokens.

    Default service account tokens are not recommended for JWT-based authentication. Default service account tokens are intended for accessing the Kubernetes API server only.

Configure the JWT Authenticator

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

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

  • IMPORTANT!! Before configuring the JWT Authenticator, read Workload identity for Kubernetes (JWT-based authentication) and Important guidelines for configuring JWT authentication. This information affects the way you configure the JWT Authenticator.

  • It must be noted that there are many ways to define JWT authentication, as described in Important guidelines for configuring JWT authentication.

    In this section, we use the following example configuration:

    • We use dev-cluster for the service ID. You can replace this service ID with any unique name for the web service that describes the Kubernetes cluster that it is scoped for, for example, dev-cluster, test1, qa, prod.

      The service ID does not support nesting and cannot contain a forward-slash / character. For example, you can specify qa for a service ID, but qa/test is not supported.

    • We simulate a use-case where Service Account Issuer Discovery is unreachable by Conjur. In this case, the JWT Authenticator must be configured using the public-key variable.

    • We use the token-app-property variable. This is the recommended configuration.

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 JWT-based authentication endpoint when setting up their workloads to authenticate to and retrieve secrets from Conjur. For details, see Set up workloads (JWT-based authentication).