Skip to main content

Security Setup with User Tokens in Nexus Repository 2

Nexus Repository 2


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


When using Apache Maven with Nexus Repository Manager, the user credentials for accessing the repository manager have to be stored in clear text in the user’s settings.xml file. Maven has the ability to encrypt passwords in settings.xml, but the need for it to be reversible in order to be used limits its security. In addition, the general setup and use is cumbersome, and the potential need for regular changes due to strong security requirements e.g., with regular required password changes triggers the need for a simpler and more secure solution.

Other build systems use similar approaches and can benefit from the usage of User Token as well.

The User Token feature of Nexus Repository Manager Pro fills that need for Apache Maven as well as other build systems and users. It introduces a two-part token for the user, replacing the username and password with a user code and a pass code that allows no way of recovering the username and password from the user code and pass code values; yet can be used for authentication with the repository manager from the command line via Maven as well as in the UI.

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.

User token usage is integrated in the Maven settings template feature of Nexus Repository Manager Pro documented in Managing Maven Settings to further simplify its use.

Enabling and Resetting User Tokens

The user token-based authentication can be activated by an administrator or user with the role usertoken-admin or usertoken-all by accessing the User Token item in the Security submenu on the left-hand main menu.

Once user token is Enabled by activating the checkbox in the administration tab displayed in Figure 6.39, “User Token Administration Tab Panel” and pressing Save, the feature is activated and the additional section to Reset All User Tokens becomes available.


Figure 6.39. User Token Administration Tab Panel

Selecting the Protect Content feature configures the repository manager to require a user token for any access to the content URLs that includes all repositories and groups. This affects read access as well as write access e.g., for deployments from a build execution or a manual upload.

Activating User Token as a feature automatically adds the User Token Realm as a Selected Realm in the Security Settings section as displayed in Figure 6.40, “Selected Realms Server Security Settings with User Token Realm activated” and available in the Server section of the left-hand Administration menu. If desired, you can reorder the security realms used, although the default settings with the User Token Realm as a first realm is generally the desired setup. This realm is not removed when the User Token feature is disabled; however, it will cleanly pass through to the next realm and with the realm remaining any order changes stay persisted in case the feature is reactivated at a later stage.


Figure 6.40. Selected Realms Server Security Settings with User Token Realm activated

Besides resetting all user tokens, an administrator can reset the token of an individual user by selecting the User Token tab in the Users administration from the Security menu in the left-hand navigation displayed in Figure 6.41, “User Token Reset for Specific User in Security Users Administration”. The password requested for this action to proceed is the password for the currently logged in administrator resetting the token(s).


Figure 6.41. User Token Reset for Specific User in Security Users Administration


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

Accessing and Using Your User Tokens

With user token enabled, any user can access his/her individual tokens via their Profile panel. To access the panel, select Profile when clicking on the user name in the top right-hand corner of the user interface. Then select User Token in the drop-down to get access to the User Token screen in the Profile panel displayed in Figure 6.42, “User Token Panel for the Logged in Users in the Profile Section”.


Figure 6.42. User Token Panel for the Logged in Users in the Profile Section

In order to be able to see this User Token panel the user has to have the usertoken-basic role or the usertoken:current privilege. To access or reset the token you have to press the respective button in the panel and then provide your username and password in the dialog.

Resetting the token will show and automatically hide a dialog with a success message and accessing the token will show the dialog displayed in Figure 6.43, “Accessing the User Token Information”.


Figure 6.43. Accessing the User Token Information

The User Token dialog displays the user code and pass code tokens in separate fields in the top level section as well as a server section ready to be used in a Maven settings.xml file. When using the server section you simply have to 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 can be closed with the Close button.

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

With content protection enabled, command line access to the repository manager will require the tokens to be supplied. Access to e.g., the releases repository via:

curl -v --user admin:admin http://localhost:9081/content/repositories/releases/

has to be replaced with the usage of user code and pass code separated by colon in the curl command line like this:

curl -v --user HdeHuL4x:Y7ZH6ixZFdOVwNpRhaOV+phBISmipsfwVxPRUH1gkV09 http://localhost:9081/content/repositories/releases/

User token values can be accessed as part of the Maven settings template feature automating updates as documented in Managing Maven Settings.


The user tokens are created at first access whether that is by using the user interface or the Nexus Maven Plugin.

Configuring User Token Behavior

The user token feature is preconfigured with built-in parameters and no external configuration file is created by default. It is however possible to customize some behavior by creating a file sonatype-work/nexus/conf/

The following properties can be configured:


This parameter controls if username lookup is allowed when using a pass code. The default is set to true. If set to false, user code and pass code have to be used to authenticate, otherwise username and pass code is also possible. This would be the more secure setting.


With this value set to true (the default), any access to the repository manager content with content protection enabled will only be allowed to browser-based access even without credentials. Other tools like curl or wget or other command-line tools will be blocked. With the more secure setting of false , any access without correct codes will be disallowed.

The usertoken. prefix is optional when the properties are loaded from the file.