@duosecurity/duo_universal
Version:
Node.js implementation of the Duo Universal SDK.
111 lines (70 loc) • 3.29 kB
Markdown
# Duo Universal Node.js library
[](https://github.com/duosecurity/duo_universal_nodejs/actions/workflows/nodejs-ci.yml)
[](https://badge.fury.io/js/@duosecurity%2Fduo_universal)
[](https://github.com/duosecurity/duo_universal_nodejs/blob/main/LICENSE)
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](https://github.com/lukashroch) for creating the initial version of this library.
## Getting Started
This library requires Node.js v14 or later.
To use this client in your existing developing environment, install it from NPM
```sh
npm install @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
```ts
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.
```ts
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.
```ts
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.
```ts
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.
```ts
const authUrl = client.createAuthUrl('username', 'state');
```
### 6. Token & code exchange
Exchanges received `duo code` from callback redirect for token result.
```ts
const token = await client.exchangeAuthorizationCodeFor2FAResult('duoCode', 'username');
```
## Example
A complete implementation example can be found in [`example/`](/example).
It's a simple express-based application.
Please follow the [`example/README.md`](/example/README.md) to spin it up.
## Contribute
Fork the repository
Install dependencies
```sh
npm install
```
Make your proposed changes. Add tests if applicable, lint the code. Submit a pull request.
## Tests
```sh
npm run test
```
## Lint
```sh
npm run lint
```