Axios NTLM Authentication Helper

1.4.6 · active · verified Wed Apr 22

axios-ntlm is a helper library designed to integrate NTLM (NT LAN Manager) authentication into the popular Axios HTTP client, specifically for Node.js environments. It achieves this by attaching interceptors to an Axios instance, allowing seamless NTLM authentication for resources that require it. The current stable version is `1.4.6`. The package generally maintains a moderate release cadence, primarily focusing on dependency updates, bug fixes, and minor enhancements. Its key differentiator lies in its direct integration with Axios, providing a familiar API for developers already using Axios, and simplifying the often complex process of NTLM authentication in JavaScript applications interacting with Windows-authenticated services. It is particularly useful in enterprise settings where NTLM remains prevalent.

Common errors

```
Request hangs indefinitely with no response or error.
```
cause In versions prior to `1.4.1`, setting an `X-retry` header to `false` could trigger an infinite retry loop, causing requests to never complete and your application to appear unresponsive.

fix Upgrade your `axios-ntlm` package to version `1.4.1` or higher. If an upgrade is not immediately possible, avoid sending `X-retry: false` headers when making requests.

Warnings

breaking A critical security vulnerability (CVE-2022-0155) related to an underlying dependency was patched in version `1.2.2`.
Fix: Immediately upgrade to `axios-ntlm@1.2.2` or later to mitigate potential security risks and ensure application security.
breaking Prior to `v1.4.1`, requests involving an `X-retry: false` header could inadvertently enter an infinite retry loop, leading to resource exhaustion or indefinite hangs.
Fix: Upgrade to `axios-ntlm@1.4.1` or later to resolve the infinite retry bug. If using an older version, avoid sending `X-retry: false` headers.
gotcha When providing a custom `AxiosRequestConfig` to `NtlmClient`, explicitly configure `httpAgent` and `httpsAgent` for connection pooling and keep-alive if you are overriding the default agents. The library will add agents if none are present, but your custom configuration might override this.
Fix: Ensure your custom `AxiosRequestConfig` correctly sets `httpAgent` and `httpsAgent` with `keepAlive: true` for optimal performance with NTLM authenticated endpoints.

Install

npm install axios-ntlm npm
yarn add axios-ntlm yarn
pnpm add axios-ntlm pnpm

Imports

NtlmClient
wrong:
```
const NtlmClient = require('axios-ntlm').NtlmClient;
```
correct:
```
import { NtlmClient } from 'axios-ntlm';
```
This is the primary factory function for creating Axios instances configured with NTLM authentication.
NtlmCredentials
wrong:
```
import NtlmCredentials from 'axios-ntlm';
```
correct:
```
import { NtlmCredentials } from 'axios-ntlm';
```
This is a TypeScript interface defining the structure for NTLM authentication credentials (username, password, domain).
AxiosRequestConfig
wrong:
```
import { AxiosRequestConfig } from 'axios-ntlm';
```
correct:
```
import { AxiosRequestConfig } from 'axios';
```
While used extensively with `axios-ntlm`, `AxiosRequestConfig` is exported directly from the `axios` package, not `axios-ntlm`.

Quickstart

This example demonstrates how to create an NTLM-enabled Axios client using provided credentials and perform a simple GET request to a protected resource.

import { NtlmClient } from 'axios-ntlm';

(async () => {

    let credentials = {
        username: 'username',
        password: "password",
        domain: 'domain'
    };

    let client = NtlmClient(credentials);

    try {
        let resp = await client({
            url: 'https://protected.site.example.com',
            method: 'get'
        });
        console.log(resp.data);
    }
    catch (err) {
        console.log(err);
        console.log("Failed");
    }

})();

view raw JSON →