Token Certificates
Token certificates are the key pair, comprised of the private and root certificates, which is used to sign and validate tokens. The private.key
is used to sign access tokens and the root.crt
is the matching public key, used to verify the token's signatures.
The root.crt
will disappear from the target's trusted folder and will be placed in the Artifactory database.
Resetting Token Certificates
Administrators can force Access to reset a token certificate.
To reset the token certificate:
- Create a file named
reset_root_keys
and place it under the<VAR>/bootstrap/etc/access/keys/ directory
. - Reset the Artifactory service.
Resetting the token certificate will effectively revoke all of the tokens that have been generated. If you want to reset your certificates but maintain the token that were created previously, you will need to copy the old root.crt
into the trusted directory: /var/etc/access/keys/trusted
.
Certificates in HA - Key Pair 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 do not 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 administrators, since non-admin users can only create tokens with themselves as the Subject.
Generating Expirable Tokens
Important
When creating a token, if the token expiry is set to a value smaller than the revocable-expiry-threshold
parameter specified in the Access YAML Configuration,
the token will be non-revocable. By default, the value of the revocable-expiry-threshold
parameter is set to 6 hours.
For example, if you set an expiry that is less than 6 hours, the token will not be revocable 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>
" parameter 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 set by the admin.
- From version 7.21.1, this can be specified by setting the
token.max-expiry
parameter in the$JFROG_HOME/artifactory/var/etc/artifactory/access.config.yml
file (prior to version 7.21.1, the parameter to set was artifactory.access.token.non.admin.max.expires.in). - If the
token.max-expiry
is equal to 0 (which is the default), there is no limitation to the token expiry. However, if the maximum expiry is greater than 0, the user cannot create a non-expirable token. - The
token.max-expiry
parameter must be set to a value higher than thetoken.default-expiry
parameter value.
Using the Revocable and Persistency Thresholds
Expirable tokens are affected by two configurable thresholds: the revocable expiry and persistency thresholds.
Revocable Expiry Threshold
The revocable-expiry-threshold
defines a token’s revocability according to its expiry. The threshold sets the minimal token expiry that defines a token as revocable, or the maximal token expiry that defines the token as non-revocable. The revocable-expiry-threshold
default value is set to 6 hours.
A token can have a lifespan that is defined by the expiry. If that expiry is set to a value smaller than the revocable-expiry-threshold parameter (see Settings below), the token will be non-revocable. If you set an expiry to be less than 6 hours, the token will not be revocable until it expires naturally. In addition, if the revocable-expiry-threshold
is set to a negative value, tokens with an expiration date might become non-revocable.
Special Cases
The following are special cases you will need to take into consideration:
revocable-expiry-threshold = 0
This means that all tokens are revocable.Important
Setting all the tokens to be revocable will affect the performance of the system, since all the tokens in the system will need to be checked directly with the database to validate that they were not revoked (including internal system ones). It is preferable to not lower this threshold to below 2 hours.
revocable-expiry-threshold = -1
This means that all tokens that have an expiration are non-revocable.persistency-expiry-threshold <= 0
This means that all tokens that have this setting are persistent.Important
Setting all the tokens to be persistent will affect the performance of the system, since all the tokens in the system will need to be checked directly with the database to validate that they are still persistent (including internal system ones). It is preferable to not lower this threshold to below 2 hours.
Setting the Revocable Expiry Threshold
The revocable-expiry-threshold
parameter is set in seconds and is specified in the Access YAML Configuration file. A token with an expiry (expirationTime-issuedAt
) below this value will not be revocable (tokens without an expiry are always revocable).
Persistency Threshold
The persistent-expiry-threshold
defines a token’s persistency by defining the minimal expiry value a token must have in order to be saved in the database. If the persistent-expiry-threshold
is set to a negative value, all tokens will be persistent and will be saved to the database.
The persistent-expiry-threshold
default value is set to 3 hours.
Setting the Persistency Threshold
The persistent-expiry-threshold
is set in seconds and is specified in the Access YAML Configuration file. A token with an expiry (expiry = expirationTime-issuedAt
) below this value will not be persisted.
Relationship Between the Two Thresholds
The relationship between the thresholds is defined as persistentExpiryThreshold <= revocableExpiryThreshold
and is validated in the Access configuration.
If both persistent-expiry-threshold
and revocable-expiry-threshold
are positive:
The persistent-expiry-threshold
MUST be smaller or equal to the revocable-expiry-threshold
(if the token is not saved in the database, it cannot be a revocable token).
This limitation is enforced in the code upon startup.
If the persistency threshold is higher than the revocable when Access starts, an error will be logged and the thresholds will be aligned to the same number as the revocable threshold.
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.
Disabling the Option to Create Refreshable Tokens
From version, 7.21.1, an admin can disable the option to create refreshable tokens by setting the parameter token.allow-refreshable
to false in the $
JFROG_HOME/artifactory/var/etc/artifactory/access.config.yml
file.
Grace Period for Extending an Expired Token
When a refreshable token expires, JFrog Access provides the user with a grace period that essentially extends the ability to refresh the token. This is done by using the parameter token.refresh-expiry
in the $
JFROG_HOME/artifactory/var/etc/artifactory/access.config.yml
file. The default setting for this parameter is 24 hours.
Limitation
The integration of SCIM ensures that an external user who has created a token will not be able to refresh the token if they have been removed from the external authentication server.
However, if your organization has not enabled SCIM, an external user who has created a token will still be able to refresh it even they have been removed; therefore, it is recommended to implement SCIM in your system.
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 User Management| Access Tokens screen | Generate Admin Token.
The services that appear in the screen above are only those services that are available in your JFrog Platform Deployment.
Generating Scoped Tokens
The User Management function of the Administration tab provides a centralized UI for managing Scoped Tokens, which are secure access tokens that provide limited and focused permissions. Scoped tokens range from identity tokens, which any user can create for themselves (see Identity Token), to tokens that provide admin access-level permissions.
In the Administration tab, go to User Management | Access Tokens.
You can now create two types of tokens: an Admin token (which provides a range of permissions) or a User token.
Viewing the Scope of a Token
From Artifactory release 7.46.3, you can see the scope of a token in the Access Tokens UI as a column called Scope.
Creating an Admin Scoped Token
- From the Token scope field, select Admin.
- In the User name field, enter the name of the Admin user.
- In the Service field, you can either select the checkbox All or clear the All checkbox and from the list that appears in the Service field, select the services you will the add to this user's token.
- In the Expiration time field, set the expiration time for the token (use one of the options in the field or set a custom expiration in hours).
- Click Generate to generate the token.
This displays the Generate Token window, which includes the username, scope, audience, expiration, token ID, and the actual token. To copy the token, click the copy icon next to it or simply click Copy.
Important
Tokens generated here are not stored in the JFrog Platform for security reasons; therefore, make sure you copy the token before closing this window. Once closed the token will not be available.
Creating an Admin Scoped Reference Token
From Artifactory release 7.38.4, you can choose whether to generate an extended token (as in the screen above), or to generate a Reference Token. The Reference Token is a "shortened," 128-character key, thereby providing an alias for longer token.
To support this option, the Generate Scoped Token UI includes an additional Create Reference Token checkbox.
- To create a Reference Token, verify that the checkbox is selected and click Generate.
This displays the Generate Token window, which includes the username, scope, audience, expiration, token ID, the full token and the Reference token. To copy either full token or the Reference token, use the copy icon next to the token.
Important
Tokens generated here are not stored in the JFrog Platform for security reasons; therefore, make sure you copy the token before closing this window. Once closed the token will not be available.
Creating a User Scoped Token
- From the Token scope field, select User.
- Click the Users field to display a dropdown list of Artifactory users and select a user, or type the name of the user in the field to locate that user.
- In the Service field, you can either select the checkbox All or clear the All checkbox and from the list that appears in the Service field, select the services you will the add to this user's token.
- In the Expiration time field, set the expiration time for the token (use one of the options in the field or set a custom expiration in hours).
- Click Generate to generate the token.
This displays the token window, which includes the Artifactory user's username, scope, audience, expiration, token ID, and the actual token, which you can copy by clicking Copy.
Generating Pairing Tokens
About Pairing Tokens
Available from Artifactory version 7.29.7, a pairing token manages connections, by establishing 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.
How do Pairing Tokens and Join Keys Differ?
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).
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.
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.
Supported Pairing Tokens
Pairing tokens enable you to connect between the following:
- Between your JFrog Platform Deployment (JPD) / edge and a remote JFrog Mission Control service. The subject of the token is the same as the subject of the principal who requested the pairing token.
- Between two JPDs (two Artifactory instances) that will be used to create a JFrog Cold Storage; in this case the pairing token that is generated will be used for the API binding process.
Pairing Tokens to Bind a JPD and a Mission Control Microservice
- In the Administration tab, go to User Management | 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.
Pairing Tokens to Set up Cold Storage (Using the API)
- In the Administration tab, go to User Management | Access Tokens | Pairing Token.
- In the Generate Pairing Token for field, select Cold Storage.
- 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.
- Next, use the token you generated above and follow the steps in Setting Up Cold Artifact Storage Using APIs.
Viewing and Revoking Tokens
Any token created with expiry greater than the revocable-expiry-threshold
parameter can be revoked using the Revoke Token by ID 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).
Since 7.21.1, access tokens are scoped tokens. Access to the REST API is always provided by default; in addition, you may specify the group memberships that the token provides. Administrators can set any scope, while non-admin users can only create Identity Tokens (user scope). See Access Token Structure for details.
A token with an expiry specified will lapse automatically upon reaching its expiry period.
A token that is not expirable (i.e., 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 User Management | Access Tokens.
- From the list, select an access token and click Revoke.
Access tokens support cross-instance authentication through a "circle of trust", which is established by sharing a public certificate among all participating instances. In essence, a circle of trust means that a service will verify access token signatures against all trusted certificates, including ones generated by other services and set as 'trusted' as part of the circle of trust. 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. A circle of trust is required when you have a series of JPDs that need to be accessed using a single set of credentials. For example, a single build agent that needs to upload and download from two JPD instances. By creating a circle of trust, you can ensure that one JPD instance will trust another instance’s tokens. This is achieved by sharing the public token certificate between all instances within the circle. Trusted certificates can be loaded and removed while the server is running, and do not require a restart. To establish a "Circle of Trust" between JFrog services, you will need to exchange the public token certificate between the services. Services that are within the circle of trust have complete admin privileges on each other. To exchange the certificates, you need to copy a service’s root certificate to another service’s The service's root certificate can be acquired in the following ways: The 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 service watches 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 Use the same Artifactory userid and groupid Make sure you give the same Artifactory To make the JFrog access tokens as secure as possible, there are a few pre-configured values that JFrog uses out-of-the-box that ensure that tokens are managed and can only be used for the right purposes: Limitations By default, only the issuing instance can refresh a token. For synchronizing tokens across services, see Access Federation.Circle of Trust (Cross-Instance Authentication)
Why do I Need a Circle of Trust?
How to Establish a Circle of Trust
$JFROG_HOME/artifactory/var/etc/access/keys/trusted
folder.$JFROG_HOME/artifactory/var/etc/access/keys/root.crt
(requires physical access to the server)root.crt
will disappear from the target's trusted folder and will be placed in the Artifactory database. $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.userid
and groupid
to the root certificate in the trusted folder ($ARTIFACTORY_HOME/access/etc/keys/trusted/*
) by comparing to the other files from the previous folder ($ARTIFACTORY_HOME/access/etc/keys/
).Security Restrictions
revocable-expiry-threshold
parameter set in the access.config.yaml
(you can see the default in the access.config.yaml). Be aware that this threshold has a special value "-1"; when set, all the tokens that have an expiry will be non-revocable. This setting is more comfortable to use in a Circle of Trust but it is less secure (as the expiry might be set for years).
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, which also includes the different types of scopes that can be assigned to the access token (for example, pairing tokens, etc.)
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
Revokes an access token by ID. For details, refer to the JFrog Artifactory REST API documentation for Revoke Token by ID.
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.