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.

If the concern is a security incident rather than key exposure, for example compromised admin or access tokens during CVE remediation, the master key does not need to change. It only encrypts data at rest and plays no role in token validation. Instead, revoke or rotate the specific compromised tokens, rotate the join key if service-to-service trust is also suspected, or invalidate every outstanding token at once by rotating the signing certificate pair described in Custom Token Certificates.

Join Key

The JFrog join key establishes trust between JFrog services using a shared secret for HMAC-SHA256 (JWS HS256) token signing. 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:

POD=$(kubectl get pods -n <namespace> -l app=artifactory -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it ${POD} -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.

Rotate the Join Key

Unlike the master key, the join key can be safely rotated. To rotate it (for example, after suspected exposure):

1. Generate a new key: openssl rand -hex 32.
2. Apply it to every component that currently shares the old join key, using whichever provisioning method your installation uses:
   • Helm: update the Secret referenced by global.joinKeySecretName (recommended, see Set Keys via Kubernetes Secrets below), or pass the new value directly via global.joinKey, then run helm upgrade for every release that shares it.
   • Ansible: set the new value as join_key in group_vars/all/vars.yml (or pass it via --extra-vars). Also set artifactory_systemyaml_override: true (and the equivalent xray_systemyaml_override / distribution_systemyaml_override for other products) for the run. By default the playbook skips rewriting system.yaml if it already exists, so without this the new key is never applied. Then re-run the playbook against every host (see the Ansible Quick Start).
   • Standalone: use Bootstrap the join key using file system below, on every node.
3. Apply the change to all trusting services within the same maintenance window. Services with mismatched join keys cannot communicate with each other until every instance is updated.
4. Confirm trust is restored by checking service logs for authentication errors between components.

View the Master Key via CLI

Run the following kubectl command in your terminal:

POD=$(kubectl get pods -n <NAMESPACE> -l app=artifactory -o jsonpath='{.items[0].metadata.name}')
export MASTER_KEY=$(kubectl exec -it ${POD} -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 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 under shared in the system.yaml file (shared.security.masterKey / shared.security.joinKey) 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, move artifactory.masterKey and artifactory.joinKey to global.masterKey and global.joinKey in your helm upgrade commands and values.yaml files. The artifactory.* values still work as a lower-precedence fallback, but global.* is the current mechanism and is what other chart-managed services (Frontend, JFBus, JFmelt) read for their own mandatory key validation.