Authentication

DNAnexus uses OAuth2 authentication, and (unless otherwise noted) API calls are considered protected resources to which requests need to be authenticated. Clients must make authenticated requests with a "bearer token" using the "Authorization" request header field with the "Bearer" HTTP authorization scheme, like in the following example:

Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw

For the purposes of new user account creation, interactive logins, and user account password management, DNAnexus maintains a server called the Authentication Server, which is separate from the API server. The Authentication Server is responsible for web-based interaction that all users must go through in order to create their accounts, generate initial tokens, or manage their password.

Bearer tokens are generated in three different ways:

1. Initial tokens are generated when a user "logs in" interactively, i.e. when an application acting on behalf of the user (referred to here as "client") redirects the user to the Authentication Server login page as part of the authorization protocol described in the OAuth2 specification (http://tools.ietf.org/html/draft-ietf-oauth-v2). This requires the user to provide their access credentials (username and password) to the Authentication Server. The following is a summary of the authentication workflow as described in section 4.1 of the OAuth2 spec (known as "Authorization Code Grant"):

   • The client directs the user agent to the authorization endpoint URI:

     https://auth.dnanexus.com/oauth2/authorize

     extended with the following parameters in the query (section 4.1.1 of the OAuth2 spec):

     • response_type: Must be set to the value "code"

     • client_id: This is a fixed string identifying the client. Currently it must be set to apiserver. In the future, a client authentication scheme will be introduced.

     • redirect_uri: Must be set to an HTTP server URI served by the client.

   • The user agent is presented with an interactive login prompt and needs to successfully provide their credentials.

   • The Authentication Server causes the user agent to contact the redirect_uri URI extended with the query parameter "code" (or responds with an error, per section 4.1.2 of the OAuth2 spec). This is the authorization code required to obtain the authentication token.

   • The client obtains the token by performing a POST request to the token endpoint URI:

     https://auth.dnanexus.com/oauth2/token

     with the following parameters in the request entity-body (section 4.1.3 of the OAuth2 spec):

     • grant_type: Must be set to the value authorization_code

     • code: Must be set to the code received in the previous step.

     • redirect_uri: Must be set to the same value as the one provided in the first step.

   • The body of the response contains a JSON-encoded hash: the key access_token is set to the token, and the key token_type is set to bearer. For more information, consult sections 4.1.4, 5.1 and 5.2 of the OAuth2 spec.

   Note: If you're developing a website that uses DNAnexus authentication, you must register your client (specifically, its client_id and redirect_uri) with us. Email us for registration info. http://dnanexus.github.io/oauth2-demo/ for a code sample using this API.

2. Additional tokens (API keys) can be generated and managed by visiting the DNAnexus platform web interface (click on the user name, open "Profile", and click on "API Tokens" to access this interface).

3. A job launched within the Execution Environment will be provided with its own token. This token is derived internally by the platform from the original token obtained with method 1.