Kubernetes Authenticator Client

This topic describes step-by-step how to set up the Kubernetes Authenticator Client so that an application in Kubernetes can retrieve secrets from Conjur.

How it works

This section describes how the application container fetches secrets from Conjur.

1. Kubernetes projects the service account token (JWT) to the FileSystem of the Kubernetes Authenticator Client. The service account token contains details about the Kubernetes service account and the namespace.

2. The Kubernetes Authenticator Client starts and authenticates to Conjur using the JWT Authenticator.

3. Conjur returns a Conjur access token.

4. The Conjur access token is shared between the Kubernetes Authenticator Client container and the application container using a shared memory volume between the container.

5. The application container can now use the Conjur access token to fetch secrets from Conjur.

Set up the application to retrieve secrets

This section describes how to set up the Kubernetes Authenticator Client so that your application can retrieve secrets from Conjur.

1. Before you begin

   • Make sure that a JWT Authenticator endpoint has been configured and allowlisted. In the examples below, we use the dev-cluster endpoint. For more information, contact your Conjur admin, or see JWT-based Kubernetes authentication.

   • This procedure assumes the following:

     • You have a configured Kubernetes namespace with a service account for your application.

     • The namespace must be prepared with the relevant resources, as described in Prepare the application namespace.

     • You are familiar with Service Account Token Volume Projection in Kubernetes

     • You are familiar with loading manifests into your namespace.

       In the examples in this section, we use test-app-namespace for the namespace, and test-app-sa for the service account. We also use dev-cluster for the JWT Authenticator endpoint (service ID).

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

2. Define the application as a Conjur host in policy

   Conjur admin: To enable the application to retrieve Conjur secrets, it first needs to authenticate to Conjur.

   The examples in this section follow on from the example JWT Authenticator configuration described in JWT-based Kubernetes authentication.

   1. In this step, you give the application, test-app, an identity in Conjur.

      1. Save the following policy as test-app.yaml and adjust the values accordingly:

         • Name the host using the following format: system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>

         • Include annotations with details about application's namespace and serviceaccount. The JWT Authenticator checks these details when the application authenticates to Conjur

         For example:

         - !policy
           id: app-path
           body:
           - !host
             id: system:serviceaccount:cyberark-conjur:test-app-sa
             annotations:
               authn-jwt/dev-cluster/kubernetes.io/namespace: test-app-namespace
               authn-jwt/dev-cluster/kubernetes.io/serviceaccount/name: test-app-sa

         Load the policy file to root:

         $ conjur policy load -f test-app.yaml -b root

      2. Grant the host permissions to the JWT Authenticator. Save the following policy as grant-app-access.yaml

         - !grant
           roles:
           - !group conjur/authn-jwt/dev-cluster/apps
           members:
           - !host app-path/system:serviceaccount:test-app-namespace:test-app-sa

         Load the policy file to root.

         $ conjur policy load -f grant-app-access.yaml -b root

3. Grant access to secrets

   Conjur admin: In this step, you grant the Kubernetes Authenticator Client access to secrets These secrets might be synced from the Vault/Privilege Cloud, or defined in Conjur, or both.

   Secrets in Conjur

   Define variables (secrets) that the Kubernetes Authenticator Client needs access to:

   Define variables (secrets) that the Secrets Provider needs access to:

   1. Save the following policy as app-secrets.yaml.

      This policy defines Conjur variables and a group that has permissions on the variables.

      - !policy id: secrets body: - !group consumers - &variables - !variable username - !variable password - !permit role: !group consumers privilege: [ read, execute ] resource: *variables

      Load the policy file into root:

      $ conjur policy load -f app-secrets.yaml -b root

   2. Grant permissions on the variables. Save the following policy as grant-secrets-access.yaml. In this example, all members of the consumers group are granted permissions on the variables:

      - !grant role: !group secrets/consumers member: !host app-path/system:serviceaccount:test-app-namespace:test-app-sa - !grant role: !group secrets/consumers member: !host app-path/system:serviceaccount:test-app-namespace:secrets-provider-service-account

      Load the policy file into root:

      $ conjur policy load -f grant-secrets-access.yaml -b root

   3. Populate the variables with secrets, for example myUser and MyP@ssw0rd!:

      $ conjur variable set -i secrets/username -v myUser

      $ conjur variable set -i secrets/password -v MyP@ssw0rd!

4. Set up the application deployment manifest

   Application owner: You can run the Kubernetes Authenticator Client as an init container or as a sidecar.

   Click to read more about the init container and sidecar options

    

   Method	Description
   init	An init container does not run continuously and therefore uses fewer resources. Run the Kubernetes Authenticator Client as an init container for applications that do not need to fetch rotated secrets; that is, the applications are not using the Conjur rotator services. The init container provides the application with one initial access token and then it exits. The application uses the token to get its required secrets and does not require any further Conjur access. The provided access token expires after 8 minutes.
   sidecar	A sidecar container runs continuously along with your application. Run the Kubernetes Authenticator Client as a sidecar for applications that need continuous access to Conjur to fetch updated secrets when they are rotated. The sidecar is a continuous process, generating a refreshed token value every few minutes (6 minutes, by default). An access token has a time-to-live of 8 minutes.

   1. Set up application manifest:

      • init Container
      • Sidecar

      To deploy your application using the Kubernetes Authenticator Client as an init container, copy the following manifest and load it to the application namespace, test-app-namespace:

      • The manifest instructs Kubernetes to project a service account token (JWT) to the application file system. Under volumes provide the following projection information for jwt-token:

        Field	Description
        path	A token path that can be used to identify the token, for example jwt
        expirationSeconds	(Optional) The expiration of the token in seconds, for example 6000
        audience	The token's audience. This is required only if the JWT Authenticator endpoint was defined with an audience variable, and the value must match the value that the variable was populated with, for example https://conjur.host.name/. For details, see Populate the policy variables. Otherwise audience is optional.

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        labels:
          app: test-app
        name: test-app
      spec:
        selector:
          matchLabels:
            app: test-app
        replicas: 1
        template:
          metadata:
            labels:
              app: test-app
          spec:
            serviceAccountName: test-app-sa
            containers:
              - name: test-app
                image: <APPLICATION-IMAGE>
                ports:
                  - containerPort: 8080
                envFrom:
                - configMapRef:
                    name: conjur-connect
                volumeMounts:
                - mountPath: /run/conjur
                  name: conjur-access-token
                  readOnly: true
            initContainers:
            - image: cyberark/conjur-authn-k8s-client
              imagePullPolicy: Always
              name: authenticator
              env:
                - name: JWT_TOKEN_PATH
                  value: /var/run/secrets/tokens/jwt
                - name: CONTAINER_MODE
                  value: init
              envFrom:
                - configMapRef:
                    name: conjur-connect
              volumeMounts:
                - mountPath: /run/conjur
                  name: conjur-access-token
                - mountPath: /var/run/secrets/tokens
                  name: jwt-token
            volumes:
              - name: conjur-access-token
                emptyDir:
                  medium: Memory
              - name: jwt-token
                projected:
                  sources:
                    - serviceAccountToken:
                        path: jwt
                        expirationSeconds: 6000
                        audience: https://conjur.host.name/

      To deploy your application using the Kubernetes Authenticator Client as a sidecar, copy the following manifest, fill in the required information, and load it to the application namespace, test-app-namespace:

      • The manifest instructs Kubernetes to project a service account token (JWT) to the application file system. Under volumes provide the following projection information for jwt-token:

        Field	Description
        path	A token path that can be used to identify the token, for example jwt
        expirationSeconds	(Optional) The expiration of the token in seconds, for example 6000
        audience	The token's audience. This is required only if the JWT Authenticator endpoint was defined with an audience variable, and the value must match the value that the variable was populated with, for example https://conjur.host.name/. For details, see Populate the policy variables. Otherwise audience is optional.

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        labels:
          app: test-app
        name: test-app
      spec:
        selector:
          matchLabels:
            app: test-app
        replicas: 1
        template:
          metadata:
            labels:
              app: test-app
          spec:
            serviceAccountName: test-app-sa
            containers:
              - name: test-app
                image: <APPLICATION-IMAGE>
                ports:
                  - containerPort: 8080
                envFrom:
                - configMapRef:
                    name: conjur-connect
                volumeMounts:
                - mountPath: /run/conjur
                  name: conjur-access-token
                  readOnly: true
                   
              - image: cyberark/conjur-authn-k8s-client
                imagePullPolicy: Always
                name: authenticator
                env:
                  - name: JWT_TOKEN_PATH
                    value: /var/run/secrets/tokens/jwt
                envFrom:
                  - configMapRef:
                      name: conjur-connect
                volumeMounts:
                  - mountPath: /run/conjur
                    name: conjur-access-token
                  - mountPath: /var/run/secrets/tokens
                    name: jwt-token
            volumes:
              - name: conjur-access-token
                emptyDir:
                  medium: Memory
              - name: jwt-token
                projected:
                  sources:
                    - serviceAccountToken:
                        path: jwt
                        expirationSeconds: 6000
                        audience: https://conjur.host.name/

   2. Apply the deployment manifest:

      kubectl apply -f k8s-authn-client-deployment.yaml -n test-app-namespace

Prepare applications to retrieve secrets

Use the one of the following methods to enable applications to retrieve secrets from Conjur.

DB_USERNAME: !var my-app/db/username
DB_PASSWORD: !var my-app/db/password
REGION: us-east-1
SSL_CERT: !var:file ssl/certs/private

Security consideration

Users who can create a Pod that can authenticate to Conjur can also access Conjur access tokens. As a result, these users can access the Pod's Conjur secrets.