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.

Accessing and Using Your User Token

To grant users the ability to access user tokens:

  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. To access the menu select the username, on the top right area of the main toolbar. In the User menu, to the left, the user will see the User Token menu item.

In order to see the User Token click the Access user token button. This will prompt the Authenticate dialog where you are required to re-enter your credentials. After clicking Authenticate in the completed dialog, another dialog will appear with the user token.

Below the Access your token section is another section that allows you to reset your token. Click the Reset user token button, which prompts an Authenticate dialog. Enter your credentials to complete the user token reset. Resetting the token will show a dialog with a success message, but you must access the user token again to see the new value.

The User Token dialog displays user code and pass code tokens in separate fields. Below the token, is the server section of your settings.xml. When using the server section you can replace the ${server} placeholder with the repository id that references your repository manager you want to authenticate against with the user token. The dialog will close automatically after one minute or simply click the Close button.

The user code and pass code values can be used as replacements for username and password in the login dialog. You can still to use the original username and the pass code to log in to the user interface.

In order to utilize your user tokens for repository authentication you must access the repository manager with the user token, from the command line. For example, your username-password credentials access with:

curl -v --user admin:admin123 http://localhost:2468/repository/bower-all/

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

curl -v --user N+ZBiTlF:76xSi+HAQvYHZH8kgyJldWD7aJnPgCrHG/Zu7mkpWmZZ http://localhost:2468/repository/bower-all/