express-ntlm

2.7.0 verified Sat Apr 25 auth: no javascript

Express middleware for NTLM authentication in Node.js. Current stable version 2.7.0. Maintained as of 2023. It provides NTLM authentication for Express apps, supporting both NTLMv1 and NTLMv2, with optional LDAP validation. Compared to alternatives like passport-ntlm, express-ntlm is simpler and does not require Passport.js. It handles NTLM negotiation, extracts user info (username, domain, workstation), and can validate against Active Directory via LDAP. Known issues with proxies and multiple users on same connection.

Common errors

error TypeError: Cannot read property 'authenticate' of null ↓

cause The module could not extract NTLM type 2 or type 3 messages; often due to malformed NTLM headers.

fix

Ensure the client sends proper NTLM authentication; verify network setup and proxy configuration.

error Error: connect ECONNREFUSED <ldap-server>:389 ↓

cause LDAP connection refused; domaincontroller host/port unreachable.

fix

Check LDAP server availability, firewall rules, and domaincontroller URL.

error Error: NTLM type 2 message generation failed ↓

cause The module failed to create an NTLM type 2 challenge.

fix

Update to latest version (2.6.1+); if persists, check client NTLM version support.

Warnings

breaking Upgrading from v1.0: The fields for username, domain and workstation have different names: `UserName`, `DomainName`, `Workstation`. ↓

fix Update property names in your code from req.ntlm.username to req.ntlm.UserName, etc.

gotcha NTLM authenticates the TCP connection, not HTTP session. Behind a reverse proxy, multiple users may share the same connection, causing user mixup. ↓

fix Use connection-pinning (e.g., nginx ip_hash) or custom reverse proxy with session sharing.

gotcha Without validation (no domaincontroller), the middleware will accept any NTLM response, including fake ones. Security risk. ↓

fix Always provide a domaincontroller for LDAP validation in production.

deprecated Old method for NTLM without proxy (NTLM_No_Proxy) is deprecated; use the standard options. ↓

fix Use the standard middleware options; NTLM_No_Proxy is removed.

Install

npm install express-ntlm

yarn add express-ntlm

pnpm add express-ntlm

Imports

default
```
const ntlm = require('express-ntlm');
```
The module exports a single function. Use with Express middleware.

default

wrong

import ntlm from 'express-ntlm';
// use with ES module imports (if your project uses type: module)

correct

import ntlm from 'express-ntlm';

ESM import works if package.json has 'type': 'module' or using .mjs.

ntlm (as middleware)
wrong
```
app.use(ntlm); // missing options
```
correct
```
app.use(ntlm({ domain: 'DOMAIN', domaincontroller: 'ldap://dc.example.com' }));
```
The middleware requires an options object. At minimum, domain and domaincontroller are required for validation.

Quickstart

Sets up an Express server with NTLM authentication middleware, requiring LDAP domain controller.

const express = require('express');
const ntlm = require('express-ntlm');

const app = express();

// NTLM authentication middleware
app.use(ntlm({
  debug: (...args) => console.log(...args),
  domain: 'MYDOMAIN',
  domaincontroller: 'ldap://myad.example',
}));

app.all('*', (req, res) => {
  res.end(JSON.stringify(req.ntlm));
});

app.listen(3000, () => console.log('Server running on port 3000'));