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

Search





Overview

JFrog Access provides JFrog Products with access tokens as a flexible means of authentication with a wide range of capabilities:

  • Cross-instance authentication
    Access tokens can be used for authentication, not only by the instance or cluster where they were created, but also for other instances and clusters that are all part of the same "circle of trust" (described below).
     
  • User and non-user authentication
    The case for authenticating users is clear, however access tokens can also be assigned to non-user entities such as CI server jobs.

  • Time-based access control 
    Access tokens have an expiry period so you can control the period of time for which you grant access. However, you may also delegate that control to the receiving user by making them refreshable

  • Flexible scope 
    By assigning Groups to tokens, you can control the level of access they provide.

  • Pairing tokens
    Manage connections between different JFrog microservices.

Access Token Structure

An access token has the following properties:

Subject
The user to which this access token is associated. If the user specified does not exist, the system will create a corresponding transient user. Administrators can assign a token to any subject (user); non-admin users who create tokens can only assign tokens to themselves.
Scope

Since 7.21.1, access tokens are scoped tokensAccess 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 set the scope to a subset of the groups to which they belong.

The supported scopes include:

  • applied-permissions/user - provides user access. If left at the default setting, the token will be created with the user-identity scope, which allows users to identify themselves in the Platform but does not grant any specific access permissions.
  • applied-permissions/admin - the scope assigned to admin users.
  • applied-permissions/groups - this scope assigns permissions to groups using the following format: applied-permissions/groups:<group-name>[,<group-name>...]
  • system:metrics:r - for getting the service metrics
  • system:livelogs:r - for getting the service livelogsr

Note: The scope to assign to the token should be provided as a space-separated list of scope tokens, limited to 500 characters.

Audience
The set of instances or clusters on which the token may be used identified by their Service IDs. The Service ID is a unique, internally generated identifier of a JFrog service or cluster and, in the case of Artifactory, is obtained through Get Service ID REST API endpoint.
Issuer
An identifier of the cluster on which the access token was created
Expiry
The date and time when the token will expire. 
Issued At
The date and time when the token was created.
ID
The token ID

Access tokens are managed either through REST API, as described below, or through the JFrog Platform Access Token UI. 

Page Contents


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:

  1. Create a file named reset_root_keys and place it under the <VAR>/bootstrap/etc/.access/keys/ directory.
  2. 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.cert 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

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 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 21600, 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/access.config.yml file (default: 3600).

Note: The artifactory.access.token.non.admin.max.expires.in parameter cannot be set to a value higher than the artifactory.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

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 Identity and Access | Access Tokens screen | Generate Admin Token.

The services that appear in the screen are only those services that you added.


Generating Scoped and Pairing Tokens

The Identity and Access function of the Administration tab provides a centralized UI for managing the tokens in your system, which include two types of tokens: Scoped Tokens (which manage access) and Pairing Tokens (which manage connections).

Scoped Tokens

Scoped tokens are secure access tokens that provide limited and focused permissions. Scoped tokens range from identity tokens, which any user can create for themselves, to tokens that provide admin access-level permissions.

Setting up Scoped Tokens

In the Administration tab, go to Identity and Access | Access Tokens.

You can now create two types of tokens: an Admin token (which provides a range of permissions) or a User token.

Creating an Admin Scoped Token
  1. From the Token scope field, select Admin.
  2. In the User name field, enter the name of the Admin user.
  3. 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.
  4. 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).
  5. Click Generate to generate the token.
    This displays the token window, which includes the username, scope, audience, expiration, token ID, and the actual token, which you can copy by clicking Copy.
Creating a User Scoped Token
  1. From the Token scope field, select User.
  2. 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.
  3. 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.
  4. 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).
  5. 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.

Pairing Tokens

Available from Artifactory version 7.29.7.

A pairing 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). 

Supported Pairings

Pairing tokens enable you to connect between the following services in the JFrog Platform:

  • Mission Control: Pair between your JFrog Platform Deployment (JPD) / edge and a remote JFrog Mission Control service
  • Cold StoragePair between your cold Artifactory instance and a remote Live Artifactory instance

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.

Setting up Pairing Tokens

  1. In the Administration tab, go to Identity and Access | Access Tokens | Pairing Token.
  2. In the Generate Pairing Token for field, select the purpose of the pairing token:
    • Mission Control (for JPDs)
    • Cold Storage (for Cold Storage Artifacts; this will only appear if you have a Cold Artifact instance set up - see Setting Up Cold Artifact Storage)
    • And more
  3. 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.

Viewing and Revoking Tokens

Any token created with expiry greater than the revocable-expiry-threshold 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:

  1. From the Administration module, select Identity and Access | Access Tokens.
  2. From the list, select an access token and click Revoke.


Circle of Trust (Cross-Instance Authentication)

Access tokens support cross-instance authentication through a "circle of trust", which is 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.

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. 

Trusted certificates can be loaded and removed while the server is running, and do not require a restart.  

Limitations

Access will check for a token's revocation based on the revocable-expiry-threshold 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 synchronizing tokens across services, see Access Federation.

Cross instance authentication

Establishing a Circle of Trust

One way of establishing trust between services is to establish a "Circle of Trust" between JFrog services by exchanging public certificates 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 $JFROG_HOME/artifactory/var/etc/access/keys/trusted folder.

The service's root certificate can be acquired in the following ways:

The root.crt will disappear from the target's trusted folder and will be placed in the Artifactory database. 

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.



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


Copyright © 2022 JFrog Ltd.