ya-express-ntlm
v1.0.36
Published
ya-express-ntlm
Downloads
89
Maintainers
Readme
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.