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.

Prerequisites

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

1. Discover Kubernetes resources

   Kubernetes admin: In this step you collect information from the Kubernetes cluster configuration that you need when configuring the JWT Authenticator.

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

   For OpenShift, replace kubectl with oc.

   1. Check that the Service Account Issuer Discovery service in Kubernetes is publicly available:

      curl $(kubectl get --raw /.well-known/openid-configuration | jq -r '.jwks_uri') | jq

      If the command ran successfully and returned a valid JWKS, run the following command to retrieve and store the jwks-uri value from Kubernetes:

      kubectl get --raw /.well-known/openid-configuration | jq -r '.jwks_uri'

      If the command failed, the Service Account Issuer Discovery service is not publicly available. In this case you need to save the JWKS output to a file:

      kubectl get --raw $(kubectl get --raw /.well-known/openid-configuration | jq -r '.jwks_uri') > jwks.json

   2. Run the following command to retrieve the service account token issuer:

      kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'

2. Define the JWT Authenticator in Conjur

   Conjur admin: In this step you define and load policy for the JWT Authenticator, dev-cluster.

   Conjur uses policy to allowlist the applications that have access to the JWT Authenticator and store the values necessary to create client certificates for mutual TLS.

   1. Save the following sample policy as jwt-authenticator-webservice.yaml:

      - !policy
        id: conjur/authn-jwt/
        body:
          - !webservice
       
          # Uncomment one of following variables depending on the public availability
          # of the Service Account Issuer Discovery service in Kubernetes 
          # If the service is publicly available, uncomment 'jwks-uri'.
          # If the service is not available, uncomment 'public-keys'
          # - !variable jwks-uri
          - !variable public-keys
       
          - !variable issuer
          - !variable token-app-property
          - !variable identity-path
          - !variable audience
          
          # Group of applications that can authenticate using this JWT Authenticator
          - !group apps
         
          - !permit
            role: !group apps
            privilege: [ read, authenticate ]
            resource: !webservice
         
          - !webservice status
         
          # Group of users who can check the status of the JWT Authenticator
          - !group operators
         
          - !permit
            role: !group operators
            privilege: [ read ]
            resource: !webservice status

      This sample policy:

      • Defines the public-keys variable to allow the JWT Authenticator to use the signing key (jwks.json) in the database. It contains the signing keys for token signature validation.

      • Defines variables that allow for application identity (app ID) definition and its proper validation:

        Variable	Description
        issuer	Contains the expected value of the service account token issuer, retrieved above (see Discover Kubernetes resources).
        token-app-property	Contains a claim name that is also defined in the application's identity (app ID) in Conjur. The app ID fetches this value during authentication. In this example. we use the sub claim.
        identity-path	Points to a policy where related Conjur app IDs (hosts) are created. In our example, this is the apps policy.
        audience	Contains a value expected to be present in the aud claim of the service account token, for example https://conjur.host.name/.

      • Creates a JWT Authenticator webservice

      • Creates an apps group that is authorized to use the JWT Authenticator

      • Creates an operators group that is authorized to check the JWT Authenticator status

   2. Load the policy into root:

      $ conjur policy load -b root -f jwt-authenticator-webservice.yaml

3. Populate the policy variables

   Conjur admin: In this step, populate the variables that you defined in the JWT Authenticator policy above. Make sure you have the information that retrieved from Kubernetes at the start of this procedure.

   1. Populate public-keys with the jwks.json that you retrieved from Kubernetes:

      $ conjur variable set -i conjur/authn-jwt/dev-cluster/public-keys -v "{\"type\":\"jwks\", \"value\":$(cat jwks.json)}"

   2. Populate the issuer variable with the service account token issuer that you retrieved from Kubernetes:

      $ conjur variable set -i conjur/authn-jwt/dev-cluster/issuer -v <service account token issuer>

   3. Populate the token-app-property variable with the value, "sub". This creates a 1:1 relationship between the policy and the app ID in Conjur based on the "sub" claim in the service account token:

      $ conjur variable set -i conjur/authn-jwt/dev-cluster/token-app-property -v "sub"

   4. Populate the identity-path variable with the app ID path, (without the host/ prefix):

      $ conjur variable set -i conjur/authn-jwt/dev-cluster/identity-path -v app-path

   5. Populate the audience variable with the value, https://conjur.host.name/:

      $ conjur variable set -i conjur/authn-jwt/dev-cluster/audience -v "https://conjur.host.name/"

4. Enable the JWT Authenticator in Conjur

   Conjur admin: In this step, you enable (allowlist) the JWT Authenticator in Conjur.

   You need to enable the JWT Authenticator on every Conjur node (Leader/Standbys/Follower) that you want to authenticate to.

   For details, see Configure authenticators.

5. Check the JWT Authenticator status

   Conjur admin: Use the Authenticator Status REST API to check that the JWT Authenticator is configured correctly, for example:

   GET https://{Conjur-URL}/authn-jwt/dev-cluster/myorg/status

   For details, see Authenticator Status Webservice.

   If the request status fails, see Troubleshooting.