Skip to main content

Configure the Authenticator as a Sidecar via Helm

If your application is distributed using Helm, we provide a Helm Chart for deploying the Corsha Authenticator alongside your API client as a sidecar. When successfully configured, the Corsha Authenticator allows your application to communicate with a Corsha-Protected API.

Prerequisites​

There are a few prerequisites for deploying the Corsha Authenticator.

  • It is strongly recommended that you configure your Corsha-Protected API before deploying Authenticators. Deployment documentation is available for the Corsha Gatekeeper or as a Kong Gateway Plug-in.

  • Access to the Console is required to deploy a Primer.

  • You are using Helm v3.15.x or newer. This mitigates an issue where helm-lint fails to import dictionaries of child charts properly through import-values. More information can be found here.

Secret Material​

Corsha Helm Charts require sensitive values, so some method of handling secret material is required. Our documentation uses Helm Secrets, but reach out to your Corsha TPOC if you could use help with integrating another secrets management method.

Deploying a Corsha Primer​

The Primer must be used to prime Corsha Authenticators at deployment by storing an Authenticator Secret in Kubernetes secrets.

See the Primer Helm installation guide to run the Primer job and create an Authenticator Secret.

Deploying a Corsha Authenticator as a Sidecar​

An Authenticator can be deployed next to your application once the Primer has stored its Authenticator Secret in Kubernetes. The following guide will deploy the Corsha Authenticator as a sidecar with a basic Nginx web server as an example.

tip

To generate a helm directory structure similar to the one used in this guide, use the helm create NAME [flags] command. More information on helm create can be found here

helm create authenticator-sidecar

The command above will generate a Helm directory structure, similar to what's found below, utilizing a generic Nginx web service.

authenticator-sidecar/
├── .helmignore   # Contains patterns to ignore when packaging Helm charts.
├── Chart.yaml    # Information about your chart
├── values.yaml   # The default values for your templates
├── charts/       # Charts that this chart depends on
└── templates/    # The template files
    └── tests/    # The test files
tip

You can remove the Helm generated hpa.yaml, serviceaccount.yaml, ingress.yaml, and service.yaml unless they are needed for your specific workload.

Workload Configuration​

The Corsha Authenticator Helm Chart requires configuration values for your environment. This configuration is defined in various yaml files touched on more extensively in the following sections.

The Values​

The values.yaml file shown below is configured for our basic Nginx web server and the Corsha Authenticator.

note

Ensure you replace <your-corsha-artifactory-credentials> with the Corsha supplied credentials. We must modify the authenticatorSecretName with the secret's name we generated when deploying the Primer above. We must also configure the Authenticator's connection to the AuthServer. This also should be provided in supplemental documentation.

info

The image in this example is for the Nginx web server and likely will be replaced by your specific container image with which the Authenticator will sidecar. Ensure you replace <your-corsha-artifactory-credentials> with the Corsha supplied credentials. We must modify the authenticatorSecretName with the secret's name we generated when deploying the Primer above. We must also configure the Authenticator's connection to the AuthServer. This also should be provided in supplemental documentation.

imageCredentials:
 username: <your-corsha-artifactory-credentials>
 password: <your-corsha-artifactory-credentials>

image:
 repository: nginx
 pullPolicy: IfNotPresent
 # Overrides the image tag whose default is the chart appVersion.
 tag: "1.23.0"

corsha:
 authenticatorSecretName: <authenticator-secret-name>
 config:
   authenticator:
       authServerTrustedMachine:
         url: "<corsha-auth-server-trusted>:443"
       authServerUntrustedMachine:
         url: "<corsha-auth-server-untrusted>:443"
     proxies:
       api:
         host: "localhost:8888"
         upstreamURL: "https://<your-api-domain>"
The Helm Chart​

Here we configure this workload's Helm chart to add the Authenticator's chart as a dependency.

In the yaml snippet below of Chart.yaml, we demonstrate this by defining dependencies: in the chart and adding in the required Authenticator references. We will now be able to access variables defined in the Corsha Authenticator's Helm Chart through the Kubernetes object corsha.

info

This example instantiates the version and appVersion via an environment variable $VERSION. This will vary in your own implementation. The Authenticator's fields repository and version are supplied with supplementary Corsha documentation. For the sake of this example these variables are also defined by environment variables.

apiVersion: v2
name: authenticator-sidecar
description: A Helm chart for Kubernetes

# A chart can be either an 'application' or a 'library' chart.
#
# Application charts are a collection of templates that can be packaged into versioned archives
# to be deployed.
#
# Library charts provide useful utilities or functions for the chart developer. They're included as
# a dependency of application charts to inject those utilities and functions into the rendering
# pipeline. Library charts do not define any templates and therefore cannot be deployed.
type: application

# This is the chart version. This version number should be incremented each time you make changes
# to the chart and its templates, including the app version.
# Versions are expected to follow Semantic Versioning (https://semver.org/)
version: "$VERSION"

# This is the version number of the application being deployed. This version number should be
# incremented each time you make changes to the application. Versions are not expected to
# follow Semantic Versioning. They should reflect the version the application is using.
# It is recommended to use it with quotes.
appVersion: "$VERSION"

dependencies:
  - name: corsha-authenticator
    repository: https://corsha.jfrog.io/corsha/corsha #where does Helm need to pull the dependency's chart
    version: "$VERSION_RANGE" #the required dependency version; this can also be a regex
    import-values:
      # import the default object from the library chart into the
      # corsha object of this chart
      - child: default.corsha
        parent: corsha

      - child: default.imageCredentials
        parent: imageCredentials
Stateful Set​

The Corsha Authenticator uses a persistent authentication stream. To utilize the Authenticator as a sidecar container we must configure the workload to deploy as a Kubernetes StatefulSet.

note

The helm create command we invoked earlier names this file deployment.yaml. For consistency, we should rename this to statefulSet.yaml and change the kind: to a StatefulSet.

In the yaml snippet of statefulSet.yaml below we show a StatefulSet with the necessary modifications to run a Corsha Authenticator sidecar. The important additions are:

  1. replicas: 1 ensures that there are not multiple Authenticators operating on the same Corsha authentication stream, which would lead to a collision in the DLN
  2. A volumeClaimTemplate is used to persist the Corsha stream to disk
  3. imagePullSecrets the secrets necessary to pull the Authenticator's Docker image from Corsha's Artifactory instance.
  4. Volume mounts included from the Authenticator library's StatefulSet and Certificate Authorities.
apiVersion: apps/v1
kind: StatefulSet
metadata:
  annotations:
    container.seccomp.security.alpha.kubernetes.io/pod: runtime/default
    container.apparmor.security.beta.kubernetes.io/corsha-authenticator: "docker-default"
  name: {{ include "authenticator-sidecar.fullname" . }}
  labels:
    {{- include "authenticator-sidecar.labels" . | nindent 4 }}
spec:
  # It is important to run with only 1 replica for your StatefulSet.
  # If you run with multiple replicas, the authenticators will try to write to the same stream, causing stream collisions.
  replicas: 1
  serviceName: {{ include "authenticator-sidecar.fullname" $ }}
  selector:
    matchLabels:
      {{- include "authenticator-sidecar.selectorLabels" . | nindent 6 }}
  volumeClaimTemplates:
    {{- include "corsha-authenticator/StatefulSet.volumeClaimTemplates" .Values.corsha | nindent 4 }}
  template:
    metadata:
      labels:
        {{- include "authenticator-sidecar.selectorLabels" . | nindent 8 }}
    spec:
      # For security purposes, the Pod's securityContext needs to be set to a non-root user in order
      # for the authenticator sidecar to be able to write to the volume. If your application must
      # run as root, you may set 10001 to 0 for all fields here, but it is not advised.
      securityContext:
        runAsUser: 10001
        runAsGroup: 10001
        fsGroup: 10001
      containers:
        - name: nginx
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - name: nginx
              containerPort: 80
              protocol: TCP
          livenessProbe:
            httpGet:
              path: /
              port: nginx
          readinessProbe:
            httpGet:
              path: /
              port: nginx
        {{- include "corsha-authenticator/StatefulSet.containers" (merge (dict "trustedCAsNamePrefix" .Values.corsha.containerName "trustedCAs" .Values.trustedCAs) .Values.corsha) | nindent 8 }}
      volumes:
        {{- include "corsha-authenticator/StatefulSet.volumes" .Values.corsha | nindent 8 }}
        {{- include "corsha-authenticator/trustedCAs.volumes" .Values.corsha.containerName | nindent 8 }}
      imagePullSecrets:
        {{- include "corsha-authenticator/dockerconfigjson.imagePullSecrets" .Values.corsha.containerName | nindent 8 }}
Secrets​

To deploy the Authenticator library with its necessary secrets we must first create/modify your existing workload's secrets.yaml file with the code found in the yaml snippet below.

apiVersion: v1
kind: Secret
metadata:
  name: {{ include "corsha-authenticator/dockerconfigjson.name" .Values.corsha.containerName }}
  labels: {{- include "authenticator-sidecar.labels" . | nindent 4 }}
type: kubernetes.io/dockerconfigjson
data: {{ include "corsha-authenticator/dockerconfigjson.data" .Values.imageCredentials | nindent 2 }}

---
apiVersion: v1
kind: Secret
metadata:
  name: {{ include "corsha-authenticator/config.name" .Values.corsha.containerName }}
  labels: {{- include "authenticator-sidecar.labels" . | nindent 4 }}
type: generic
stringData: {{- include "corsha-authenticator/config.stringData" .Values.corsha | nindent 2 }}
note

If you require the addition of extra Certificate Authority (CA) roots of trust to connect to the Corsha Gatekeeper or Corsha Auth Server, you will need to include the additional value below in your secrets.yaml file. Your Corsha TPOC will let you know if this is required and send you the required cert.

If your CA is untrusted/self-signed, then you will also have to give the .cert file to Corsha to add to our trusted CAs.

  trustedCAs: |
    -----BEGIN CERTIFICATE-----
    <REDACTED>
    -----END CERTIFICATE-----

Install the Corsha Authenticator​

Now that we've configured our Helm charts, we can now deploy the Corsha Authenticator to our cluster by invoking the commands below.

If this is your first time deploying an Authenticator sidecar you will need to build the Helm dependencies.

helm dependency build

If you are installing a new version of the Authenticator's chart, you will need to run a dependency update prior to installing the chart.

helm dependency update

With our dependencies built, we can now install the Authenticator sidecar via the following command.

note

Ensure you replace $NS with your Kubernetes namespace.

helm install authenticator-sidecar . --namespace $NS --values values.yaml

Verify the Authenticator's Deployment​

Now that we've deployed the Corsha Authenticator we can check its health to ensure the deployment was successful.

To do so, we can run the following command.

note

Ensure you replace $NS with your Kubernetes namespace.

kubectl -n $NS get pods authenticator-sidecar-0

You should see output similar to what's below, confirming that our sidecar started alongside our other container and its status is running.

NAME                      READY   STATUS    RESTARTS   AGE
authenticator-sidecar-0   2/2     Running   0          5m23s

If you do not see this status after configuring the Authenticator as a sidecar, please reach out to your Corsha TPOC for additional help.

You are now ready to configure the Pod's primary container to proxy with the sidecar.