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 Service 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 a Service 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, the system is aware of any new certificates that have been added or removed.
Limitations
Access will check for a token's revocation based on the minimum-revocable-expiry parameter set in the access.config.file.
If a token was created on a different server and is checked for revocability, it will be considered revoked, since it is not in the checked database (unless using Access Federation).
Therefore, by default, only non-revokable tokens (tokens with expiry) can be used for authentication on a different instance from the one that created it.
By default, only the issuing instance can refresh a token. For synchornizing tokens across services, see access federation.
Establishing a Circle of Trust
To establish a "circle of trust" between JFrog services, you need to exchange public certificates between the services.
To exchange the certificates, you need to copy a service’s root certificate to another service’s $JFROG_HOME/artifactory/var/etc/access/keys/trusted folder.
The service's root certificate can be acquired in the following ways:
- found under
$JFROG_HOME/artifactory/var/etc/access/keys/root.crt(requires physical access to the server) - by calling Get Root Certificate REST API
You can use your own custom private key and root certificate key pair, and pre-set a circle of trust by directly adding the relevant keys before you startup the service:
- Private key:
$JFROG_HOME/artifactory/var/etc/access/keys Public key: $JFROG_HOME/artifactory/var/etc/access/keys/trusted
If no custom keys are provided in JFROG_HOME/artifactory/var/etc/access/keys, Access will generate them on first startup.
Trust can be created between multiple services. you need to make sure that all participating instances in the circle of trust are equipped with the relevant public keys (root certificate). Note that a trust can be unidirectional or bidirectional. The services watch a directory of trusted public keys and reloads the keys when it needs to verify a token.
Renaming the source service’s certificate
Since trust can be created between multiple services, you should rename each source service’s certificate with a meaningful name. For example, if one service named “us-east” should be trusted by another service named “us-west”, then $JFROG_HOME/artifactory/var/etc/access/keys/root.crt from us-east, should be copied to $JFROG_HOME/artifactory/var/etc/access/keys/trusted/us-east.crt on us-west.
Certificates in HA
Keypair propagation in an existing HA cluster
When using certificates in High Availability clusters, the private.key and root.key are propagated automatically and are updated between the cluster nodes.
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 JFrog Platform URL, you could use:
curl -u<USERNAME>:<TOKEN> http://JFROG_PLATFORM_URL/router/api/v1/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://JFROG_PLATFORM_URL/router/api/v1/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 when providing 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
By default, expirable tokens cannot be revoked, but this can be configured
When creating a token, if the token expiry is set to a value smaller than the minimum-revocable-expiry parameter specified in the Access YAML Configuration, the token will be non-revocable.
By default, the value of the minimum-revocable-expiry parameter is set to -1 which means that any token with expiry specified cannot be revoked until it expires naturally.
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 also set a token to be non-expirable by setting the expiry to zero, in which case it will be 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
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 maximum allowed value. This can be specified by setting the artifactory.access.token.non.admin.max.expires.in parameter in the $JFROG_HOME/artifactory/var/etc/artifactory/artifactory.system.properties file (default: 3600).
Note: The artifactory.access.token.non.admin.max.expires.in parameter cannot be set to a value higher than the access.token.expiresIn.default parameter value.
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
Available from Artifactory version 7.4.
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.
To create an admin token, from the administration module, go to Identity and Access | Access Tokens screen | Generate Admin Token.
Viewing and Revoking Tokens
Any token created with expiry greater than the minimum-revocable-expiry parameter can be revoked using the Revoke Token REST API endpoint or in the Access Tokens page in the UI. Note that you can only revoke a token on the instance (or cluster) that issued it unless that instance is part of an Access Federation setup (which requires an Enterprise+ license).
A token with an expiry specified will lapse automatically upon reaching its expiry period.
A token that is not expirable (i.e. it was created with its expires_in parameter set to 0) must be actively revoked to terminate its usage.
To revoke an access token:
- From the Administration module, select Identity and Access | Access Tokens.
- From the list, select an access token and click Revoke.
REST API
All management of access tokens is done via REST API through the endpoints described below.
Get Root Certificate
Receive public root certificate for the server
For details, refer to the JFrog Artifactory REST API documentation for Get Root Certificate
Create Token
Creates an access token.
For details, refer to the JFrog Artifactory 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 JFrog Artifactory REST API documentation for Refresh Token.
Revoke Token
Revoke an access token
For details, refer to the JFrog Artifactory REST API documentation for Revoke Token.
Get Service ID
Provides the service ID of an Artifactory instance or cluster
For details, refer to the JFrog Artifactory REST API documentation for Get Service ID.