Repository Management with Nexus

6.17. Security Setup with User Tokens

6.17.1. Introduction

When using Apache Maven with Nexus, the user credentials for accessing Nexus have to be stored in clear text in the user’s settings.xml file. Maven has the ability to encrypt passwords in setting.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 system use similar approaches and can benefit from the usage of User Token as well.

The User Token feature of Nexus 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 Nexus from the command line e.g. 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 Nexus and other systems and the plain text username and password can not 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 documented in Chapter 13, Managing Maven Settings to further simplify its use.

6.17.2. Enabling and Resetting User Tokens

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

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

figs/web/config-user-token-main.png

Figure 6.41. User Token Administration Tab Panel


Selecting the Protect Content feature configures Nexus to require a user token for any access to the content urls of Nexus, which includes all repositories and groups. This affects read access as well as write access for example for deployments from a build execution.

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.42, “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 probably 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.

figs/web/config-user-token-security-settings.png

Figure 6.42. 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.43, “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)

figs/web/config-user-token-user-reset.png

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


Warning

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.

6.17.3. Accessing and Using Your User Tokens

With User Token enabled, any user can access their 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 Nexus 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.44, “User Token Panel for the Logged in Users in the Profile Section”.

figs/web/config-user-token-profile.png

Figure 6.44. 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-user 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.45, “Accessing the User Token Information”.

figs/web/config-user-token-access.png

Figure 6.45. 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 Nexus server 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 for Nexus. It is also possible to use the original username and the pass code to log in to Nexus.

With content protection enabled command line access to Nexus 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 Chapter 13, Managing Maven Settings.

Note

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

6.17.4. Configuring User Token Behaviour

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 behaviour by creating a file sonatype-work/nexus/conf/usertoken.properties'.

The following properties can be configured:

usertoken.userTokenServiceImpl.allowLookupByUserName
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 authenticated, otherwise username and pass code is also possible. This would be the more secure setting.
usertoken.userTokenServiceImpl.restrictByUserAgent
With this value set to true, which is the default, any access to the Nexus content with content protection enabled will only be allowed to web 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 usertoken.properties file.