Overview
This page describes how to create, manage and best practices for your master keys and join keys.
Important
Remember to keep the join key, master key, and other trusted keys safe; they should not be shared with external parties.
Join Key
The JFrog join.key feature establishes trust between the JFrog services based on symmetric encryption (AES-128 bit or AES-256 bit). The join.key is used internally for creating trust between microservices of the same service, for example between Artifactory and Access.
Once trust is established (meaning the join.key is shared between all the different services), the services can continue using the standard token-based authentication for communication. This is accomplished by having each service create the tokens used for the inter-service communication and signing those tokens with the join.key.
Access will then use the provided join.key instead of the auto-generated one, save it to its database, and share it with Artifactory.
If the join.key is not identical on the trusted services, communication between services fail.
For automation purposes, it is recommend to generate your own Join Key and share it with every new instance.
Fetching the JPD join.key
The JPD join key can be found either in the JPD UI in the Administration module | User Management | Settings | Connection Details. To show the key, you will need an admin password.
Alternatively, you will find it (encrypted) in the join.key file in the Artifactory file-system under $JFROG_HOME/artifactory/var/etc/security.
Until Artifactory version 7.38.10, the join key could be found in the JPD UI in the Administration module | Security | Settings | Join Key.
Note: you can only share the encrypted join.key with services using the same master.key.
Master Key
The Master key is an AES secret key (128 or 256 bit) that's used by Artifactory to securely synchronize files between cluster nodes. It is responsible for encrypting and decrypting the shared data in the database.
If the master.key is not identical on the cluster nodes, the service will not be able to decrypt configuration files from the database.
The master key is not used for communication between the different JFrog Platform products (unlike the join key, which is used to communicate between Artifactory, Xray, and other JFrog services).
The master key is set per product, and must be the same for all the nodes in the same service (when using HA).
To improve security around the storage of the master.key, from Artifactory version 7.29.7, JFrog supports loading the master.key at startup and keeping it in memory. This is achieved by removing the master key from the file system by each application, after it was read by the application node during bootstrapping. Important Before every restart, you will need to place the master.key file in the filesystem. Remember to keep the master.key in a separate, safe location. Customers who wish to use this capability will need to do the following: When the flag above is set to true:Master.key Load and Retention in Memory
shared.security.masterKeyExternal to true
Pairing Tokens
Available from Artifactory version 7.29.7, a pairing token establishes trust between different JFrog microservices. The pairing token is an access token that is used for the initial pairing flow. Because the token is a limited access token, it is dedicated to a specific task and short-lived. Once trust is established, the services can continue using the standard token-based authentication for communication.
Pairing tokens replace the join.key that was used in the past in the JFrog Platform to link between services. This type of token is only designed to link cross-topologies (i.e., locally, and not with in a JPD).
Pairing tokens enable you to connect between your JFrog Platform Deployment (JPD) / edge and a remote JFrog Mission Control service. Pairing tokens provide pairing for a specific purpose use case. They are revocable, and are expected to be used at most once (i.e., revoked after first pairing). The default expiry setting for these tokens is 5 minutes.
- The subject of the token is the same as the subject of the principal who requested the pairing token/
- The base URL in the extension is mandatory
- The exchange URL in the extension is mandatory (since the token is signed, this URL can be assumed as trusted)
- The pairing URL is optional and is used when you need to establish a two-way trust
Master Token
The result of a pairing is the master token, which is an access token that grants the requesting service all the actions it is required to do on the issuing service, based on the given use case. The master token is usually a strong access token that can be used for several operations and is usually a long-lived token. An admin user can revoke trust by revoking this token.
Setting up Pairing Tokens
- In the Administration tab, go to Identity and Access | Access Tokens | Pairing Token.
- In the Generate Pairing Token for field, select Mission Control (for JPDs).
- Click Generate to generate the token.
This displays the token window, which includes the token's expiration (in seconds, set by default to 300 seconds = 5 minutes), the token ID, and the actual token, which you can copy by clicking Copy.
Creating an Automatic Admin Token
From Artifactory release 7.38.4.
JFrog enables companies to create their own admin-scoped access token without using the JFrog Platform UI or via another token. This Access admin-scoped token is designed to be used for a short time only and its purpose is to start up the system. This provides customers with the option of setting up their JFrog Platform in an automated, fully UI-free setup.
To securely-generate the "first" admin-scoped access tokens, without relying on a previous token or basic credentials:
Generate an admin-scoped token by placing a generate.token.json file under the $JFROG_HOME/artifactory/var/bootstrap/etc/access/keys directory. For example:
$JFROG_HOME/artifactory/var/bootstrap/etc/access/keys/generate.token.json
When bootstrapping, if this file is created, this will generate a token and set it under the $JFROG_HOME/artifactory/var/etc/access/keys/ directory. For example:
$JFROG_HOME/artifactory/var/etc/access/keys/token.json
The generate.token.json file will be deleted from the file system once the token has been generated. The file containing the token, token.json, will be deleted by default after 1 minute. This can be changed via the access.config.yaml, by modifying the parameter bootstrap-token-delete-in-minutes (in $JFROG_HOME/artifactory/var/etc/access/access.config.template.yml).
The resulting token's properties are as follows:
- The generated token is limited to a 15 minute expiry, after which the system will revoke the token.
- The token is admin-scoped for permissions
- The token has an audience of access service: jfac@*
- The token has the subject "admin" - even if the admin user does not exist
For Docker installations, you will need to mount the bootstrap directory.
Creating Your 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
Bootstrapping with Your Own Keys
There are two ways to manually update your keys: file copy and/or bootstrap via the system.yaml file.
Bootstrapping Keys Using the system.yaml File
This method only applies if you have installed but not started your service yet.
- Save the security section of the system yaml file with the generated string for each key using masterKey parameter for the Master Key and joinKey parameter for the Join Key.
- Start the service.
Bootstrapping the join.key Using File System
This method can be used even if you already have a join.key
- Save the generated string file as join.key.
Delete the existing join.key from
$JFROG_HOME/artifactory/var/etc/security/.- Place each file in the
$JFROG_HOME/artifactory/var/bootstrap/access/etc/securitydirectory. Add the Artifactory permissions to the directories and the join.key file. For example,
chown -R artifactory:artifactory access/etc/security/join.key
- Start the service.
Managing the join.key
By default, a join.key is automatically generated and stored in the Access database during Access startup.
The join.key is then automatically copied by Access to Artifactory over the file system and is re-provisioned every time the services are restarted.
Access shares the join.key with Artifactory by copying it to the following location:
$JFROG_HOME/artifactory/var/etc/security/join.key
Upgrading to Artifactory 6.8 automatically initiates and generates the join.key mechanism.
Managing join.keys in HA
There should only be one join.key per HA cluster since the Access database is shared across all nodes of an HA cluster.
In case a join key is provided and not generated by the system, it can be provided to a single cluster node as it will be propagated to all nodes of the cluster by the system.
