Manage Keys

This page covers best practices for creating and managing keys.

You can also use pairing tokens to establish communication between services.

Master Key

The master key is an AES secret key (128 or 256 bit) that is used by Artifactory to securely synchronize files between cluster nodes. It is used to encrypt and decrypt shared data in the database. The master key is not used for communication between the different JFrog services (unlike the join key).

Each JFrog Platform component has its own master key. In HA environments, all instances of a component must have the same master key value, on all HA nodes.

Join Key

The JFrog join key establishes trust between JFrog services based on symmetric encryption (AES-128 bit or AES-256 bit). The join.key is used between microservices of the same service, for example between Artifactory and Access.

Trust is established as follows:

1. To establish trust, the join key is shared between all JFrog services,

2. Services use token-based authentication for communication: each service creates tokens and signs them with the join.key.

   If the join.key is not identical on the trusted services, communication between services fails.

View the Join Key

To view the join key in the JFrog Platform:

1. Go to Administration > Security > General > Connection Details.

2. In the Current Password field, enter your login password, and click Unlock.

   You can view and copy the key from the Join Key field.

The encrypted key is stored in the file $JFROG_HOME/artifactory/var/etc/security/join.key.

Retrieve the Master Key from a Kubernetes Pod

In Helm/Kubernetes installations, retrieve an existing master key directly from a running Artifactory pod:

kubectl exec -it <release>-artifactory-0 -n <namespace> -c artifactory -- cat /opt/jfrog/artifactory/var/etc/security/master.key

Use this when upgrading a Helm installation that now requires the master key to be passed explicitly. See Service Pod Architecture Changes for the full requirement.

View the Master Key via CLI

Run the following kubectl command in your terminal:

export MASTER_KEY=$(kubectl exec -it rt-artifactory-0 -n <NAMESPACE> -c artifactory -- cat /opt/jfrog/artifactory/var/etc/security/master.key)

Create keys

By default the join.key and master.key files are automatically generated by Artifactory during the initial start up of the service.

A different key (hexadecimal encoded) can be created using the following command.

openssl rand -hex 16 
/or
openssl rand -hex 32

Bootstrap with your own keys using the system.yaml file

This method only applies if you have installed but not started your service yet.

1. Save the security section of the system.yaml file with the generated string for each key, using the masterKey parameter for the master key and the joinKey parameter for the join key.
2. Start the service.

Bootstrap the join key using file system

This method can be used even if you already have a join key.

1. Save the generated string file as join.key.

2. Delete the existing join.key from $JFROG_HOME/artifactory/var/etc/security/.

3. Place each file in the $JFROG_HOME/artifactory/var/bootstrap/access/etc/security directory.

4. Add the Artifactory permissions to the directories and the join.key file. For example,

   Bash

   chown -R artifactory:artifactory access/etc/security/join.key

5. Start the service.

Configure Keys in Helm Charts

Starting from release 7.161.x, master and join keys are mandatory for all JFrog Artifactory Helm chart installations. Keys are configured at the global level of values.yaml, making them available to all components in the chart.

Set Keys via --set Flags

export MASTER_KEY=$(openssl rand -hex 32)
export JOIN_KEY=$(openssl rand -hex 32)

helm upgrade --install artifactory jfrog/artifactory \
  --set global.masterKey=${MASTER_KEY} \
  --set global.joinKey=${JOIN_KEY} \
  --namespace artifactory --create-namespace

Set Keys via Kubernetes Secrets (Recommended for Production)

1. Create a Kubernetes secret for each key.

   Bash

   kubectl create secret generic my-masterkey-secret \
     --from-literal=master-key=${MASTER_KEY} \
     --namespace artifactory
   
   kubectl create secret generic my-joinkey-secret \
     --from-literal=join-key=${JOIN_KEY} \
     --namespace artifactory

2. Reference the secrets in values.yaml.

   YAML

   global:
     masterKeySecretName: my-masterkey-secret
     joinKeySecretName: my-joinkey-secret

   Or pass directly via --set:

   Bash

   helm upgrade --install artifactory jfrog/artifactory \
     --set global.masterKeySecretName=my-masterkey-secret \
     --set global.joinKeySecretName=my-joinkey-secret \
     --namespace artifactory --create-namespace

Upgrade Note

If you are upgrading from a release prior to 7.161.x, replace artifactory.masterKey and artifactory.joinKey with global.masterKey and global.joinKey in your helm upgrade commands and values.yaml files.