Duo Universal Node.js library

This library allows a web developer to quickly add Duo's interactive, self-service, two-factor authentication to any Node.js web login form.

See our developer documentation at https://www.duosecurity.com/docs/duoweb for guidance on integrating Duo 2FA into your web application.

Duo especially thanks Lukas Hroch for creating the initial version of this library.

Getting Started

This library requires Node.js LTS (v20 or later).

To use this client in your existing developing environment, install it with your package manager of choice.

npm install @duosecurity/duo_universal

pnpm add @duosecurity/duo_universal

yarn add @duosecurity/duo_universal

Once it's installed, see our developer documentation at https://duo.com/docs/duoweb and the example folder in this repo for guidance on integrating Duo 2FA into your web application.

TLS 1.2 and 1.3 Support

Duo_universal_nodejs uses the Node tls library and OpenSSL for TLS operations. All versions of Node receiving security support (14 and higher) use OpenSSL 1.1.1 which supports TLS 1.2 and 1.3.

Usage Details

1. Import client

import { Client } from '@duosecurity/duo_universal';

2. Create client

Creates new client instance. Provide your Duo Security application credentials and host URL. Include redirect URL to make a way back to your application.

const client = new Client({
    clientId: 'yourDuoApplicationClientId',
    clientSecret: 'yourDuoApplicationSecret',
    apiHost: 'api-12345678.duosecurity.com',
    redirectUrl: 'http://localhost:3000/redirect',
});

3. Heath check

Determines if Duo’s servers are accessible and available to accept the 2FA request.

const status = await client.healthCheck();

4. Generate state

Generates new state (random string) to link the with authentication attempt. Store appropriately, so you can retrieve/compare on callback.

const state = client.generateState();

5. Create authentication URL

Creates authentication URL to redirect user to Duo Security Universal prompt. Provide user identifier and state generated in previous step.

const authUrl = await client.createAuthUrl('username', 'state');

6. Token & code exchange

Exchanges received duo code from callback redirect for token result.

const token = await client.exchangeAuthorizationCodeFor2FAResult('duoCode', 'username');

Optional: nonce

A nonce binds the authentication request to the resulting token. Generate one alongside the state, store it with the state, and pass it to both calls — the returned token is then rejected unless its nonce claim matches.

const state = client.generateState();
const nonce = client.generateNonce();
/* Store both against the user's session before redirecting. */

const authUrl = await client.createAuthUrl('username', state, { nonce });

/* On callback, after confirming the returned state matches the stored one: */
const token = await client.exchangeAuthorizationCodeFor2FAResult('duoCode', 'username', nonce);

A supplied nonce must be between MIN_NONCE_LENGTH (16) and MAX_NONCE_LENGTH (1024) characters, otherwise a DuoException is thrown. Omit nonce entirely to leave the claim out of the request.

Example

A complete implementation example can be found in example/. It's a simple express-based application. Please follow the example/README.md to spin it up.

Contribute

Fork the repository

Install dependencies

pnpm install

Make your proposed changes. Add tests if applicable, lint the code. Submit a pull request.

Tests

pnpm run test

Lint

pnpm run lint