How to retrieve a user token from Nexus Repository using REST

Visit my.sonatype.com for documentation on Nexus Repository version 2.

To address security concerns of exposing a user's company login information, Nexus Repository Professional includes a  "User Token" authentication method.

Retrieving a User Token For a Specific User Using REST

These instructions describe unsupported and subject-to-change REST APIs that can be used to get a user token, until the functionality is officially implemented.

First, make sure the User Token feature is enabled in Nexus Repository. Then, it takes two steps to get a user's token via REST.

Step 1: Generate a single-use access token

You need to generate a single-use access token to gain access to the REST resource which will return the User Token for the user.

Send a POST request with the regular username and password Basic Authorization headers and base64 encoded payload values, to one of these endpoints ( default webapp context is included ):

• Nexus Repository 3.8.0+:/service/rest/wonderland/authenticate
• Nexus Repository 3.0.0+:/service/siesta/wonderland/authenticate
• Nexus Repository 2.7+ to latest 2.x version: /nexus/service/siesta/wonderland/authenticate
• Nexus Repository 2.0-2.6x: /nexus/service/local/usertoken/authenticate

Single-use tokens are only valid for a maximum of 20 seconds by default. This means the next request to retrieve the user token must be accessed within 20 seconds from obtaining the single-use token.

Step 2: Retrieve the User Token

Once you get the single-use access token from the response, make a GET request which includes Basic Authentication headers, to fetch the actual "User Token" value ( default webapp context is included ):

• Nexus Repository 3.24.0+: /service/rest/internal/current-user/user-token
• Nexus Repository 3.8.0 to 3.23.0 : /service/rest/usertoken/current
• Nexus Repository 3.0.0 to 3.7.0 : /service/siesta/usertoken/current
• Nexus Repository 2.7+: /nexus/service/siesta/usertoken/current
• Nexus Repository 2.0-2.6x: /nexus/service/local/usertoken/current

"user-token" endpoint: When calling the "user-token" endpoint, a query parameter "authToken" should be appended to the URL with the base64 encoded value of the single-use access token from the authenticate response. ie. /service/rest/internal/current-user/user-token?authToken=base64encoded_singleusetoken

"usertoken/current" endpoints: When calling the current endpoint, you'll need to set a special Nexus Repository-specific header as part of the GET request. The header value is the single-use access token from the authenticate response. The header name is:

• Nexus Repository 3.0.0-3.23.0: X-NX-AuthTicket
• Nexus Repository 2.7+: X-NX-AuthTicket
• Nexus Repository 2.0-2.6.x: X-NX-UserToken-AuthTicket

Sample Bash Script

Sonatype has created an example bash shell script that demonstrates how to programmatically fetch your user token from any version of Nexus Repository.

Download fetch_user_token.sh 

Why must Basic Authentication credentials be provided which match the payload credentials?

The authenticate resource will return a 400 HTTP status code if the Basic Authentication credential username does not match the decoded payload username.

The reasoning is that an access token for user A should only be issued to authenticated user A. In the UI, this is modeled by a dialog that prompts for credential verification before exposing a user token.

After an access token is issued, it represents the principal and so the basic authentication prevents impersonating another user with an access token.

Example Using Curl

First base64 encode the user ID and password using the "base64" command line tool:

> echo -n "admin" | openssl base64
YWRtaW4=
> echo -n "admin123" | openssl base64
YWRtaW4xMjM=

Then get a single-use token for admin user using POST data and Basic Authentication:

> curl -H "Accept: application/json" -H "Content-Type: application/json" --data '{"u":"YWRtaW4=","p":"YWRtaW4xMjM="}' -u admin:admin123 http://localhost:8081/nexus/service/siesta/wonderland/authenticate
{
  "t" : "gnwEA5/maPV3sGYrROcqISmbL2+/YzMwADHIshNxB+7sPnHy6dTpE8Isolv3f4PSOxiiNwPWmVdCqpFPBNsJiX4I"
}

Nexus Repository 2: Use the single-use token in a special header to GET the current user token using Basic Authentication for the same user in the first request:

> curl -H "Accept: application/json" -H "Content-Type: application/json" -H "X-NX-AuthTicket: gnwEA5/maPV3sGYrROcqISmbL2+/YzMwADHIshNxB+7sPnHy6dTpE8Isolv3f4PSOxiiNwPWmVdCqpFPBNsJiX4I" -u admin:admin123 http://localhost:8081/nexus/service/siesta/usertoken/current
{
  "nameCode" : "8I034iTW",
  "passCode" : "EraLxqQei3DO9fjcTTAO9fvKU9t7EaliZIzjolDnAv37",
  "created" : "2014-01-28T17:17:07.701+0000"
}

Additional Resources

User Token concepts are explained in our help documentation:

Nexus Repository 3: https://help.sonatype.com/repomanager3/system-configuration/user-authentication/authentication-via-remote-user-token

Nexus Repository 2: https://help.sonatype.com/repomanager2/configuration/security-setup-with-user-tokens

You can find more information about how to use the REST API in Nexus Repository here:

Nexus Repository 3: https://help.sonatype.com/repomanager3/rest-and-integration-api

Nexus Repository 2: https://blog.sonatype.com/learn-the-nexus-rest-api-automating-sonatype-nexus