# Enabling Web Application Users to Log In with DNAnexus Credentials

With the DNAnexus OpenID Connect (OIDC) service, you can securely enable users to log in to your web-based applications using their existing DNAnexus Platform credentials.

{% hint style="success" %}
For an example of how to configure a web-based app to use the OpenID Connect flow with DNAnexus, check this DNAnexus-provided [OIDC sample app in JavaScript](https://github.com/dnanexus/oidc-example-app).
{% endhint %}

## 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, allowing users to log in and access its functionality via a web interface.
* Provide a web-accessible privacy policy and terms of service.
* Specify a JSON Web Key Set (JWKS) endpoint URL to support verification of the required JSON Web Token (JWT) ID token.

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

To register your app with DNAnexus as an OIDC client, you need to [contact DNAnexus Support](mailto:support@dnanexus.com) with the following details about your app:

* `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](https://documentation.dnanexus.com/api/users#username-handle-vs-user-id) of the user who can set and reset the app's [client secret](#step-2-set-a-client-secret). You can specify only a single user as the app author.
* `redirect_uris` **array of strings** A list of one or more HTTPS URLs to which user authorization requests are directed.
* `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 [JSON Web Key Set (JWKS)](https://openid.net/specs/openid-connect-core-1_0.html#Encryption). This URL must be publicly accessible over HTTPS. You can host the JWKS file in any location that supports HTTPS access, such as an S3 bucket with public read access or a GitHub repository. The URI you provide must remain stable, but it can redirect to another location, allowing flexibility in how the content is served.

{% hint style="info" %}
**Key Rotation Requirements**

Rotate your JWKS public and private keys at regular intervals. For example, every three months, depending on your organization's security policies. You are responsible for regularly updating the file at the specified URI or updating the redirect target if your URI uses redirection.
{% endhint %}

* `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). The supported algorithms are `A256KW`, `ECDH-ES`, `RSA-OAEP`, and `RSA-OAEP-256`.
* `id_token_encrypted_response_enc` **string** The algorithm used for encryption of the ID Token content. This value is optional and defaults to `A256CBC-HS512`. The supported algorithms are `A256CBC-HS512` and `A256GCM`.
* `owning_organization_id` **string** The DNAnexus Platform org-id that is associated with the client.

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

### Step 2. Set a Client Secret

Once you register your app as an OIDC client and get the **Client ID**, you can initialize its **Client Secret**. Client secret is a unique string that the app presents to the DNAnexus OIDC server, along with the Client ID, during authentication.

To get the client secret, use the API method [`/oidcClient-xxxx/resetClientSecret`](https://documentation.dnanexus.com/api/oidc-clients##api-method-oidcclient-xxxx-resetclientsecret), replacing `xxxx` with the app's Client ID.

For newly registered apps, the `resetClientSecret` method initializes their client secret. For existing apps, it invalidates the previously used client secret and generates a new one.

```shell
# Reset app's client secret, generating a new one
dx api oidcClient-xxxx resetClientSecret
```

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

Adjust your app to use the client ID and client secret as part of authentication requests. For example, you can use an OIDC-compliant client library, such as [open-id client](https://github.com/panva/node-openid-client).

The DNAnexus OIDC server handles authorization requests in the following way:

* Authorization requests are handled per the [Authorization Code Flow as defined in the Open ID connect Core 1.0 spec](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth).
* The [Proof Key for Code Exchange (PKCE) standard](https://www.rfc-editor.org/rfc/rfc7636.html) is enforced.
* The subject identifier must be specified using the [pairwise identifier](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg) type.
* The ID Token must be encrypted using [JSON Web Encryption (JWE)](https://www.rfc-editor.org/rfc/rfc7516.html) and [JSON Web Key (JWK)](https://datatracker.ietf.org/doc/html/rfc7517)

### Step 4. Configure Your App to Request Information from Users

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

* `openid` **string** The app must always request this scope. In return, the app receives 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`. Example: `user-amy`.
* `name` **string** The user's full name, exactly as registered when they created a DNAnexus user account
* `email` **string** The email address associated with the user's DNAnexus user account

## Managing Third-Party Web Application Access

When you log in to a third-party web app, such as an OIDC client, using your DNAnexus credentials for the first time, you can choose to:

* Allow the app to automatically use your DNAnexus credentials for future logins.
* Require the app to prompt you each time before using your credentials.

To review the applications you have authorized to access your DNAnexus credentials and change their access settings at any time:

1. In [DNAnexus Platform](https://platform.dnanexus.com/), go to **Account Security** > **Third-Party Web Applications**.
2. Expand the application tile to view details.
3. Click **Revoke** to remove the app's access to your DNAnexus credentials.