JFrog

    Cloud customer?
    Start for Free>
    Upgrade in MyJFrog >
    What's New in Cloud >






    Skip to end of metadata
    Go to start of metadata

    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 shouldnotbe 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.

    如果加入。关键是不完全相同的信任rvices, communication between services fail.

    For automation purposes, it is recommend togenerate your own Join Keyand share it with every new instance.

    Fetching the JPD join.key

    The JPD join key can be found either inthe JPD UI in theAdministrationmodule|User Management|Settings|Connection Details. To show the key, you will need anadmin password.
    Alternatively, you will find it (encrypted) inthejoin.keyfilein 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 theAdministrationmodule|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 isnotused for communication between the different JFrog Platform products (unlike thejoin 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).

    Master.key Load and Retention in Memory

    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 byremoving the master key from the file system by each application, after it was read by the application node during bootstrapping.

    Important

    Beforeeveryrestart, you will need to place the master.key file in the filesystem.

    Remember to keep the master.key in a separate,safelocation.

    Customers who wishto use this capability will need to do the following:

    1. Enable the master key removal by setting the flagshared.security.masterKeyExternaltotrue
    2. Fetch the master key and place it in the correct path on the application's file system whenever a new node is bootstrapped

    When the flag aboveis set totrue:

    • The router will remove the master.key file once each service is up and running.
    • Pipelines will not generate a master.key and will instead read the master.key from the database.

    Pairing Tokens

    Available from Artifactory version 7.29.7, apairing 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 yourJFrog 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 areexpected 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 themaster 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

    1. In theAdministrationtab, go toIdentity and Access | Access Tokens | Pairing Token.
    2. In the Generate Pairing Token for field, select Mission Control (for JPDs).
    3. ClickGenerateto 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 clickingCopy.

    Page Contents

    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 agenerate.token.jsonfile under the$JFROG_HOME/artifactory/var/bootstrap/etc/access/keysdirectory.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

    Thegenerate.token.jsonfile 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 theaccess.config.yaml, by modifying the parameterbootstrap-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.
    • 令牌是admin-scoped权限
    • 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 thejoin.keyandmaster.keyfiles are automatically generated by Artifactory during the initial start up of the service.

    A differentkey (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 thesystem.yamlfile.

    Bootstrapping Keys Using the system.yaml File

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

    1. Save thesecurity section of the system yaml filewith the generated string for each key usingmasterKeyparameter for the Master Key andjoinKeyparameter for the Join Key.
    2. Start the service.

    Bootstrapping 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 asjoin.key.

    2. Delete the existingjoin.keyfrom$JFROG_HOME/artifactory/var/etc/security/.

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

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

      乔恩- r artifactory: / etc / securi artifactory访问ty/join.key
    5. 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 thejoin.keymechanism.

    Managing join.keys in HA

    There should only be onejoin.keyper HAcluster 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.


    • No labels
    Copyright © 2023 JFrog Ltd.