User Tokens

Only available in Sonatype Nexus Repository Pro. Interested in a free trial? Start here.

When using Apache Maven with Nexus Repository Manager Pro, the user credentials for accessing the repository manager have to be stored in the user’s settings.xml file. Like a pom.xml, your settings.xml is file that contains your user preferences. The Maven framework has the ability to encrypt passwords within the settings.xml, but the need for it to be reversible in order to be used limits its security. 

The default location of settings file is ~/.m2/settings.xml. This file contains listings for personalized client or build-tool configurations such as repositories. This file is not exclusive to Maven-specific repositories.

Other build systems use similar approaches and can benefit from the usage of user tokens as well. Nexus Repository Manager Pro’s user token feature establishes a two-part token for the user. Usage of the token acts as a substitute method for authentication that would normally require passing your username and password in plain text.

This is especially useful for scenarios where single sign-on solutions like LDAP are used for authentication against the repository manager and other systems and the plain text username and password cannot be stored in the settings.xml following security policies. In this scenario the generated user tokens can be used instead.

Enabling and Resetting User Tokens

User token-based authentication can be activated by an administrator or user with the nx-usertoken-settings privilege. Navigate to Administration → Security → User Token. 

Check the Enable user tokens box.

Select Save to activate the feature.

Additionally, you can check the Require user tokens for repository authentication box to allow the repository manager to require a user token for any access to the repository and group content URLs. This affects read and write access for deployments from a build execution or a manual upload, but the user interface will not change. Non-content operations, such as logging into Docker with plain-text credentials, are still accessible, although subsequent requests for images after logging in will fail.

You can also reset the token of an individual user by selecting the User Token tab in the Users administration from the Security menu. The password requested for the action to proceed is the password for the authenticated administrator who resets the token. A non-administrator also needs the nx-usertoken-users privilege to do this.

Resetting user tokens forces users to update the settings.xml with the newly created tokens, and could potentially break any command line builds using the tokens until this change is carried out. This also applies to continuous integration servers using user tokens or any other automated build executions.

Set Up User Tokens in Realms

When you activate user tokens, the feature automatically adds the User Token Realm to the Active Realms list. To see the results, go to Realms located under Security in the Administration menu. If desired, you can re-order the security realms used, although the default settings with the User Token Realm as the first realm is probably the desired setup. This realm is not removed when the user tokens are disabled; however, it will cleanly pass through to the next realm. The realm will remain in the active bin in your Realms in case the feature is reactivated at a later stage.

Generating and Using Your User Token

User tokens are generated the first time they are accessed. A user needs the nx-usertoken-current privilege to access their user tokens.

Permissions for Accessing User Token

To grant users the ability to access user tokens, do the following:

  1. Select Roles from Security in the Administration menu.
  2. Choose a role you want to assign the permission, from the selection panel.
  3. Assign the nx-usertoken-current privilege to the role, then save the change.

When enabled, the user can access their individual token from the mode toggle.

Accessing and Generating the User Token

User tokens are generated the first time they are accessed. To access the User Tokens menu follow these steps:

  1. Select your username on top right area of the main toolbar.
  2. In the left-hand navigation panel, select the User Token tab.
  3. Select the Access user token button.
  4. In the resulting dialog, re-enter your credentials and select Authenticate.

Another dialog will appear with the user token.

Resetting Your User Token

  1. Select your username on top right area of the main toolbar.
  2. In the left-hand navigation panel, select the User Token tab.
  3. Select the Reset user token button.
  4. In the resulting dialog, re-enter your credentials and select Authenticate.

This will invalidate your previous user token; however, you will need to generate a new one if you require a new user token. To generate a new user token, select the Access user token button, re-enter your credentials in the resulting dialog, and select Authenticate. Another dialog will appear with the user token.

Using the User Token

When you select the Access user token button and go through the process of generating the user token, a dialog like the one below displays your user token:

Note that the dialog will close automatically after one minute.

example user token dialog

User Token Name and Pass Codes

Your user token name and pass codes display in separate fields. You can use these as replacements for username and password in the login dialog; you can also still use your original username and password to log into the user interface.

Server Section for Maven settings.xml

We also provide information for the server section of your Maven settings.xml. Note that you will need to replace ${server} with the repository id that references your Sonatype Nexus Repository instance against which you want to authenticate with your user token.

base64 Representation

Another field provides a base64 representation of "user:password."

Note for npm: The npm client login has a limitation of [a-z0-9] characters for the username while Sonatype Nexus Repository user tokens can include any characters that are available with base64 encoding. This will result in an error if you attempt to authenticate with npm using your user token name. To get around this, place the base64 representation of "user:password" directly in your .npmrc file.

Use User Token for Repository Authentication

In order to utilize your user tokens for repository authentication you must access Sonatype Nexus Repository with the user token from the command line. For example, you would access with your username and password using a comand like the following: 

curl -v --user {username}:{password} http://localhost:2468/repository/bower-all/

You can replace those credentials with the user and pass code separated by a colon in the curl command line like this:

curl -v --user {token name code}:{token pass code} http://localhost:2468/repository/bower-all/