Using Artifactory 6.x ?
JFrog Artifactory 6.x User Guide
Have a question? Want to report an issue? Contact JFrog support
Access Service
From Artifactory version 5.4, access tokens are managed under a new service called Access which is implemented in a separate WAR file, access.war
. This change has no impact on how access tokens are used, however, the Artifactory installation file structure now also includes the added WAR file under the $ARTIFACTORY_HOME/webapps
folder. Artifactory communicates with the Access service over HTTP and assumes it is running in the same Tomcat using the context path of "access".
The new implementation is backwards compatible to old tokens, so you can still use tokens generated by an older version to authenticate in the new version, however, you cannot use tokens generated by the new version to authenticate in an older version.
Breaking Change: Note that the change is not backwards compatible, so tokens created from version 5.4 and above cannot be used for authentication with versions prior to 5.4. This may impact a circle of trust in which some instances are running versions below 5.4 while others are running version 5.4 and above.
Access Service Logs
The Artifactory Access Service uses the Logback Framework to manage logging. Activity is logged according to type in three different log files which can be found under the ARTIFACTORY_HOME/access/logs
folder.
The following log files are available:
access.log | This is the main Access service log file containing data on the Access server activity |
request.log | The HTTP traffic information for requests coming in. Most of these are from Artifactory |
audit.log | Auditing of the actions performed by the service. Currently only successful actions are recorded (e.g. token was created, token was refreshed or revoked) |
Since the Access service runs under the same Tomcat as Artifactory, its logs (catalina.out. localhost etc.) contains entries for both Artifactory and Access.
Configuring Logging
Logging for the Access service is configured in the $ARTIFACTORY_HOME/access/etc/logback.xml
file.
Cross-Instance Authentication
Access tokens support cross-instance authentication through a "circle of trust" established by sharing a public certificate among all participating instances. It is up to the Artifactory administrator to make sure that all participating instances are equipped with the certificates. This means that any instance can generate a token to be used with any other instance within the circle of trust. When an Artifactory instance receives a REST API call authenticated by a signed token, it will use the root certificate that includes the public key to verify that its issuer is in the circle of trust. Even while running, Artifactory is aware to any new certificates added and removed from it.
Limitations
Only a token that is expirable and refreshable can be used for authentication on a different instance from the one that created it.
Only the issuing instance can refresh a token.
Setting the Private Key and Root Certificate
It is up to the Artifactory administrator to make sure that all participating instances are equipped with the public key (root certificate).
Access watches a directory of trusted public keys with nio WatchService and reloads the keys when it needs to verify a token.
All that is needed is to place the keys under $ARTIFACTORY_HOME/access/etc/keys/trusted.
Access home layout (new entries are in bold):
[$ACCESS_HOME]
|
+-- etc/
+-- keys/
|-- root.crt
|-- private.key
+-- trusted/
|-- [name].crt
|-- [name2].crt
|-- [name3].crt
+-- ...
Artifactory HA
For Artifactory HA installations, root certificates should to be placed under $ARTIFACTORY_HOME/access/etc/keys/trusted
in each node of a cluster.
This process used to vary depending on whether you are bootstrapping new instances or setting up cross-instance authentication for existing instances (up until version 5.9.0 where the above instructions are outlined).
The steps for each case are described in the following sections.
New Instances
Artifactory Pro or OSS
- Start up the first Artifactory instance (or cluster node for an HA installation) that will be in your circle of trust. A private key and root certificate are generated and stored under
$ARTIFACTORY_HOME/access/etc/keys
. Copy the private key and root certificate files to a location on your file system that is accessible by all other instances/nodes that are in your circle of trust.
Before bootstrapping, for each of the other instances/nodes, create the $ARTIFACTORY_HOME/access/etc folder and create a properties file in it called
access.bootstrap.config
with the following contents:key=/path/to/private.key crt=/path/to/root.crt
- When each instance/node starts up, if the $ARTIFACTORY_HOME/access/etc/
access.bootstrap.config
file exists, then the private key and root certificate are copied from the specified location into the server's home directory under $ARTIFACTORY_HOME/access/etc/keys.
Artifactory HA
In the case of an Artifactory HA installation, the private key and root certificate can be found under $ARTIFACTORY_HOME/access/etc/keys
in the primary node.
Existing Instances
Key rotation will invalidate any issued access tokens
The procedure below will create new key pairs which in turn will invalidate any existing Access Tokens issued by the current instance.
Do this first!
Copy the private key and root certificate files from the Artifactory instance whose circle of trust you want the current instance to join, to a location on your file system that is accessible by the current instance.
Before bootstrapping the instance:
For Artifactory version below 5.6.0:
- Delete the existing private key and root certificate files (
private.key
androot.crt
) from the$ARTIFACTORY_HOME/access/etc
folder. Create the $ARTIFACTORY_HOME/access/etc/
access.bootstrap.config
with the following contents:key=/path/to/private.key crt=/path/to/root.crt
Add the following JVM property (under the JAVA_OPTIONS enviroment variable) to
$ARTIFACTORY_HOME/bin/artifactory.default:
-Djfrog.access.force.replace.existing.root.keys=true
Start up the instance ready to be added to your circle of trust and verify that the artifactory.log file shows the following entry:
******************************************************************* *** Forcing replacement of the root private key and certificate *** *******************************************************************
Delete the JVM property you added to $ARTIFACTORY_HOME/bin/artifactory.default in step 3.
For Artifactory versions between 5.6.0 and 5.9.0:
- Delete the existing private key and root certificate files (
private.key
androot.crt
) from the$ARTIFACTORY_HOME/access/etc
folder. Create the $ARTIFACTORY_HOME/access/etc/
access.bootstrap.config
with the following contents:key=/path/to/private.key crt=/path/to/root.crt
- Save the Configuration Descriptor from the Artifactory UI or use the General Configuration REST API and save it locally under
$ARTIFACTORY_HOME/etc/artifactory.config.import.xml.
Completely remove the adminToken tags and its value from the Configuration Descriptor file saved from above.
Validate all correct permissions are set on the files above then restart Artifactory.
Verify that the
$ARTIFACTORY_HOME/logs/artifactory.log
or/and$ARTIFACTORY_HOME/access/logs/access.log
file shows the following entry:**************************************************************** *** Skipping verification of of the root private fingerprint *** **************************************************************** *** Private key fingerprint will be overwritten **************** ****************************************************************
The $ARTIFACTORY_HOME/access/logs/access.log will show the entries below:
[ACCESS BOOTSTRAP] Starting JFrog Access bootstrap... [ACCESS BOOTSTRAP] Copying private key and root certificate files provided by bootstrap config. [ACCESS BOOTSTRAP] Updating server '5d2f9c44-6bff-4723-80e2-45835965d76c' private key finger print to: 2212e73eeb3b4ee604f80045d0028473293f54ba05851ea6a6cbb34fecad2a2b [ACCESS BOOTSTRAP] JFrog Access bootstrap finished.
Keypair propagation in an existing HA cluster
With High Availability clusters the private.key and root.key are propagated automatically and are updated per what it is the saved on the cluster shared database.
The steps should be made primary node, which will also print the following log entry in its $ARTIFACTORY_HOME/logs/artifactory.log:
Publish changes to another access peer [http://<artifactoryNode>:<port>/access] successfully
Using Tokens
There are several ways you can use access tokens for authentication.
Basic Authentication
An access token can be used instead of a password for basic authentication. This may be useful when you need a client (such as certain dependency managers) that only supports basic authentication to access Artifactory. In this case, it is important to access Artifactory using the same user name provided when creating the token (with -d "username=<USERNAME>"
).
For example, to use an access token as a password to ping Artifactory you could use:
curl -u<USERNAME>:<TOKEN> http://ARTIFACTORY_URL/api/system/ping
Authorization Headers
An access token can be used as a bearer token in authorization headers. This is especially useful for authenticating CI servers with Artifactory instead of using credentials, since you don't need to have a user defined in Artifactory if the group provided in -d "member-of-groups:<GROUP>"
is configured in that Artifactory instance. As a result, there is no need to manage fictitious users for your different automation tools that need access to Artifactory.
For example, to use an access token as a bearer token to ping Artifactory you could use:
curl -H"Authorization: Bearer <TOKEN>" http://ARTIFACTORY_URL/api/system/ping
Support Authentication for Non-Existing Users
One of the big advantages of access tokens is the fact that you don't have to create a user in Artifactory to use them. When creating a token, you can specify a user name that does not exist, and Artifactory will create a transient user that will only exist as long as the token is valid. This can be useful to in giving access to different tools such as a CI server coordinating a build without having to manage fake user accounts. This method is also more secure since you can assign a new token for each "job" that the external tool runs.
Artifactory Administrator Only
Note that this feature is only available for Artifactory administrator since non-admin users can only create tokens with themselves as the Subject.
Generating Expirable Tokens
Expirable tokens cannot be revoked
A token with an expiry specified will lapse automatically upon reaching its expiry period.
You can limit the validity period of a token by setting the expiry time when generating a token. If set, the token will be valid until the expiration time will pass.
You can all set a token to be non-expirable by setting the expiry to zero, in which case it will valid indefinitely until actively revoked.
This value is set by using the "&expires_in=<VALUE_IN_SECONDS>" param when generating the token (see example in REST API section below). If not used the default value will be 3600 meaning your token will be valid for one hour.
Artifactory Administrator Only
Note that only an Artifactory administrator can change the validity period of a token to any value. Non-admin users, can only set the token validity period to a value that is equal or less than the default 3600 seconds.
Generating Refreshable Tokens
As mentioned above, you can limit the validity period of an token by setting its expiry time. To allow extending access privileges of a token once it has expired, you can provide a refresh token which will generate a new token with the same privileges as the original one. This takes token management out of the hands of its issuer and delegates it to the user who received the token.
Who can refresh?
Only the instance (or HA cluster) that issued a refreshable token can actually refresh it.
Limitation
An external user who has created a token will still be able to refresh it even if he has been removed from the external authentication server.
Generating Admin Tokens
In general, the scope for a token is defined by specifying the groups into which the token is included, however, an Artifactory administrator can also create a token with admin privileges. This can be useful for JFrog Mission Control and JFrog Xray since both of these complementary applications require admin permissions to work seamlessly with Artifactory. With this capability, when Mission Control or Xray connect to an instance of Artifactory, they can create an admin tokens and use that for authentication instead of using basic authentication with a username and password.
Revoking Tokens
Any refreshable or non-expirable token can be revoked but only by the instance (or cluster) that issued it. A token with an expiry specified will lapse automatically upon reaching its expiry period. A token that is not expirable (expires_in
parameter is set to 0) must be actively revoked to terminate its usage. As described above, to support cross-site authentication, a token must be both expirable and refreshable. Note that this kind of token cannot be revoked. The only way to terminate its usage is to revoke its refresh token, so its usage will be terminated next time its expiry period lapses.
"Revoking" a cross-instance authentication token
To terminate usage of a token used for cross-instance authentication, you need to revoke its refresh token.
REST API
All management of access tokens is done via REST API through the endpoints described below.
Create Token
Creates an access token.
For details, refer to the REST API documentation for Create Token.
Refresh Token
Refresh an access token to extend its validity. If only the access token and the refresh token are provided (and no other parameters), this pair is used for authentication. If username or any other parameter is provided, then the request must be authenticated by a token that grants admin permissions.
For details, refer to the REST API documentation for Refresh Token.
Revoke Token
Revoke an access token
For details, refer to the REST API documentation for Revoke Token.
Get Service ID
Provides the service ID of an Artifactory instance or cluster
For details, refer to the REST API documentation for Get Service ID.
UI
Admin users can view details on all created Access Tokens in the Admin module under Security | Access Tokens.
The Access Tokens page allows you to view, revoke, search by subject and filter to view only expirable tokens.
Additional functionalities, such as creating new tokens, is done via REST API.