ya-express-ntlm

An express middleware to have basic NTLM-authentication in node.js.

The project express-ntlm was taken as a basis and rewritten in TypeScript.

• The logic for caching the connection to the LDAP server has been changed. The default connection ID is now the domain name.
• Added a delay after an unsuccessful authorization attempt on the LDAP server. If the password is entered incorrectly, this prevents the user from being locked out. if the domain controller has a blocking policy set after, for example, 3 failed authentication attempts within 1 minute.
• Added advanced logging in debug mode with decoded NTLM messages. Using code from the project ntlm-parser.
• In "NTLM_STUB" mode the LDAP server is not used. And the NTLM message Type 2 is generated using code taken from the project @node-ntlm/core.

install

npm install ya-express-ntlm

Usage example

JS

const dotenv = require('dotenv');

dotenv.config();
const express = require('express');
const { authNTLM } = require('ya-express-ntlm');

process.env.DEBUG = 'ntlm:auth-flow,ntlm:ldap-proxy,ntlm:ldap-proxy-id';

const app = express();
const port = Number(process.env.TEST_PORT) || 8080;

app.use(authNTLM({
  getDomain: () => process.env.DOMAIN || 'MYDOMAIN',
  getDomainControllers: () => [process.env.LDAP_ADDRESS || 'ldap://dc.mydomain.myorg.com'],
}));

app.all('*', (req, res) => {
  res.end(JSON.stringify({ ts: Date.now(), ...req.ntlm }));
  // {"domain": "MYDOMAIN", "username": "MYUSER", "workstation": "MYWORKSTATION"}
});

app.listen(port);

console.log(`Server listening on http://localhost:${port}`);

TypeScript

import * as dotenv from 'dotenv';
import express, { Request, Response } from 'express';

dotenv.config();
process.env.DEBUG = 'ntlm:auth-flow,ntlm:ldap-proxy,ntlm:ldap-proxy-id';

import { authNTLM, EAuthStrategy } from 'ya-express-ntlm';

const app: express.Express = express();
const port = Number(process.env.TEST_PORT) || 8080;

app.use(authNTLM({
  getDomain: () => process.env.DOMAIN || 'MYDOMAIN',
  getDomainControllers: () => [process.env.LDAP_ADDRESS || 'ldap://dc.mydomain.myorg.com'],
}));

app.all('*', (req: Request, res: Response) => {
  res.end(JSON.stringify({ ts: Date.now(), ...req.ntlm }));
  // {"domain": "MYDOMAIN", "username": "MYUSER", "workstation": "MYWORKSTATION"}
});

app.listen(port);

console.log(`Server listening on http://localhost:${port}`);

To use the req.ntlm object in your TypeScript project, add the file express-augmented.d.ts

declare global {
  namespace Express {
    export interface Request {
      ntlm: {
        username?: string,
        domain?: string,
        workstation?: string,
        isAuthenticated?: boolean,
        uri?: string,
      },
    }
  }
}

Without validation

It's not recommended, but it's possible to add NTLM-Authentication without validation. This means you can authenticate without providing valid credentials.

app.use(authNTLM({
  getStrategy: () => 'NTLM_STUB',
  getDomain: () => process.env.DOMAIN || 'MYDOMAIN',
}));

Options

All parameters are optional functions listed here

Default values are here.

Notes

All NTLM-fields (username, domain, workstation) are also available within response.locals.ntlm, which means you can access it through your template engine (e.g. jade or ejs) while rendering (e.g. <%= ntlm.username %>).

Debugging

You can view the entire authorization process in detail. To enable debug mode, you need to set ENV DEBUG

DEBUG=ntlm:auth-flow,ntlm:ldap-proxy,ntlm:ldap-proxy-id

Typical NTLM handshake looks like this

Create / Decode NTLM messages

To experiment with NTLM messages:

import { startCoder } from 'ya-express-ntlm';

startCoder();

Silent authentication within the corporate network

Let's say you host the site my-intranet-site.corp.com for your corporate network and configure NTLM authentication on it using ya-express-ntml.

Your users log in to their Windows computers in the MYDOMAIN domain.

If you do not take additional measures, then the first time after launching the browser, when going to the site, the WWW-Authenticate: NTLM header will be sent in response to the HTTP request and the browser will display a pop-up dialog for entering your login and password:

But Windows already has information about what login the user is logged in under. And you can ensure that such login popup will not be displayed. The login under which the user logged into Windows will be automatically used.

To do this, you need to ask your domain administrator to add the site https://my-intranet-site.corp.com to Intranet zone.

As a result of ya-express-ntml operation, res.ntlm will contain the name of the authenticated user, and then it can be used in the authorization logic on your site.

References

NTLM specification

A more understandable document describing NTLM

NTLM Authentication Scheme for HTTP