Author: Or Gat

JFrog’s Legacy of API Keys

When JFrog introduced API Keys way back with JFrog Artifactory 4.4.3, the keys provided users with a practical solution to easily create a secret. This key could then be used instead of their password with JFrog Artifactory's REST API or through clients such as the JFrog CLI and package managers.

The reasoning behind the use of API Keys was based on security concerns: because users tended to re-use the same password for multiple applications, using application-specific credentials (credentials that would only work with JFrog products) was safer. This also worked for users who did not want to share their passwords with JFrog at all – for example when using SAML/OAuth for UI authentication.

However, despite their advantages, there are several security and usability constraints that API Keys do not cover. For that reason (and others) JFrog made the decision to deprecate the usage of API Keys and to introduce a new authentication mechanism – Reference Tokens.

So why did JFrog deprecate API Keys?

Although they’re easy to create and use, API Keys have some characteristics that make them less secure:

• API Keys are retrievable – the keys are saved in the database and can be retrieved via REST API or the UI.
• API Keys don’t have lifecycle management features – since API Keys are not created with an expiry date, and, by default, never expire, the user or Artifactory admin must manually revoke them. A single user can have a single active API Key at any moment – which means a single key needs to be shared with multiple clients. If it is revoked, it is revoked for all clients.
• API Keys are not manageable – administrators can not monitor or manage a user’s API Keys.

Introducing JFrog Access and Identity Tokens

JFrog’sAccess Tokensare standard JSON Web Tokens (JWTs) that provide flexibility and security by setting various token properties, which in turn control the token’s permissions, lifecycle, accessibility and more. You can read more about JFrog’saccess tokens here.

One type of Access Token is called anIdentity Token, which is an Access Token that is scoped (targeted) to a specific user’s permissions (their identity). Using an Identity Token is key to accessing the other types of tokens.

How to get an Identity Token in 3 steps:

Much like the old API keys, you can create an Identity token by going to the User Profile page:

1] Go to the Edit Profile menu in the top right corner of the Web UI
2] Select the "Generate an Identity Token" button
3] You now have a one-time chance to copy the token text

You can use this token to access the application in place of a password, just like an API key:

curl -u froggy:cm[...] http://localhost:8081/artifactory/api/system/ping

You may also use this token to generate Access Tokens. The Identity Token is key here, you have to use the Identity Token in an "Authorization: Bearer" header for security reasons:

curl - h“授权:无记名厘米(...]" -d "scope=applied-permissions/user" -XPOST -v http://localhost:8081/access/api/v1/tokens

{
"token_id" : "bbf4fc27-be5f-40d2-9b19-9181ea21900b",
"access_token" : "ey[...]",
"expires_in" : 31536000,
"scope" : "applied-permissions/user",
"token_type" : "Bearer"
}

Artifactory Administrators may generate tokens for other users, or create transient users, but they too are limited to using Identity or Admin Tokens to do so:

curl - h“授权:无记名厘米(... Admin ID Token ...]" -X POST -d "username=froggy-pipeline" -d "scope=applied-permissions/groups:readers"
http://localhost:8082/access/api/v1/tokens

{
"token_id" : "58f781d5-f59d-4f7c-972c-d78e4018c4ec",
"access_token" : "eyJ[...]bA",
"scope" : "applied-permissions/groups:readers",
"token_type" : "Bearer"
}

What makes Identity Tokens useful?

Because Access Tokens can be created with different scopes, with Identity Tokens, this means that you can set the Access Token’sscopeproperty to “applied-permissions/user”.

For example, if you create a token with “scope=applied-permissions/user” and “subject=User1”, you’ve created an Identity token for User1. This means you’ve granted the token User1’s permissions as they are defined in the Platform by JFrog’s roles and permissions function. When a user generates a token via their Profile page in the JFrog Platform WebUI, the generated token is always an Identity Token (scoped to the permissions of the logged-in user).

Because JFrog’s Access tokens are standard JWTs, as such they can be quite long – since they contain the token’s properties (scope, subject and others), as well as additional information used to validate the token.In fact, the sheer length of the token can create compatibility issues with various clients trying to authenticate with the JFrog platform. Moreover, some clients might not even support bearer token authentication (Authorization: Bearer ).To mitigate these length limitations, JFrog introduced the参考标记.

What is a Reference Token?

一个参考标记只是短字符串字符acters that refers to an actual token.
To obtain a Reference Token, users can request the token using the create-token request API, by setting the “include_reference_token” parameter to true. They can also use the JFrog Platform WebUI Profile page to generate this token.

Note:When creating the token via the user’s Profile page, this parameter is always set to true, and the resulting UI generated token isalways a Reference Token.

The reference token can then be used to authenticate with the JFrog platform as a bearer token, similarly to an API Key (with the JFrog API Key header), or even as alternative basic credentials.

Why should I use Reference Tokens?

Unlike API Keys, Reference Tokens are a more secure way to manage user authentication because they “inherit” the security features of Access Tokens.

Here are some additional advantages of the new Reference Tokens:

• 参考标记s are not retrievable – Reference Tokens are stored as hashed, so they are not retrievable from the UI, REST API, or database, making them less likely to be compromised.
• 参考标记s can have a default expiry – the Artifactory administrator can set a default expiry for Reference Tokens. They can also control the default expiry time and decide whether a token will be refreshable or not.
• A user can have multiple Reference Tokens – unlike API Keys, a user can create numerous Reference Tokens
• Reference tokens information can be viewed and the token can be revoked via the JFrog Platform UI – both for the user and the administrators.
• 参考标记s can be used in multiple ways – Reference Tokens can be used similarly to API Keys, with the “X-JFrog-Art-Api” Header, but also as Basic credentials with “curl -u User1:” or as bearer tokens “curl -H Authorization: Bearer ”.
• 参考标记s are short (64 characters) – unlike Identity Tokens, Reference Tokens can be used with clients that don’t support long tokens/passwords

How can I prepare for the migration away from API Keys?

Think of the migration away from API Keys in the way you’re required to update your password. The process is quick and easy, and can be done by any user – you don’t need to request your admin’s assistance.

For the short term – and to make the migration to Reference Tokens smoother – you’ll be able to continue to use API Keys. In an upcoming JFrog Platform version, we’ll add an option that will enable administrators to log every request’s authentication method, which will allow the administrator to see which users are using API Keys for their authentication.

Of course, if you wish to disable the creation of new API Keyspriorto the official JFrog deprecation, do the following:In “$JFROG_HOME/artifactory/var/data/artifactory/artifactory.properties”,
set the property “artifactory.security.apiKey.blockCreate” to true.