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

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

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

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
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.

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

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. You can include the --no-projects flag if you wish to refrain from selecting a project, or you can use the the dx select command to select a project automatically.

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

$ dx login --token --noprojects
$ dx login --token ; dx select project-xxxx
Selected project project-xxxx

Two-Factor Authentication

Two-Factor Authentication is an easy-to-use system that allows you to add an extra layer of security protecting the data stored on the DNAnexus platform.

After enabling Two-Factor Authentication, in addition to entering your username and password at login, you will also be required to enter a two-factor authentication code to access your account. This code is generated by a third-party two-factor authentication application (i.e. Google Authenticator) and is a time-based one-time password that will only be valid for that login session.

With Two-Factor Authentication protecting your account, your data will be protected even in the case that both your username and password are stolen. The attacker will be unable to access your account without your two-factor authentication code which is generated on your smartphone or computer.

Enabling two-factor authentication

To enable Two-Factor Authentication, go to your Profile page (top-righthand corner of the web platform) and at the bottom of the User Account tab in Security Settings you will see the option to turn on Two-Factor Authentication.

From there, you will need to acquire a third-party Time-based One-Time Password (TOTP) application, like Google Authenticator on smartphones, and link it to your DNAnexus account.

You can link the application using the QR code provided, or by manually entering the smart key into your application. The TOTP application will automatically generate an authentication code that changes periodically (every 30 seconds for Google Authenticator) which you will use in conjunction with your password to log into your account.

After sucessfully enabling Two-Factor Authentication, you will be redirected to a page containing back-up codes which can be used in place of an application-generated two-factor authentication code. We recommend you save these codes in a secure place in case you are unable to access your authentication application.

NOTE: We recommend using Google Authenticator on your mobile device. It's a popular, free solution available on Apple iOS and Android mobile devices. Get it on Google Play or from the Apple iTunes App Store.

We currently do not support sending authentication codes via text message (SMS). If you are unable to use a smart phone application, compatible Two-Factor Authentication Apps, which use the TOTP (Time-based One-time Password) algorithm, exist for other platforms. Let us know if you have a favorite app or other feedback about using this feature by contacting our support team.

Usage

Once Two-Factor Authentication is enabled on your account, you will be required to enter the application-generated two-factor authentication code in addition to your username and password at every login regardless if you are using the web platform or command-line interface. You will also be required to enter a code to change personal information.

Specifically, you will need a two-factor authentication code to do the following:

  • Access your account through DNAnexus web platform

  • Change your password

  • Change your user settings

  • Turn off Two-Factor Authentication

  • Login to your account using the DNAnexus Command Line Interface (CLI)

In the case you lose your phone or are otherwise unable to access your authenticator application, you can use the back-up codes provided when enabling Two-Factor Authentication to access your account. If this is not an option, please contact our support team for further assistance.

Disabling two-factor authentication

We highly recommend you protect the data you store on DNAnexus with Two-Factor Authentication. However, if you change your mind, you can always turn it off simply by going back to your Profile page and turning off Two-Factor Authentication on the User Account tab in Security Settings. You will be required to enter your password and your two-factor authentication code one more time to disable this feature.

NOTE: If you disable Two-Factor Authentication, then re-enable the feature, you will need to re-configure your TOTP application by scanning the new QR code or entering the new Secret Key. You will also be required to save the new back-up codes. The old back-up codes and codes generated by your previous application configuration will not be valid.