Login and Logout

Logging In on the Command Line

You can use the command line interface (CLI) to log in to the DNAnexus platform using the command dx login, at which point you will be prompted to select a project in which to work.

In the example below, the user "amy" has logged in and has 3 projects for which she has CONTRIBUTE or higher permissions. She can enter a number to select a project or press <ENTER> to work in the "SAM importer test" project. In this case, she has decided to work on "Scratch Project", so she enters "1".

$ dx login Acquiring credentials from https://auth.dnanexus.com Username: amy Password: Note: Use "dx select --level VIEW" or "dx select --public" to select from projects for which you only have VIEW permissions. Available projects (CONTRIBUTE or higher): 0) SAM importer test (CONTRIBUTE) 1) Scratch Project (ADMINISTER) 2) Mouse (ADMINISTER) Pick a numbered choice [2]: 1 Setting current project to: Scratch Project

Logging Out on the Command Line

You can log out using dx logout.

$ dx logout Deleting credentials from https://auth.dnanexus.com…

Please note that this command invalidates the authentication token used for the session, so if you used dx login --token <TOKEN> to log in and then use dx logout to log out, you will be unable to use <TOKEN> in future sessions.

Authentication Tokens

Generating an authentication token

You can log in without having to provide a username and password for a certain amount of time by using authentication tokens (henceforth referred to as tokens). Broadly, authentication tokens are generated by providing your username and password to the platform and specifying a time period for which the token may be used to log in.

WARNING ! If you provide your token to a third party, they may access the DNAnexus platform with your token, effectively impersonating you as a user. They will have the same access level as you for any projects to which the token has access, potentially allowing them to run jobs and incur charges to your account. Please keep your token safe and secure.

In order to generate a token, visit your DNAnexus profile on the web platform via the drop-down menu on the far right side of the web interface:

How to view your DNAnexus profile

Once at your profile, go to the “API Tokens” tab and click on the "New Token" button.

The New Token button

This sequence of actions will bring you to the "New Token" window.

The form with which one creates a new token

Fill out each field accordingly and select "Generate Token".

A pop-up will then appear saying “Your token has been generated. Please copy it for later use; for security purposes, this is the only time you will see it:” with a 32-character token comprised of letters and numbers in the line below. Copy down this token in a secure location and save it for later.

Some examples in which tokens might be used include the following:

  • Writing a script. Tokens can be helpful when writing scripts that require logging in to the platform. However, if you incorporate a token into a script, the token should only be valid for as long as the script requires access to the platform; the “Expiration Date” should be modified accordingly. Furthermore, the token should only be granted access to the projects required by the script. If your script uploads data to only one project, the “Token Scope" should reflect the limited access.
  • Logging in to the command line for interactive use. If your organization uses single sign-on and you cannot log in to the command line using a username and password, or if for any other reason you don’t wish to log in to the command line with your username and password, tokens are quite useful. This is the only scenario in which you should use a full-scope token, thereby allowing you to access all of your available projects. Otherwise, tokens should be scoped according to the access level required.

Logging in with an authentication token

In order to use a token to log in on the command line, you must use dx login with the --token flag. If Alice had logged in earlier using a token instead, this is what she would have seen.

$ dx login --token <TOKEN> Note: Use "dx select --level VIEW" or "dx select --public" to select from projects for which you only have VIEW permissions. Available projects (CONTRIBUTE or higher): 0) SAM importer test (CONTRIBUTE) 1) Scratch Project (ADMINISTER) 2) Mouse (ADMINISTER) Pick a numbered choice [2]: 1 Setting current project to: Scratch Project

Revoking authentication tokens

You must navigate to the “API tokens” tab of your profile in order to revoke a token. This process is described in the generating an authentication token section above.

Once in the “API tokens” tab, select which token you wish to revoke and then click the “Revoke” button:

’Revoking

Once you confirm that you wish to revoke the token, the token will be revoked.

Some examples in which tokens might be revoked include the following:

  • Token accidentally shared too widely. If more people have access to your token than you would like, revocation of the token will cut off access to your account by unwanted parties.
  • Token no longer needed. For example, if the script utilizing the token is no longer in use; or if the group granted access to the platform using the token no longer exist; or in any other instance in which the token is no longer necessary, you should revoke it to restrict access to your account.

Logging In Non-Interactively

The standard way of logging in on the CLI requires interaction with the terminal in order to both log in and select a project with which to work for the session. However, for scripts and other scenarios in which interacting with the terminal proves impractical, logging in non-interactively is possible.

In order to log in non-interactively, you must use dx login with the --token flag as well as the dx select command.

If Alice were to log in non-interactively, this is what she would see:

$ dx login --token <TOKEN> --noprojects; dx select project-xxxx Selected project project-xxxx

Last edited by Samantha Zarate, 2017-08-14 21:56:57

 Feedback