Applying Configuration Changes
Once you have configured your YAML file to include all the configuration changes needed, you can apply them by following the steps using the different YAML configuration files described below.
Take care when modifying Access configurations
Modifying the Access configurations is an advanced feature, and if done incorrectly may render Access in an undefined and unusable state. Since it is easy to overwrite configurations, we strongly recommend backing up the configuration YAML file before making any direct changes, and taking great care when doing so.
YAML Configuration Files
There are several configuration files that may found under the $JFROG_HOME/artifactory/var/etc/access folder:
access.config.import.yml | If this file exists, it is the configuration file that the Access services actually imports and overrides all the existing settings when restarted. If the file does not exist, Access will load with its latest configuration settings. |
access.config.patch.yml | If this file exists, the values specified in the imported file will replace the existing Access configuration values. If the file does not exist, Access will load with its latest configuration settings. |
access.config.template.yml | This is a template file provided upon installation. It includes default values for a variety of configuration parameters, as well as simple examples for others. Don't load or modify this file The purpose of this file is to provide a reference to the list of configurable parameters governing Access. Some of the parameters provide recommended default values, however other parameters (such as server names) contain sample values that, if loaded into your Access services, may render them unusable. We strongly recommend not modifying this file, and not uploading it (by changing its name to |
access.config.latest.yml | This file shows which configuration parameters are different from the default values in the current Access configuration. This is the file you should be editing and renaming to access.config.import.yml if you wish to make configuration changes |
access.config.latest.<timestamp>.yml | This file shows previous versions of the access.config.latest.yml file with a timestamp to indicate when it was replaced. |
Uploading the YAML File
To setup your Access configuration files, you need to work with the above YAML files in the following way:
Open the
access.config.template.ymlfileFind the Key for which you would like to change the Value and copy it
Open the
access.config.latest.ymlfilePaste the Key - Value pair you copied and set the relevant value as desired
Save the
access.config.latest.ymlfile asaccess.config.import.ymlor asaccess.config.patch.ymlRestart Access by restarting the corresponding Artifactory service
Note that an uploaded configuration file does not update the current configuration in Access, but rather completely replaces it.
Making multiple configuration calls
You may configure synchronization as often as you want and with any combination of parameters.
Example
To change the setting of number-of-retries from 3 (the default) to 5, you would take the following steps:
- Open the
access.config.template.ymland copy thenumber-of-retries: 3Key-Value pair. - Paste the copied Key-Value pair into the
access.config.latest.ymlfile - In
access.config.latest.yml,change the value ofnumber-of-retriesto5 - Save the modified
access.config.latest.yml as access.config.import.yml - Restart Artifactory - this will restart the Access service which will then load the values in access.config.import.yml with the updated configuration
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
Reverting to Previous Configurations
Every time you change the Access configuration by loading a new access.config.import.yml file, Access stores the current configuration, before it is replaced, in an access.config.latest.<timestamp>.yml file.
At any time, if you want to revert to a previous configuration:
- Find the
access.config.latest.<timestamp>.ymlfile with the relevant timestamp. - Rename the file to access.config.import.yml
- Restart Artifactory - this will restart the Access service which will then load the values in access.config.import.yml with the updated configuration
Supported Configurations
Below is an example of a complete YAML file showing all the different parameters that you may configure
# DO NOT IMPORT THIS FILE.
# This file describes the JFrog Access YAML configuration file and should only be
# as a reference.
#
# To change the configuration in an Access service, follow these instructions:
# 1. Find the value you want to update
# 2. Set the value in the access.config.latest.yml file under [$JFROG_HOME]/artifactory/var/etc/access
# 3. Change access.config.latest.yml to access.config.import.yml
# 4. Restart Access
---
security:
multi-factor-authentication:
authenticators: [ ] # list of available authentication providers. feature is disabled if unset
application-name: JFrog Platform # app name to display in Authenticator App
password-policy: # users' password policy
uppercase: 0 # minimum number of uppercase letters that the password must contain
lowercase: 0 # minimum number of lowercase letters that the password must contain
digit: 0 # minimum number of digits that the password must contain
length: 4 # minimum length of the password
not-match-old: true # should access allow setting a new password to the same one currently set for the user
user-lock-policy:
attempts: 0 # number of failed login attempts to allow before locking a user. 0 (default) means the feature is disabled
seconds-to-unlock: 1 # number of seconds to wait before re-enabling login for a user that has been locked out
password-expiry-days: 0 # number of days before a password expires. Set by Artifactory
admin-password-expirable: false # does the access admin password expire
audit:
enabled: true # should access log all requests to a specific file or not
password-strength: 8 # bcrypt password strength. A higher value means better security, but password verification will be slower
local-interfaces-expire-in-seconds: 600 # number of seconds for which local server ips should be cached for users’ allowed-ips
encryption-enabled: true # specifies if users’ custom data encryption is allowed
tls: false # When set to true, JFrog Access will act as the Certificate Authority (CA) and sign the TLS certificates used by all the different JFrog Platform nodes. This ensures that the node to node communication is done over TLS.
tls-minimal-version: TLS-1.2 # When set, node to node communication via TLS will support only TLS with version matching the minimal version and above
tls-subject-alternative-names: # When set, these names will be added as SAN to the generated node TLS certificate
- myaoleustghttpsv-artifactory
- myaoleustghttpsv-artifactory-artifactory
- "*.svc.myaoleustghttpsv.cluster.local"
topology-stale-millis: 30000 # The time passed from the last heartbeat of any of the micro-services in the topology, before it is considered stale
secrets-require-tls: true # if true then tls must be enabled in order to store sensitive configuration (like vault config)
token:
refresh-expiry: 86400 # grace period (seconds) during which an expired token can still be refreshed. Must be positive.
default-expiry: 31536000 # default expiry period (seconds) when token expiry is set to null. When set to zero, default expiry is not forced. Must be non-negative. Must comply with ('max-expiry' >= 'default-expiry').
max-expiry: 0 # max expiry period (seconds) When max expiry is bigger than zero, non-expirable tokens are forbidden and the user's token expiry will be limited to the max expiry value. When set to zero,the user's token can be non-expirable and the expiry will not be limited with a higher boundary. Must be non negative. Must comply with ('max-expiry' >= 'default-expiry').
allow-refreshable: true # when disabled, all the user tokens will be created as non refreshable.
default-expiry-internal: 3600 # default expiry period (seconds) when -internal- token expiry is set to null. Must be positive.
cache:
expire-after-write-seconds: 60 # number of seconds Access waits before deleting an entry from the cache
maximum-size: 1000 # maximum number of tokens Access allows in the cache
revocation:
minimum-revocable-expiry: 21600 # DEPRECATED - Please use 'revocable-expiry-threshold' instead - (seconds) token with expiry (expirationTime-issuedAt) below this value will not be revocable. (tokens without expiry are always revocable) set to -1 to make all tokens with expiry non-revocable (default).
revocable-expiry-threshold: 21600 # Available from Artifactory 7.8.0 - (seconds) token with expiry (expirationTime-issuedAt) below this value will not be revocable. (tokens without expiry are always revocable) set to -1 to make all tokens with expiry non-revocable (default).
persistency:
persistent-expiry-threshold: 10800 # Available from Artifactory 7.8.0 - (seconds) token with expiry (expirationTime-issuedAt) below this value will not be persistent. set to -1 to make all tokens persistent. lowering this value will effectively revoke all tokens with expiry below the old value and above the new revocable-expiry-threshold.
delete-with-user: true # if should delete user tokens when deleting user.
block-simultaneous-login: false # when set to true, Access will revoke User's session tokens when a new session token is created for the same user
integration-secret-expiry-secs: 0 # Expiry period of the secret token. In seconds. Default: 0. 0 means never expires.
user-invitation-token-expiry-secs: 2592000 # The user's invitation token expiry period. In seconds. Default: 30 days. 0 means never expires.
task:
revoke-expired-tokens-cron: "0 0 0/1 * * ?" # cron expression defining when the "revoke expired token" job should run. disable the job by using "-". when the default value is set the seconds & minutes of the cron job are randomly generated.
send-usage-cron: "0 0 23 * * ?" # cron expression defining when the "send usage" job should run
heartbeat:
interval-seconds: 5 # interval between successive runs of the heartbeat job
consider-stale-seconds: 30 # the time period (seconds) a server can remain unresponsive before being considered stale in the cluster
stale-admin-revoke:
interval-seconds: 3600 # interval between successive runs of the stale admin revoke job, e.g. once an hour
consider-stale-seconds: 604800 # the time period (seconds) since the last heartbeat was registered in the topology, so is considered stale, e.g. every 7 days
load-certificates-seconds: 30 # period of time in seconds when to look if there are any new "trusted certificates"
cluster:
sync:
timeout-millis: 100 # initial time (ms) to wait before retrying a request
socket-timeout-millis: 5000 # time to wait (ms) before giving up on executing a REST call on another server
exponential-backoff-multiplier: 2 # number by which the retry timeout should be multiplied before a subsequent retry. For example, by default, the third retry will happen after 200 ms
number-of-retries: 3 # maximum number of retries
backoff-max-delay-millis: 1000 # maximum time between successive retries regardless of other settings
force-rest: false # whether to force rest in grpc sync
force-grpc: false # whether to force grpc in grpc sync when syncing over https
startup-sanity-retry: 200 # maximum number of retries for validating self ping via router
maximum-future-time-diff-millis: 60000 # maximum difference between previous data timestamp and received data timestamp that is allowed
join:
router-check-url-timeout-millis: 3000 # connection timeout (ms) for validating router responsiveness in url 'check-url'
project:
cache:
expire-after-write-seconds: 3600 # number of seconds Access waits before deleting an entry from the cache
maximum-size: 10000 # maximum number of entries allows in the cache
socket-timeout-millis: 10000 # time to wait (ms) before giving up on executing a REST call on another server
connect-timeout-millis: 10000 # time to wait (ms) before giving up on connecting to another server
federation:
outbound: # outbound configuration specifies parameters for sending data
entity-types-to-sync: # entity types to sync as part of federation (default - used if not configured for server)
- users
- groups
- permissions
- tokens
exclude-users: [ "admin","access-admin","xray" ] # do not put this user in the federated server (must be an array)
buffer-wait-millis: 30000 # amount of time (ms) data should be accumulated before being sent
buffer-max-size: 500 # maximum number of events that can be accumulated before triggering sending of data
consider-stale-hours: 168 # time (hours) server can remain unresponsive before being considered stale
maximum-future-time-diff-millis: 60000 # maximum difference between received data timestamp to current timestamp of the server that is allowed
timeout-millis: 3000 # initial wait between retries
exponential-backoff-multiplier: 2 # number by which the retry timeout should be multiplied before a subsequent retry. For example, by default, the third retry will happen after 6000 ms
initial-server-grace-period-millis: 1000 # how long to wait for the first query (due to load time etc)
number-of-retries: 3 # maximum number of retries
backoff-max-delay-millis: 10000 # maximum time between successive retries regardless of other settings
delay-on-error-millis: 300000 # time to wait (ms) after an error occurred
socket-timeout-millis: 30000 # time to wait (ms) before giving up on executing a REST call on another server
connect-timeout-millis: 10000 # time to wait (ms) before giving up on connecting to another server
delete-stale-events-factor: 2.0 # how much to multiply consider-stale-hours before deleting any federation events, even if not sent
servers:
- name: hello-1 # the name of the target server
url: "http:#example.com/access" # the target server url
active: true # whether the federation to this server is enabled or not
entity-types-to-sync: # entity types to sync as part of federation. if not configured - fallback to outbound entity types to sync
- users
- groups
- permissions
- tokens
permission-filters: # include and exclude patterns filtering permissions to federate per server
include-patterns:
- ".*a.*"
- ".*b.*"
exclude-patterns:
- ".*aa.*"
force-override: true # if true then the target (if access >= v7.8 or >= 6.21.1) will always erase local changes even if updated
# - name: hello-2 # you can configure any number of target servers
# url: "http:#example2.com/access"
inbound: # inbound configuration specifies receiving data
number-of-retries: 3 # number of retries to consume the incoming data
service-id-mapping:
- from: jfrt@1234567890abcdef # service id to change from for permissions and tokens
to: jfrt@fedcba0987654321 # service id to change to
- from: jfbt@abcdefabcdefabcdef # any number of server mappings can be specified
to: jfbt@aaaaaaaaaaaaaaaaa
backoff-max-delay-millis: 30000 # maximum time between successive retries regardless of other settings
exponential-backoff-multiplier: 2 # number by which the retry timeout should be multiplied before a subsequent retry. For example, by default, the third retry will happen after 6000 ms
timeout-millis: 1000 # initial wait between retries
permissions-resource-rename:
- filter: "^docker-([A-Z]*)$" # pattern that will try to match the repository keys on incommming permission change
map: "CN" # replacement for the capturing group of the regex
- filter: "^mvn-([A-Z]*)$"
map: # empty will remove the capturing group
forward-propagation: false # Whether to forward federation changes to other servers or not, avoid combine with force-override to prevent circular propagation
proxy:
host: "localhost" # proxy's host
port: 4567 # proxy's port
db:
batch-size: 2000
startup-check-enabled: true # If enabled, access will run some check on the DB setup at startup.
licenses: # should only be set by Artifactory
- server-name: "hello"
key: "veryLongLicense"
integrations-enabled: false # Default: false
integration-templates: # list of possible integrations to create
- id : "1" # The id of the integration template, to save a reference back from the integration.
name: "my integration" # The name of the integration as will appear in the UI when creating a new integration.
redirect-uri: "https://my-jfrog-integrations.com/callback" # The redirect-uri that will direct users back to the integration client with the authorization code.
scope: "applied-permissions/user" # Only this scope is currently supported.
max-config-files-to-retain: 10 # maximum number of configuration file versions to save after being updated
schema-version: 2 # Mark the configuration schema version. If it's not the latest version, a migration operation will be performed.
do-not-import-this-file # Ignore: a marker to prevent import of this file
For the TLS flag above, the minimal version is TLS-1.2. When set, node-to-node communication via TLS will support only TLS with the version matching the minimal version and above.
