How to retrieve a user token from Nexus Repository Manager using REST

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

Retrieving a User Token For a Specific User Using REST

There are unsupported and subject to change REST APIs that can be used to get a user's user token, until NEXUS-12653 is officially implemented.

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

Step 1: Generate a single use access token

First 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 ):

  • NXRM 3.0.0+:/service/siesta/wonderland/authenticate
  • NXRM 2.7+ to latest 2.x version: /nexus/service/siesta/wonderland/authenticate
  • NXRM 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 ):

  • NXRM 3.24.0+: /service/rest/internal/current-user/user-token
  • NXRM 3.8.0 to 3.23.0 : /service/rest/usertoken/current
  • NXRM 3.0.0 to 3.7.0 : /service/siesta/usertoken/current
  • NXRM 2.7+: /nexus/service/siesta/usertoken/current
  • NXRM 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 value of the single use access token from the authenticate response. ie. /service/rest/internal/current-user/user-token?authToken=singleusetoken

"current" endpoints: When calling the current endpoint, you'll need to set a special Nexus 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:

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

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 an authenticated user A. In the UI, this is modelled by a dialog which 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"
}

NXRM 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:

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

NXRM 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 NXRM 2 here:

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

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

Have more questions? Submit a request

3 Comments

  • 0
    Avatar
    NGSA Vanguard

    A complete example using wget or curl would be very useful

  • 0
    Avatar
    Kumaresan (suspended)

    The command to get single token throws attached error. I have tried all the possibilities. Please advise

     

    Nexus version 2.11.4

     

  • 0
    Avatar
    Peter Lynch

    We are closing this article for comments.

    If you have a support license, please contact us by submitting a support ticket.

    If you do not have a support license, please use our Nexus Users List or our other free support resources.

Article is closed for comments.