Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

node-expose-sspi

jlguenego1kISC0.1.60TypeScript support: included

Expose the Microsoft Windows SSPI interface in order to do NTLM and Kerberos authentication.

SSPI, SSO, Single Sign On, node-addon, kerberos, NTLM, Negotiate, SPNEGO, authentication, auth, Microsoft, Windows

readme

Node expose sspi

Expose the Microsoft Windows SSPI (SSP Interface) to Node.js®.

Use cases:

  • NTLM and Kerberos SSO authentication, both server and client inside a private windows organization network, for instance an ERP in a private company.
  • Active Directory access to users for detailed info.

Requirements: Microsoft Windows OS, NodeJS version >=12.16.1. Architecture: x64 or ia32.

Reference

Install

license npm version sponsor

Just do:

npm i node-expose-sspi

Note: There is a prebuilt binary node addon that will be installed.

Usage

SSO Authentication server use case

mkdir myproject
cd myproject
npm init -y
npm i express
npm i node-expose-sspi

Make an express web server by doing the server.js file:

const express = require('express');
const { sso } = require('node-expose-sspi');

const app = express();
app.use(sso.auth());

app.use((req, res, next) => {
  res.json({
    sso: req.sso,
  });
});

app.listen(3000, () => console.log('Server started on port 3000'));
node server.js

Browser on http://localhost:3000

{
  "sso": {
    "method": "NTLM",
    "user": {
      "domain": "JLG",
      "name": "jlouis",
      "displayName": "Jean-Louis P. GUÉNÉGO",
      "groups": [
        "JLG\\Domain Users",
        "\\Everyone",
        // ...
      ],
      "sid": "S-1-5-21-2022955591-1730574677-3210790899-1103",
      "adUser": {
        // adUser filled only if Active Directory is reachable.
        // ...
        "givenName": ["Jean-Louis"],
        "sn": ["GUÉNÉGO"],
        "c": ["FR"],
        "l": ["TORCY"],
        "postalCode": ["77200"],
        "title": ["IT Consultant"],
        "description": ["My microsoft domain account for demonstrating SSO"]
      }
    }
  }
}

Note: To read JSON file on Chrome, you should use the JSON Formatter Chrome Extension.

Command line client:

  • Git Bash: curl --negotiate -u : http://localhost:3000 -b cookie.txt
  • Powershell: Invoke-WebRequest -uri http://localhost:3000 -UseDefaultCredentials

To know more, you can follow the SSO Reference Manual.

SSO Authentication client use case

See the complete example

Account context status

const { sso } = require('node-expose-sspi');

The sso object has following functions to help you:

  • sso.hasAdminPrivileges(): check if user has administrator privileges. A user can be administrator, but when starting a process, it does not have administrator privileges by default. To have them, the process needs to be started as an administrator. See Microsoft documentation about it.
  • sso.isOnDomain(): check if the computer has joined a domain.
  • sso.isActiveDirectoryReachable(): check if the Active Directory domain controller is reachable.

API

Fully detailed API document.

Browsers

Chrome

No conf. It just works.

Firefox

Unlike Chrome, NTLM and Kerberos are not activated by default in Firefox. To make it working, you need to follow these steps:

  1. Navigate to the URL about:config.
  2. Click past the warning of harmful consequences.
  3. Type negotiate-auth into the filter at the top of the page, in order to remove most of the irrelevant settings from the list.
  4. Double-click on network.negotiate-auth.trusted-uris. A dialogue box for editing the value should appear.
  5. Enter the required hostname(s) and/or URL prefix(es) then click OK. For the above example, it is http://localhost:3000

More detailed info here.

Edge

Edge does not require any configuration. But the browser ask the credentials to the user each time it is started.

IE11

IE11 does not require any configuration. Be careful it does not open JSON files in a simple way.

Typescript

This module is ready to be used with both typescript and javascript. No need extra typings.

Typescript example

Authentication protocols

Kerberos

Kerberos is recommanded for production running. For running with Kerberos protocol, both client and server needs to be joined on a Windows Domain.

3 conditions must be met for running Kerberos:

  • The node server, running node-expose-sspi needs to be run as a domain user with service principal name (SPN) declared in Active Directory.
  • The client browser needs to be run on a windows domain account.
  • The website url needs to be declared in a white list of intranet website.

You can find more detail in the Kerberos dedicated documentation.

NTLM

If you are not on a Windows Domain, node-expose-sspi will use the NLTM authentication protocol.

If both the server and the client are on a Windows Domain, NTLM will be used if the Kerberos conditions are not met. See the Kerberos chapter of this README.

The NTLM protocol is less secure than Kerberos and not secure at all if you are not under an HTTPS connection. This is because both login and password hash go on the HTTP request, just encoded in base64...

Another thing bad in NTLM is that browsers sometimes popup a dialog box to ask credentials to the user. Your users don't like that. This is a bad user experience.

Authentication error analysis

If you encounter error, please read this document before submitting an issue.

Production running

Performance

You should avoid to use the Negotiate protocol each time a user access an authenticated resources, because it may take times.

Just use the Negotiate protocol once with sso.auth() on a specific connection url, and then put a session id cookie associated with the req.sso object. Please see this example.

Server behind a reverse proxy

Example: node server behind an IIS proxy

Examples

To run the examples, just clone this project.

git clone https://github.com/jlguenego/node-expose-sspi.git
npm i
cd node-expose-sspi
cd examples
cd <***example-name***>

Look also at the README.md of the example.

Examples :

Development

As a prerequisites, you need node-gyp and a C++ toolchain installed on your environment.

If you did not installed node-gyp and the C++ toolchain, please open a PowerShell command line as an administrator and do :

npm i -g windows-build-tools

To compile the native node module, do the following:

git clone https://github.com/jlguenego/node-expose-sspi.git
cd node-expose-sspi
npm run build
npm run test

There are 2 dev areas :

  • C++ code: run npm run dev to watch the modifications and recompile ASAP.
  • Typescript code: run npm run build:tsw to recompile while watching.

All tests are done with mocha.

The module debug is used for printing some debug info.

Hardware architecture

To both compile ia32 and x64, run the npm run build:arch command.

TODO

Any idea of new features ? Please tell me and raise an issue. :blush:

  • write a loopback example
  • write a nestjs example
  • write a medium article
  • Integrate with passport?
  • Test with 10000 users.
  • UTF8 everywhere

Scenario:

  • linux trial.

Thanks

Thanks to all the people who wrotes the npm modules required by this project.

And a very special thanks to the authors of the node-sspi project that helped me writing this one. I considere node-sspi to be the father of node-expose-sspi.

Thanks also to people raising issues to improve the quality of this module.

Sponsoring

This library design aims to be used in production, in private company environment, doing business, using Microsoft Windows.

To help maintaining it, you can sponsor me with github.

Author

Jean-Louis GUENEGO jlguenego@gmail.com (http://jlg-consulting.com/)

You may participate to complete this project. You can improve this doc, or check the code (memory leak, etc.), create new usefull business cases, etc.

Contributors are welcome!

changelog

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

0.1.60 (2022-12-21)

0.1.59 (2021-07-23)

0.1.58 (2021-06-05)

Bug Fixes

0.1.57 (2021-04-01)

Bug Fixes

  • allow compilation with node 15 (7ca1305)

0.1.56 (2021-04-01)

Bug Fixes

  • Kerberos output detailed message (2010df2)

0.1.55 (2020-12-13)

Features

  • added bug info in package.json (30f2d03)
  • added spn list from status command (ec2e1cf)

Bug Fixes

0.1.54 (2020-11-28)

Bug Fixes

0.1.53 (2020-11-27)

Features

Bug Fixes

  • cookie not well set in client (8f5b4e9)

0.1.52 (2020-11-26)

Features

  • added better watch to npm run dev (4760192)
  • added LookupPrivilegeValue (927f02c)
  • added privileges management (378a32a)
  • added TokenPrivileges (d6a46b4)

0.1.51 (2020-11-19)

Bug Fixes

  • better www-authenticate parsing (296ec9c)
  • client must be keep alive (fb1839f)
  • digest authentication testing (8e788bd)

0.1.50 (2020-11-15)

Bug Fixes

  • added Basic method to client (b855ea6)
  • added support for mocha eslint (b751429)

0.1.49 (2020-11-13)

0.1.48 (2020-11-13)

Bug Fixes

0.1.47 (2020-10-27)

0.1.46 (2020-10-23)

0.1.45 (2020-10-21)

Bug Fixes

0.1.44 (2020-09-15)

Bug Fixes

  • added req.sso = req.session.sso (191c448)
  • better typing - remove any (39590d6)

0.1.43 (2020-09-12)

Bug Fixes

0.1.42 (2020-09-12)

Bug Fixes

0.1.41 (2020-09-12)

Bug Fixes

0.1.40 (2020-09-12)

Bug Fixes

  • test working on domain with unreachable ctrl (84540d0)
  • try catch in getstatusinfo #37 (8111b43)

0.1.39 (2020-09-06)

Bug Fixes

  • added express-webpack example #34 (de3fe32)
  • rename api.node to node-expose-sspi.node (7375149)

0.1.38 (2020-08-30)

Bug Fixes

0.1.37 (2020-08-30)

Bug Fixes

0.1.36 (2020-08-24)

Bug Fixes

0.1.35 (2020-08-24)

Bug Fixes

0.1.34 (2020-08-24)

Bug Fixes

  • Issue #27 koa example (4d6f901)
  • refactored server context handle manager. (96d3f6d)

0.1.33 (2020-07-17)

Features

  • 400 to 401 on unexpected error (6949624)
  • added protocol message in error message. (9017d38)
  • added SPN.getListAll (52305e0)

0.1.32 (2020-07-16)

Features

  • added flags setup to user create account (ca3ab47)
  • SEC_E_LOGON_DENIED managed with 401. (49d30a0)

0.1.31 (2020-07-15)

Features

0.1.30 (2020-07-14)

Features

Bug Fixes

  • security on dependancies (a0de1fc)

0.1.29 (2020-07-05)

Bug Fixes

  • coverage (e24421c)
  • coverage with connect (353bc5e)
  • GetTokenInformation - filter must be a string (0b47ade)
  • removed express-jwt because not used. (bad9e5c)

0.1.28 (2020-05-31)

Features

0.1.27 (2020-05-03)

Features

0.1.26 (2020-04-30)

0.1.25 (2020-04-28)

Features

  • run on ia32 or x64 without any postinstall (484dc47)

0.1.24 (2020-04-25)

Features

0.1.23 (2020-04-14)

Features

  • add filter to GetTokenInformation (50ae48b)
  • added filter group options to auth() (12cc946)

Bug Fixes

  • useCookie was not working (c8f2848)

0.1.22 (2020-04-14)

Features

  • added connection AD (c10d7f3)
  • cookie and AD can work together (a1dabf8)

0.1.21 (2020-04-14)

Features

  • added message type detection (eaf332f)

Bug Fixes

  • client did not saved cookies correctly (df51b51)
  • improve doc readability (2cf7b18)
  • test independant of domain name (c5dfefe)

0.1.20 (2020-04-13)

Bug Fixes

  • SPN better identification (bc8e856)

0.1.19 (2020-04-13)

Features

  • add targetName options in client (4753e22)
  • added interface SecuritySupportProvider (e0aec90)
  • can force the client to use Kerberos (c1cb932)
  • test stack trace are in ts (e5fb53c)

Bug Fixes

  • bad error management in auth.ts (198b68d)
  • kerberos or ntlm method deduction (631c947)

0.1.18 (2020-04-12)

Bug Fixes

  • get SPN must use the same algo as IE (15dc162)
  • localhost SPN (e84682d)

0.1.17 (2020-04-10)

Features

0.1.16 (2020-04-10)

Bug Fixes

  • manage targetName utf16 (df50c3e)
  • reorganize target for watching dev (6b06644)
  • use targetName as SPN (Issue #6) (b3b1695)

0.1.15 (2020-04-10)

Features

  • added more debug in client (3d03834)

Bug Fixes

  • client cookie empty use case (4917af9)
  • Issue #5 about client documentation (ba18985)

0.1.14 (2020-04-08)

Features

Bug Fixes

  • no promise in middleware. (af3688a)

0.1.13 (2020-04-07)

Bug Fixes

0.1.12 (2020-04-07)

Bug Fixes

  • NextFunction can be also async (5d6005c)

0.1.11 (2020-04-07)

Bug Fixes

  • typescript asyncmiddleware (cd11640)

0.1.10 (2020-04-07)

Features

  • migration tslint to eslint (c7a08da)

0.1.9 (2020-04-05)

Features

0.1.8 (2020-04-04)

Features

  • add cookie management to auth and client (1e8e8de)

Bug Fixes

  • c++ code does not rely on atlstr.h anymore (b8d0c90)
  • small check of release method (c242a77)
  • tooLate and this.authItem (9c63c97)

0.1.7 (2020-04-02)

Bug Fixes

  • replaced autorization with Authorization (9615182)

0.1.6 (2020-04-02)

Bug Fixes

  • can support many request in parallel (4e8c359)

0.1.5 (2020-04-02)

Features

  • async error stack trace (245ea15)

Bug Fixes

  • case where authIsReady called too late (a4ac4c6)
  • Issue #2 - crash server (7b16afe)
  • refactor getUser with try catch (4f8a3b7)

0.1.4 (2020-04-01)

Features

Bug Fixes

0.1.3 (2020-03-28)

Features

  • added isActiveDirectoryReachable (c9be60b)
  • make middleware koa compliant (3036a3a)
  • use npm module debug (78a4770)

Bug Fixes

0.1.2 (2020-03-27)

Bug Fixes

  • error HTTP 431 - header too large (bfd7b54)
  • examples debugged (d920de0)
  • remove serverContextHandle (496b732)
  • update api in examples (0f841e7)

0.1.1 (2020-03-26)

Bug Fixes

0.1.0 (2020-03-26)

Features

Bug Fixes

  • add prettierrc (5096255)
  • compatibility VC++2017 remove constant (ef8010c)
  • no need test doc .vscode in npm module. (f700dfa)

0.0.21 (2020-03-18)

Features

  • adding client in sso object (931ea07)

0.0.20 (2020-02-29)

Features

0.0.19 (2020-02-27)

Features

0.0.18 (2020-02-23)

Features

  • added require-self utility (5946bcd)

Bug Fixes

0.0.17 (2020-02-23)

Features

  • adding typedoc documentation (1329844)

0.0.16 (2020-02-21)

Bug Fixes

  • req.sso not recognized in ts (b6088f3)

0.0.15 (2020-02-21)

Features

Bug Fixes

  • moving some types to interfaces (5c098f9)
  • no console.log in api (944d0ed)

0.0.14 (2020-02-17)

Bug Fixes

0.0.13 (2020-02-16)

Bug Fixes

0.0.12 (2020-02-16)

Features

  • add access token flags in ts (3204732)
  • added extended name format flag (2d532cd)
  • added flag to acceptSecurityContext (9fc1160)
  • added flags for targetDataRep (2b4bc92)
  • added IscReqFlag (9e9aba4)
  • added secStatus error msg (245fb45)

Bug Fixes

  • added flags for credentialUse (9c4e6f2)
  • added setFlags utility to return flags (775e90c)
  • added targetDataRep for ISC (d7ee57f)
  • added typings on auth() (18f0379)
  • int64_t flags (b918ca5)

0.0.11 (2020-02-16)

Bug Fixes

0.0.10 (2020-02-14)

Bug Fixes

  • default undefined displayName to name (b6a69d4)

0.0.9 (2020-02-13)

Features

Bug Fixes

  • add createSSO function (c2c7e64)
  • adding typescript interfaces (bc649b2)
  • displayName optionals (52431cd)
  • example done with session (2665566)
  • managing a bad login/password error (c2b9207)
  • refactor code for smaller file (ad5e282)
  • server error management (8bdf16b)
  • splitted code into smaller file (c0f041d)

0.0.8 (2020-02-12)

Features

  • add flags support (1469b86)
  • added NameSamCompatible for GetUserNameEx (4e9e6f2)

Bug Fixes

  • added proper error message (7b19fb2)

0.0.7 (2020-02-12)

Features

Bug Fixes

  • add display name to sso middleware (0209538)
  • added npmignore (bd0d4c2)
  • reduce footprint in the request (cce52bd)
  • remove sspi.node from git management (87d5849)
  • typescript footprint sso (2cc2b06)

0.0.6 (2020-02-12)

Bug Fixes

  • install standard-version (5cb6e0c)

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.