User Tokens in Sonatype Nexus Repository
This topic covers how to use user tokens for user authentication in Sonatype Nexus Repository Pro.
Note
Only available in Sonatype Nexus Repository Pro. Interested in a free trial? Start here.
Nexus Repository Pro’s user token feature establishes a two-part token for a user that the user can then use instead of providing a plain text username and password for authentication. User tokens provided added security beyond what reversible encryption provides and are especially useful when using single sign-on solutions like LDAP for authentication.
For example, when using Apache Maven with Nexus Repository Pro, user credentials for accessing the repository manager must be stored in the user’s settings.xml file. While the Maven framework can encrypt passwords within the settings.xml, it must be reversible in order to be used, which results in limited security. Other build systems use similar approaches and can also benefit from using user tokens.
Note that, by default, the settings.xml file is available under ~/.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.
Administrators or users with at least the nx-usertoken-settings privilege can activate user token-based authentication under Administration → Security → User Token in the Sonatype Nexus Repository Pro user interface.
Considerations for Enabling User Token Expiration in an Existing Deployment
If enabling User Token Expiration on an existing deployment, the configured expiration settings will apply to existing user tokens as well as newly created ones. The start date for Nexus Repository to calculate whether a given token should be considered expired is based on token creation date. (E.g., if Token X was created 365 days ago and your setting expires tokens after 100 days, then Token X will be considered expired upon enabling the User Token Expiration feature.)
Select the Enable box under the User Tokens section to enable user token-based authentication
If desired, select the Enable box under Require User Tokens for Repository Authentication to have Nexus Repository require a user token for any access to repositories and group content URLs.
Requiring user tokens for repository authentication affects both read and write access related to build execution or manual upload; however, the user interface does not change.
Non-content operations (e.g., logging into Docker with plain-text credentials) are still accessible even when the Require user tokens for repository authentication box is checked; however, subsequent requests for images after logging in will fail.
Note
Require user tokens for repository authentication does not work with Docker repositories if the Allow anonymous Docker pull configuration is enabled.
If desired, select the Enable box under User Token Expiration; then, under User Token Expiry, enter the number of days for which you want user tokens to remain valid. This defaults to 30 days, but you can set this field to anything between 1-999 days. (New in 3.69.0)
Select Save.
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.
User Token Realm
When you enable user token-based authentication, Sonatype Nexus Repository automatically adds and activates the User Token Realm.
By default, the User Token Realm will appear at the top of your list of active realms; this means that user tokens will be given first priority for granting user access in the event of a name clash between authentication realms.
If you disable user token-based authentication, Nexus Repository will not remove or deactivate the User Token Realm; however, it will cleanly pass over this realm to the next one in the active realms list.
For full information about authentication realms, see our Realms help topic.
Administrators or users with at least the nx-usertoken-users privilege can reset either an individual or all user tokens.
Warning
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.
To reset all user tokens, navigate to Administration → Security → User Token in the Sonatype Nexus Repository Pro user interface. Then, take the following actions:
Select the Reset all user tokens button at the bottom of the user tokens configuration screen.
In the confirmation modal, type "Reset all user tokens" in the Verify Reset text box to confirm that you want to proceed.
Select the Reset User Tokens button to complete the action.
To reset an individual user token, navigate to Administration → Users, and take the following actions:
From the user list, select the individual user whose user token you wish to reset.
Select the User Token tab from that individual user's settings.
In the Authenticate modal that appears, enter your own password (i.e., the password of the authenticated administrator who is resetting the user token).
Select the Authenticate button.
Sonatype Nexus Repository generates user tokens the first time that a user accesses the token. Users need the nx-usertoken-current privilege to access their user tokens. For details on granting privileges, see our Privileges help topic.
Sonatype Nexus Repository generates user tokens the first time that a user accesses the token. To access the User Tokens menu, follow these steps:
Select your username on top right area of the main toolbar to manage your account.
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 containing your user token information; note that the dialog closes automatically after 1 minute.
 |
Your user token dialog contains the following information:
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
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.
In order to use your user tokens for repository authentication, you must access Sonatype Nexus Repository with the user token from the command line. You would do this with a username and password by using a command like the following:
curl -v --user {username}:{password} http://localhost:2468/repository/bower-all/To use your user token, replace username and password with your user token name and passcode separated by a colon in the curl command line:
curl -v --user {token name code}:{token pass code} http://localhost:2468/repository/bower-all/Resetting your user token will invalidate your previous one. If you need a new user token, you will then need to generate a new one as detailed in Accessing and Generating Your User Token. To reset your user token, take the following 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 Reset user token button.
In the resulting dialog, re-enter your credentials and select Authenticate.
If an administrator has configured user token expiration as explained in Enabling User Tokens, you can view the time remaining until your user token expires:
Select your username on top right area of the main toolbar to manage your account.
In the left-hand navigation panel, select the User Token tab.
Locate the User Token Status section, which provides the date and time when your user token is set to expire.
If your token has already expired, you will see that the status is set to "Expired," and a warning box will appear letting you know that you must select the Generate User Token button to generate a new user token.