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:
- Select Roles from Security in the Administration menu.
- Choose a role you want to assign the permission, from the selection panel.
- 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:
- Select your username on top right area of the main toolbar.
- In the left-hand navigation panel, select the User Token tab.
- Select the Access user token button.
- In the resulting dialog, re-enter your credentials and select Authenticate.
Another dialog will appear with the user token.
Resetting Your User Token
- Select your username on top right area of the main toolbar.
- In the left-hand navigation panel, select the User Token tab.
- Select the Reset user token button.
- 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.
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."
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/