Enabling Web Application Users to Log In with DNAnexus Credentials

Learn how to configure your app to allow app users to log in using DNAnexus credentials.

If you're the developer of a web app that will be used by DNAnexus Platform users, you can enable them to log in, easily and securely, using their Platform credentials, via the DNAnexus OIDC service. This page provides a step by step guide to configuring your app to enable OIDC login, and registering it with DNAnexus as an OIDC client.

For a sample app illustrating how this is done, see this DNAnexus-maintained Github repo.

Configuring Your Web-Based Application to Allow Login with DNAnexus Credentials

Prerequisites

To enable user login with DNAnexus credentials, your application must be web-based. That is, it must allow users to log in and access its functionality via a web interface. Your application must also have a privacy policy and terms of service document that are both web-accessible. You must also supply a JSON Web Key Set (JWKS) endpoint URL, to support JWT encryption of the required ID token.

Step 1. Register Your App with DNAnexus and Obtain a Client ID

As a first step, you must register your app with DNAnexus. To do this, email DNAnexus Support, including the following specifications in your email:

• client_name string The name of the app that is to be configured as an OIDC client.

• author_id string The DNAnexus Platform user ID of the user who will be able to set and reset the app's client secret

Only one user can be designated as an app's author.

• redirect_uris array of strings A list of one or more URLs to which user authorization requests will be directed. All must use the HTTPS protocol

• homepage_uri string The URL of the page used to access and use the app

• policy_uri string The URL of the app's privacy policy document

• tos_uri string The URL of the app's terms of service document

• jwks_uri string The URL of the app's JWKS (JSON Web Key Set)

• scope space-separated list of strings A space-separated list of scopes that the client can request as part of each authorization request. See below for a list of support scopes.

• id_token_encrypted_response_alg string The algorithm used for encryption of the Content Encryption Key (CEK). Supported values are:

  "A256KW",
  "ECDH-ES",
  "RSA-OAEP",
  "RSA-OAEP-256"

• id_token_encrypted_response_enc string The algorithm used for encryption of the ID Token content. This value is optional, will default to A256CBC-HS512 . Supported values are:

  "A256CBC-HS512",
  "A256GCM"

Once DNAnexus Support processes your request, you will receive a confirmation that your app is registered as an OIDC client. You will also receive its client ID. The client ID is a unique string, in UUID format, that identifies your app. You will need this client ID to set up and maintain your app as an OIDC client, so store it securely.

Step 2. Obtain Your Client Secret

Once you've successfully registered your client and obtained the Client ID, you must next obtain a Client Secret. This is a unique string that the app will present to the DNAnexus OIDC server, along with the Client ID, during authentication. To obtain the Client Secret, use the API method /oidcClient-xxxx/resetClientSecret, replacing "xxxx" with the app's Client ID.

$ dx api oidcClient-xxxx resetClientSecret

Step 3. Configure Your App to Use the Client ID and Client Secret

Next you must configure your app to use the client ID and client secret, as part of authentication requests. The simplest way to do this is by leveraging an OIDC-compliant client library, such as open-id client.

Note the following about how the DNAnexus OIDC server handles authorization requests:

• Authorization requests are handled in keeping with the Authorization Code Flow as defined in the Open ID connect Core 1.0 spec.
• The Proof Key for Code Exchange (PKCE) standard is enforced
• Only pairwise identifiers are supported.
• ID Token has to always be encrypted using JWE and leveraging JWK

Step 4. Configure Your App to Request Information from Users

Apps must request the openid scope. App may require that any or all of the additional scopes, listed below, be included in authorization requests:

• openid string The app must always request this scope. In return, the app will receive the ID token providing identity data for the user.

• user_id string A user’s Platform username, prepended with user- in the form user-username (e.g. user-amy)

• name string The user’s full name, exactly as registered when he or she created a DNAnexus user account

• email string The email address associated with the user’s DNAnexus user account

Resetting Your App's Client Secret

If you need to reset your app's client secret, you can do this via a call to the API endpoint /oidcClient-xxxx/resetClientSecret, replacing "xxxx" with the app's client ID, as when you obtained the client secret in the first place (see Step 2 above). Once a new client secret is generated, the previous secret gets invalidated momentarily.

Learn More

See this DNAnexus-maintained Github repo for a sample app illustrating how to configure a web-based app to use the DNAnexus OIDC service.