Install the CA Connector Client in a Linux Container

When the CA Connector The Keyfactor CA Connector is installed in the customer environment to provide a connection between a CA and Keyfactor Command when a direct connection is not possible. It is supported on both Windows and Linux and has versions for Microsoft (Windows only) or EJBCA CAs. Client runs in a Linux container, it is typically installed in a containerization solution that sits on top of a Linux server or set of servers. There are a wide variety of containerization solutions for multiple operating systems. This document covers deploying the container to either Docker or Kubernetes on Linux.

The artifactory for the CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. Connector Client images for Docker and Kubernetes without Helm can be found in the following JFrog repository:

repo.keyfactor.com/images/command/ca-connector

The artifactory for the CA Connector Client Helm charts can be found in the following JFrog repository:

repo.keyfactor.com/images/command/ca-connector

Note: For artifactory credentials or more information, check with your Keyfactor Customer Success Manager or visit the Keyfactor Support Portal.

Docker

If you plan to use Docker, you may find it helpful to first run the CA Connector Client in the foreground so that it will output log messages to assist in troubleshooting.

Tip: If your Docker implementation hasn’t been configured to inject your DNS

The Domain Name System is a service that translates names into IP addresses. server(s) into running containers, you may wish to do this so that the CA Connector Client will be able to do name resolution. To do this, on the Linux server(s) where you are running Docker, create or update the /etc/docker/daemon.json file, and add an entry similar to the following:

{"dns": ["DNS_IP_Address_1", "DNS_IP_Address_2"] }

Tip: For information on installing remote PAM

PAM (Privileged Access Management): Controls privileged access by vaulting credentials, enforcing least-privilege/just-in-time access, rotating secrets, and auditing sessions. Across Keyfactor products, PAM protects diverse sensitive operations and secrets—for example certificate stores and CA credentials—via built-in or third-party providers; external integrations are delivered as custom PAM extensions (several published on Keyfactor’s public GitHub). extensions, see Remote PAM Extensions on the CA Connector Client (Container).

To install the CA Connector Client in a Linux container and start the container using compose:

Create a directory from which you will run the Docker container (e.g., /opt/kyf_ca-connector). For example:

sudo mkdir /opt/kyf_ca-connector
From your Docker host, retrieve the CA Connector Client image from the artifactory with commands similar to the following (placing your token or API An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. key in the my_password file), with the desired version:

sudo nano my_password.txt

cat my_password.txt | docker login repo.keyfactor.com --username username --password-stdin

docker pull repo.keyfactor.com/images/command/ca-connector:25.5

Note: For artifactory credentials or more information, check with your Keyfactor Customer Success Manager or visit the Keyfactor Support Portal(opens page in a new tab).

Important: Remove the my_password.txt file when complete. For example:
sudo rm my_password.txt

Create a Docker compose file (compose.yaml) in the directory for your Docker container similar to the following, using the inputs as per Table 1156: CA Connector Parameters for Docker, referencing the artifactory image you pulled, selecting the appropriate authentication mechanism for your environment, and any additional volume mounts. The fields highlighted in red below indicate fields that need to be edited or that you may wish to edit.

Important: When editing the file, be sure to preserve the indenting exactly as shown. YAML requires a very specific file layout to function. If the indenting (multiples of two spaces) or layout is incorrect, you will receive an error when trying to install.

services:
  caconnector:
    image: repo.keyfactor.com/images/command/ca-connector:25.5
    container_name: ca-connector-1
    environment:
      - LOG_LEVEL=Info
      - ServerURL=https://command.keyexample.com/KeyfactorCAConnectors
      - OAuthServer__Address=https://appsrvr187.keyexample.com:5443/realms/Keyfactor/protocol/openid-connect/token # Token URL
      - OAuthServer__ClientId=Client-ID
      - OAuthServer__ClientSecret='Client-Secret' # The client secret needs quotes under some circumstances if it contains special characters
      #- OAuthServer__Scope=OPTIONAL-SCOPE(s)
      #- OAuthServer__Audience=OPTIONAL-AUDIENCE
       - Name=appsrvr185.keyexample.com # The name for the connector in Keyfactor Command

    volumes:
      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-bundle.crt # The path on your host (the first one) will vary depending on the OS

Important: The secret for the RabbitMQ client is stored in clear text in this compose file. Access to this file should be strictly controlled.

Set the permissions on the compose.yaml file such that the file is owned by root and readable only by root (this assumes your Docker daemon is running as root, which is typical). For example:

sudo chown root:root compose.yaml

sudo chmod 400 compose.yaml

Tip: If you need to make edits to the compose file, you will need to make the file writable again. For example:
sudo chmod 600 compose.yaml
Execute the following command to install and run the container in the foreground:

sudo docker compose up

Press CTRL-C to stop it if it’s running in the foreground. You can instead run it in the background by adding the -d flag like so, but it can sometimes be helpful to run it in the foreground initially so that you can easily review the log output live:

sudo docker compose up -d
Tip: To stop and start the container again after installation is complete, use the following commands:
sudo docker compose stop
sudo docker compose start
Or:
sudo docker compose restart
If you need to delete the container and try the install again, use this command:
sudo docker compose down
To review logs generated from the container, identify the container ID or name with this command:
sudo docker container ls
Or for a more succinct output:
Copy
```
sudo echo "CONTAINER ID  NAMES       STATUS" && docker container ls --format "{{.ID}}  {{.Names}}  {{.Status}}"
```
For example, in the following output (this is the succinct version) you could select either the container ID ceb2169efdbd or the name ca-connector-1:
```
CONTAINER ID  NAMES       STATUSceb2169efdbdca-connector-1  Up 45 minutes
daa0b06986c3  ejbca900  Up 4 weeks
9136a6765450  ejbca900-database  Up 4 weeks
7cf64de25b4d  ejbca920  Up 4 weeks
4451b1ef5089  ejbca920-database  Up 4 weeks
94a373b2f49a  rabbit-mq  Up 4 weeks
```
Then use the following command to output the current log (with the optional --follow to make output continuous):
sudo docker container logs [--follow] [container ID or name]

Table 1156: CA Connector Parameters for Docker

Parameter	Description
CAConfigCacheExpirationMinutes	The number of minutes that the CA configuration will be cached before being cleared. The default is 10.
LOG_LEVEL	The container logging level output. Supported values are: OFF No logging FATAL Log severe errors that cause early termination ERROR Log severe errors and other runtime errors or unexpected conditions that may not cause early termination WARN Log errors and use of deprecated APIs, poor use of APIs, almost errors, and other runtime situations that are undesirable or unexpected but not necessarily wrong INFO Log all of the above plus runtime events (startup/shutdown) DEBUG Log all of the above plus detailed information on the flow through the system TRACE Maximum log information—this option can generate VERY large log files The default value is Info.
Name	Required. The name the CA Connector Client uses to register itself with Keyfactor Command. This name must match the name used when creating a CA connector record in Keyfactor Command (see Preparing). If you choose to uninstall and reinstall the connector (e.g., using compose down), it is important to use the same name for subsequent implementations so that Keyfactor Command will recognize the connector when it is started again.
OAuthServer__Address	Required in some cases. The URL of the token endpoint for the identity provider. For example: Copy `https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token` For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation).
OAuthServer__Audience	The audience that should be included in token requests to the identity provider. The OAuth mechanism in use in your Keyfactor Command environment may or may not require this.
OAuthServer__ClientId	Required. The ID for the client application created in the OAuth identity provider to allow the CA connector to make requests to Keyfactor Command (see Identify the CA Connector Client Access Token). For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.
OAuthServer__ClientSecret	Required. The secret for the client application created in the OAuth identity provider to allow the CA connector to make requests to Keyfactor Command. For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.
OAuthServer__Scope	One or more scopes that should be included in token requests delivered to the OAuth identity provider when making a token request. Multiple scopes should be separated by spaces. For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative. The OAuth mechanism in use in your Keyfactor Command environment may or may not require this.
ServerURL	Required. The URL to the CA connector application on the Keyfactor Command server. SSL is required to connect to the Keyfactor Command server. For example: Copy `kyf101.keyfactorpki.com/KeyfactorCAConnectors`
SignalR__SkipNegotiation	When set to true, tells the SignalR client to skip the negotiation step during the connection. The default is false.
SignalR__TransportTypes	Specifies the transport types that SignalR should use to establish a connection. The default is: "WebSockets, LongPolling"

Kubernetes without Helm

To deploy the container as a StatefulSet in Kubernetes without using Helm, manually define a Kubernetes manifest (YAML file) specifying the StatefulSet resource. This includes configuring the container image, environment variables, volume mounts, and other settings needed for deployment. The container will run within the StatefulSet, ensuring persistence and unique network identities.

Tip: For information on installing remote PAM extensions, see Remote PAM Extensions on the CA Connector Client (Container).

To install the CA Connector Client using Kubernetes without Helm:

Create a directory from which you will run the container (e.g., /opt/kyf_ca-connector).
If desired, create a namespace for CA Connector Client resources and containers in Kubernetes. For example:

sudo kubectl create namespace keyfactor-connector
Create a secret in Kubernetes to allow the CA Connector Client to authenticate to Keyfactor Command (see Identify the CA Connector Client Access Token).

For example:

sudo kubectl create secret generic client-credentials --namespace keyfactor-connector --from-literal=client-id=MyClientID --from-literal=client-secret=MySuperSecretClientSecret
Create a secret in Kubernetes for the credentials you will use to authenticate to the Keyfactor artifactory. For example:

sudo kubectl create secret docker-registry keyregcred --namespace keyfactor-connector --docker-server=repo.keyfactor.com --docker-username=MyUsername --docker-password=MySuperSecretToken --docker-email=my.email@my-domain.com

Note: For artifactory credentials or more information, check with your Keyfactor Customer Success Manager or visit the Keyfactor Support Portal(opens page in a new tab).
Create a ConfigMap in Kubernetes containing CA root and issuing certificates for all CAs in the environment that will have any relationship with the CA Connector Client (see Configure a Certificate Root Trust for the Keyfactor CA Connector).

Once the host’s trust store is updated with all the certificates you will need, create the ConfigMap. For example:

sudo kubectl create configmap ca-roots --namespace keyfactor-connector --from-file=/etc/ssl/certs/ca-certificates.crt

Note: The standard path to the trusted root store will vary depending on your Linux implementation.

Create a Kubernetes deployment file (e.g., caconnector.yaml) in the directory for your Kubernetes container similar to the following, using the inputs as per Table 1157: CA Connector Parameters for Kubernetes without Helm, referencing the artifactory for the image you wish to install, selecting the appropriate authentication mechanism for your environment, and any additional volume mounts. The fields highlighted in red below indicate fields that need to be edited or that you may wish to edit.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  # Give the pod a unique name if you plan to deploy more than one CA connector to the same Kubernetes server or cluster
  name: keyfactor-ca-connector-1
  labels:
    app.kubernetes.io/name: keyfactor-ca-connector
    app.kubernetes.io/instance: connector-1
    app.kubernetes.io/version: "25.5"
spec:
  # The CA connector should not have replicas; instead use many different deployments with different names if horizontal scaling is needed
  serviceName: keyfactor-ca-connector-service
  replicas: 1

  selector:
    matchLabels:
      app.kubernetes.io/name: keyfactor-ca-connector
      app.kubernetes.io/instance: connector-1

  template:
    metadata:
      labels:
        app.kubernetes.io/name: keyfactor-ca-connector
        app.kubernetes.io/instance: connector-1

      containers:
        - name: ca-connector
        # Specify the desired image version
        image: "repo.keyfactor.com/images/command/ca-connector:25.5"
        imagePullPolicy: IfNotPresent

        # Environment Variables
        env:
          # The below block is the URL of the CA connectors API on the Keyfactor Command server
          - name: ServerURL
            value: https://command.keyexample.com/KeyfactorCAConnectors
          # The below block is the name the CA connector will use when registering with Keyfactor Command
          - name: Name
            value: ca-connector-1
          - name: LOG_LEVEL
            value: Info
          - name: OAuthServer__Address
            value: https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token
          #- name: OAuthServer__Scope
          #  value: OPTIONAL-SCOPE
          #- name: OAuthServer__Audience
          #  value: OPTIONAL-AUDIENCE
          - name: OAuthServer__ClientId
            valueFrom:
              secretKeyRef:
                name: client-credentials
                key: client-id
          - name: OAuthServer__ClientSecret
            valueFrom:
              secretKeyRef:
                name: client-credentials
                key: client-secret

        volumeMounts:
          - mountPath: /etc/ssl/certs/ca-certificates.crt
            name: root-ca
            readOnly: true
            subPath: ca-certificates.crt

      volumes:
        - configMap:
            items:
            - key: ca-certificates.crt
              path: ca-certificates.crt
            name: ca-roots
          name: root-ca

      imagePullSecrets:
        - name: keyregcred

Set the permissions on the deployment file such that the file is owned by root and readable only by root (this assumes your Kubernetes implementation is running as root, which is typical). For example:

sudo chown root:root caconnector.yaml

sudo chmod 400 caconnector.yaml

Tip: If you need to make edits to the values file, you will need to make it writable again. For example:
sudo chmod 600 caconnector.yaml

Execute the following command to install and run the container:

kubectl apply --namespace keyfactor-connector -f caconnector.yaml

Tip: To review logs generated from the container, identify the pod name with this command:

kubectl get pods --namespace keyfactor-connector

Then use the following commands to output information about the pod and the current log:

kubectl describe pod [pod name] --namespace keyfactor-connector

kubectl logs --namespace keyfactor-connector [pod name] --follow

The optional follow parameter A parameter or argument is a value that is passed into a function in an application. will continuously output the logs as they are generated until interrupted.

If you need to delete the container and try the install again, use this command:

kubectl delete --namespace keyfactor-connector -f caconnector.yaml

Table 1157: CA Connector Parameters for Kubernetes without Helm

Parameter	Description
CAConfigCacheExpirationMinutes	The number of minutes that the CA configuration will be cached before being cleared. The default is 10.
LOG_LEVEL	The container logging level output. Supported values are: OFF No logging FATAL Log severe errors that cause early termination ERROR Log severe errors and other runtime errors or unexpected conditions that may not cause early termination WARN Log errors and use of deprecated APIs, poor use of APIs, almost errors, and other runtime situations that are undesirable or unexpected but not necessarily wrong INFO Log all of the above plus runtime events (startup/shutdown) DEBUG Log all of the above plus detailed information on the flow through the system TRACE Maximum log information—this option can generate VERY large log files The default value is Info.
Name	Required. The name the CA Connector Client uses to register itself with Keyfactor Command. This name must match the name used when creating a CA connector record in Keyfactor Command (see Preparing). If you choose to uninstall and reinstall the connector (e.g., using compose down), it is important to use the same name for subsequent implementations so that Keyfactor Command will recognize the connector when it is started again.
OAuthServer__Address	Required in some cases. The URL of the token endpoint for the identity provider. For example: Copy `https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token` For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation).
OAuthServer__Audience	The audience that should be included in token requests to the identity provider. The OAuth mechanism in use in your Keyfactor Command environment may or may not require this.
OAuthServer__ClientId	Required. The ID for the client application created in the OAuth identity provider to allow the CA connector to make requests to Keyfactor Command (see Identify the CA Connector Client Access Token). For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.
OAuthServer__ClientSecret	Required. The secret for the client application created in the OAuth identity provider to allow the CA connector to make requests to Keyfactor Command. For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative.
OAuthServer__Scope	One or more scopes that should be included in token requests delivered to the OAuth identity provider when making a token request. Multiple scopes should be separated by spaces. For a managed instance of Keyfactor Command, this value should have been provided to you by your Keyfactor representative. The OAuth mechanism in use in your Keyfactor Command environment may or may not require this.
ServerURL	Required. The URL to the CA connector application on the Keyfactor Command server. SSL is required to connect to the Keyfactor Command server. For example: Copy `kyf101.keyfactorpki.com/KeyfactorCAConnectors`
SignalR__SkipNegotiation	When set to true, tells the SignalR client to skip the negotiation step during the connection. The default is false.
SignalR__TransportTypes	Specifies the transport types that SignalR should use to establish a connection. The default is: "WebSockets, LongPolling"

Was this page helpful? Provide Feedback

Version v25.5

On this page:

Install the CA Connector Client in a Linux Container

Docker

Kubernetes without Helm

Kubernetes with Helm