Kubernetes Authenticator Client

This topic describes step-by-step how to enable applications in a Kubernetes environment using a Kubernetes authenticator. It is important to complete each step in the order they are described.

Integrate the Kubernetes Authenticator Client

To enable an application to authenticate with Conjur, the application manifest must be modified to include:

  • The Kubernetes Authenticator Client as either a sidecar or init container

  • A volume mounted to both containers to share the Conjur access token

  • Application environment variables containing connection information for the Conjur appliance

  • Configure the authenticator client container and add the container name to policy

Create service account for your app

If you are using service accounts to authenticate and you have not created one yet, you will need to do so now. The following example assumes that you are using test-app as the name for your service account.

 
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: test-app

Make sure that this service account name matches both policy for authenticator identities in Conjur as well as manifests below wherever < APP_SERVICE_ACCOUNT_NAME > is used.

Add the authenticator image

The Authenticator Client is a public image available on DockerHub or on Red Hat. It can be added to the manifest as either a sidecar or init container.

To use the authenticator as a sidecar, insert its image spec alongside the application container image spec. See the Sidecar application manifest example .

To use an init container, insert the authenticator spec under the initContainers property of the pod spec. See the Init container application manifest example . The authenticator client must be configured with the following variables:

Parameter

Description

CONTAINER_MODE

The container mode defaults to sidecar; when running in sidecar mode, you may omit this parameter.

For the init container, set this value to init.

MY_POD_NAME

This variable identifies the pod where your application runs. Use the Downward API to insert this information into the manifest. In the example manifests, this value is auto-populated fron the app container info.

MY_POD_NAMESPACE

This variable identifies the pod where your application runs. Use the Downward API to insert this information into the manifest. In the example manifests, this value is auto-populated fron the app container info.

MY_POD_IP

This variable identifies the pod where your application runs. Use the Downward API to insert this information into the manifest. In the example manifests, this value is auto-populated from the app container info.

CONJUR_AUTHN_URL

Specify the credential service used to log into Conjur.

Syntax: https://conjur-open-source-k8s-conjur-oss.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/authn-k8s/<AUTHENTICATOR_ID>)

CONJUR_ACCOUNT

The account name designated to the Conjur appliance during initial configuration. You most likely set this environment variable before running the deployment scripts. If so, you can use $CONJUR_ACCOUNT for the value here. In most default installations, this account name is default but your configuration may vary.

CONJUR_AUTHN_LOGIN

Specify the Conjur host that authenticates to Conjur. Set this value to a host id that is defined in policy.

For more information, see Application Identity in OpenShift/Kubernetes.

CONJUR_SSL_CERTIFICATE

The public SSL certificate value required for connecting to the Conjur follower service.

The SSL certificate is generated during Conjur appliance configuration and stored in a .pem file located in the root folder where Conjur was created. The file name is conjur-account.pem, where account is the account name provided for the Conjur appliance.

We recommend using a ConfigMap to store the value.

For example, use:

 
kubectl create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The equivalent OpenShift command is:

 
oc create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The above commands create a ConfigMap that loads the certificate value into it. Now that the certificate value is populated, add the following configuration to the manifest:

 
configMapKeyRef:
    name: conjur-cert        
    key: ssl_certificate 

 

Add a shared volume

The authenticator uses a volume shared with the application container to provide a token to authenticate with Conjur and retrieve secrets. The application manifest should define a memory-only volume and then mount it to /run/conjur on both the application and authenticator containers.

Add Conjur connection information

The application must be configured with environment variables that contain connection information for the Conjur appliance. Add the following variables to the application environment:

Parameter

Description

CONJUR_AUTHN_URL

Specify the credential service used to log into Conjur.

Syntax: https://conjur-open-source-k8s-conjur-oss.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/authn-k8s/<AUTHENTICATOR_ID>)

CONJUR_ACCOUNT

The account name designated to the Conjur appliance during initial configuration. You most likely set this environment variable before running the deployment scripts. If so, you can use $CONJUR_ACCOUNT for the value here. In most default installations, this account name is default but your configuration may vary.

CONJUR_AUTHN_TOKEN_FILE

Identifies the complete path and filename where the authentication container should write the Conjur access token that it obtains on behalf of the application.

CONJUR_SSL_CERTIFICATE

The public SSL certificate value required for connecting to the Conjur follower service. We recommend using a ConfigMap to store the value.

The SSL certificate is generated during Conjur appliance configuration and stored in a .pem file located in the root folder where Conjur was created. The file name is conjur-account.pem, where account is the account name provided for the Conjur appliance.

For example, use:

 
kubectl create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The equivalent OpenShift command is:

 
oc create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The above commands create a ConfigMap that loads the certificate value into it:

 
configMapKeyRef:
    name: conjur-cert        #ConfigMap name
    key: ssl_certificate  #the key into the ConfigMap

Configure the authenticator client container name

 

In pre-v5.2.4 deployments, the container name must be the value authenticator. Starting with v5.2.4, there are no restrictions on the authenticator client container name.

Assign the authenticator client container name in the application manifest, in the -image section for the authenticator client. Here is the relevant section in the manifest:

 
- image: cyberark/conjur-authn-k8s-client
   imagePullPolicy: Always
   name: <AUTHENTICATOR_CLIENT_CONTAINER_NAME>

The container name that you assign here must match the one defined in the host's authn-k8s/authentication-container-name annotation, as described in Define Kubernetes Resources as Conjur identities.

Define application policy

Use a Conjur policy to define the following:

  • An identity for our application linked to the authentication identities we defined in Policy for authentication identities

  • Variables to hold the secrets for our application that can be written to by at least one human user and read by our application identity

Prepare applications to retrieve secrets

Use either the Conjur API or Summon to enable applications to retrieve secrets from Conjur.

Load initial secret values into Conjur

For each secret defined in an application policy, load the initial secret value. You can use the Conjur API, or the CLI for this step.

This is an example using the CLI:

 
$ conjur variable value cluster-1/db/password abc$xyz

Start the application

To start the application, use this Kubernetes command:

 
kubectl create -f your-manifest.yaml

The equivalent OpenShift command is:

 
oc create -f your-manifest.yaml