{"id":26560784,"url":"https://github.com/jlguenego/node-expose-sspi","last_synced_at":"2025-04-09T11:10:20.953Z","repository":{"id":40290262,"uuid":"234580010","full_name":"jlguenego/node-expose-sspi","owner":"jlguenego","description":"Expose Microsoft Windows SSPI to Node for SSO authentication.","archived":false,"fork":false,"pushed_at":"2023-01-18T11:39:59.000Z","size":2706,"stargazers_count":127,"open_issues_count":31,"forks_count":19,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-02T09:07:09.389Z","etag":null,"topics":["active-directory","authentication-middleware","kerberos","microsoft-windows-sspi","negotiate","nodejs","ntlm","spnego-authentication","sso-authentication","sspi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlguenego.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["jlguenego"]}},"created_at":"2020-01-17T15:44:04.000Z","updated_at":"2025-01-12T13:34:27.000Z","dependencies_parsed_at":"2023-02-10T14:45:44.342Z","dependency_job_id":null,"html_url":"https://github.com/jlguenego/node-expose-sspi","commit_stats":null,"previous_names":[],"tags_count":81,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlguenego%2Fnode-expose-sspi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlguenego%2Fnode-expose-sspi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlguenego%2Fnode-expose-sspi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlguenego%2Fnode-expose-sspi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlguenego","download_url":"https://codeload.github.com/jlguenego/node-expose-sspi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248027407,"owners_count":21035594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["active-directory","authentication-middleware","kerberos","microsoft-windows-sspi","negotiate","nodejs","ntlm","spnego-authentication","sso-authentication","sspi"],"created_at":"2025-03-22T13:29:57.638Z","updated_at":"2025-04-09T11:10:20.930Z","avatar_url":"https://github.com/jlguenego.png","language":"C++","funding_links":["https://github.com/sponsors/jlguenego"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg width=\"200\" height=\"200\" src=\"doc/img/logo.svg\"\u003e\n  \u003ch1\u003eNode expose sspi\u003c/h1\u003e\n  \u003cp\u003e\n    Expose the Microsoft Windows SSPI (SSP Interface) to \u003ca href=\"https://nodejs.org/\"\u003eNode.js®\u003c/a\u003e.\n  \u003c/p\u003e\n\u003c/div\u003e\n\nUse cases:\n\n- **NTLM** and **Kerberos** SSO authentication, both server and client inside a private windows organization network, for instance an ERP in a private company.\n- **Active Directory** access to users for detailed info.\n\nRequirements: Microsoft Windows OS, NodeJS version \u003e=12.16.1. Architecture: x64 or ia32.\n\n## Reference\n\n - [Complete reference guide](./doc/reference/index.md)\n - [Authentication error analysis](./doc/error/index.md)\n\n## Install\n\n[![license](https://img.shields.io/badge/license-ISC-green.svg)](./LICENSE)\n[![npm version](https://badge.fury.io/js/node-expose-sspi.svg)](https://badge.fury.io/js/node-expose-sspi)\n[![sponsor](https://img.shields.io/badge/github-sponsor-blue.svg)](https://github.com/sponsors/jlguenego)\n\nJust do:\n\n```\nnpm i node-expose-sspi\n```\n\nNote: There is a prebuilt binary node addon that will be installed.\n\n## Usage\n\n### SSO Authentication server use case\n\n```bat\nmkdir myproject\ncd myproject\nnpm init -y\nnpm i express\nnpm i node-expose-sspi\n```\n\nMake an express web server by doing the `server.js` file:\n\n```js\nconst express = require('express');\nconst { sso } = require('node-expose-sspi');\n\nconst app = express();\napp.use(sso.auth());\n\napp.use((req, res, next) =\u003e {\n  res.json({\n    sso: req.sso,\n  });\n});\n\napp.listen(3000, () =\u003e console.log('Server started on port 3000'));\n```\n\n```\nnode server.js\n```\n\n**Browser on http://localhost:3000**\n\n```\n{\n  \"sso\": {\n    \"method\": \"NTLM\",\n    \"user\": {\n      \"domain\": \"JLG\",\n      \"name\": \"jlouis\",\n      \"displayName\": \"Jean-Louis P. GUÉNÉGO\",\n      \"groups\": [\n        \"JLG\\\\Domain Users\",\n        \"\\\\Everyone\",\n        // ...\n      ],\n      \"sid\": \"S-1-5-21-2022955591-1730574677-3210790899-1103\",\n      \"adUser\": {\n        // adUser filled only if Active Directory is reachable.\n        // ...\n        \"givenName\": [\"Jean-Louis\"],\n        \"sn\": [\"GUÉNÉGO\"],\n        \"c\": [\"FR\"],\n        \"l\": [\"TORCY\"],\n        \"postalCode\": [\"77200\"],\n        \"title\": [\"IT Consultant\"],\n        \"description\": [\"My microsoft domain account for demonstrating SSO\"]\n      }\n    }\n  }\n}\n```\n\nNote: To read JSON file on Chrome, you should use the [JSON Formatter Chrome Extension](https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa).\n\n**Command line client:**\n\n- Git Bash: `curl --negotiate -u : http://localhost:3000 -b cookie.txt`\n- Powershell: `Invoke-WebRequest -uri http://localhost:3000 -UseDefaultCredentials`\n\nTo know more, you can follow the [SSO Reference Manual](./doc/reference/index.md).\n\n### SSO Authentication client use case\n\n**[See the complete example](./doc/use-case/client.md)**\n\n### Account context status\n\n```js\nconst { sso } = require('node-expose-sspi');\n```\n\nThe `sso` object has following functions to help you:\n- `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](https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/how-user-account-control-works).\n- `sso.isOnDomain()`: check if the computer has joined a domain.\n- `sso.isActiveDirectoryReachable()`: check if the Active Directory domain controller is reachable.\n\n## API\n\n**[Fully detailed API document](./doc/api/README.md)**.\n\n## Browsers\n\n### Chrome\n\nNo conf. It just works.\n\n### Firefox\n\nUnlike Chrome, NTLM and Kerberos are not activated by default in Firefox. To make it working, you need to follow these steps:\n\n1. Navigate to the URL `about:config`.\n2. Click past the warning of harmful consequences.\n3. Type `negotiate-auth` into the filter at the top of the page, in order to remove most of the irrelevant settings from the list.\n4. Double-click on `network.negotiate-auth.trusted-uris`. A dialogue box for editing the value should appear.\n5. Enter the required hostname(s) and/or URL prefix(es) then click OK. For the above example, it is `http://localhost:3000`\n\n[More detailed info here](http://www.microhowto.info/howto/configure_firefox_to_authenticate_using_spnego_and_kerberos.html).\n\n### Edge\n\nEdge does not require any configuration. But the browser ask the credentials to the user each time it is started.\n\n### IE11\n\nIE11 does not require any configuration. Be careful it does not open JSON files in a simple way.\n\n## Typescript\n\nThis module is ready to be used with both typescript and javascript. No need extra typings.\n\n[Typescript example](./doc/typescript.md)\n\n## Authentication protocols\n\n### Kerberos\n\nKerberos is recommanded for production running. For running with Kerberos protocol, both client and server needs to be joined on a [Windows Domain](https://en.wikipedia.org/wiki/Windows_domain).\n\n3 conditions must be met for running Kerberos:\n\n- The node server, running `node-expose-sspi` needs to be run as a domain user with service principal name (SPN) declared in Active Directory.\n- The client browser needs to be run on a windows domain account.\n- The website url needs to be declared in a white list of intranet website.\n\n[You can find more detail in the Kerberos dedicated documentation](./doc/Kerberos.md).\n\n### NTLM\n\nIf you are not on a Windows Domain, `node-expose-sspi` will use the NLTM authentication protocol.\n\nIf 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](#Kerberos).\n\nThe 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...\n\nAnother 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.\n\n## Authentication error analysis\n\nIf you encounter error, [please read this document before submitting an issue](./doc/use-case/errors.md).\n\n## Production running\n\n### Performance\n\nYou should avoid to use the Negotiate protocol each time a user access an authenticated resources, because it may take times.\n\nJust 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.](./examples/express-ejs])\n\n### Server behind a reverse proxy\n\n[Example: node server behind an IIS proxy](./doc/use-case/production-windows.md)\n\n## Examples\n\nTo run the examples, just clone this project.\n\n```\ngit clone https://github.com/jlguenego/node-expose-sspi.git\nnpm i\ncd node-expose-sspi\ncd examples\ncd \u003c***example-name***\u003e\n```\n\nLook also at the `README.md` of the example.\n\nExamples :\n\n- [Express simple](./examples/express-simple/)\n- [Express with EJS](./examples/express-ejs/)\n- [Express with Webpack](./examples/express-webpack/)\n- [Express with pkg](./examples/express-pkg/)\n- [Koa simple](./examples/koa-simple/)\n- [Fastify simple](./examples/fastify-simple/)\n- [Restify simple](./examples/restify-simple/)\n- [Reverse proxy example](./examples/reverse-proxy/)\n- [Angular SSO example](https://github.com/jlguenego/angular-sso-example)\n- [React SSO example](https://github.com/jlguenego/react-sso-example)\n- [Vue SSO example](https://github.com/jlguenego/vue-sso-example)\n- [HTTP(S) fetch API with SSO](./doc/use-case/client.md)\n\n## Development\n\nAs a prerequisites, you need node-gyp and a C++ toolchain installed on your environment.\n\nIf you did not installed node-gyp and the C++ toolchain,\nplease open a **PowerShell command line as an administrator** and do :\n\n```\nnpm i -g windows-build-tools\n```\n\nTo compile the native node module, do the following:\n\n```\ngit clone https://github.com/jlguenego/node-expose-sspi.git\ncd node-expose-sspi\nnpm run build\nnpm run test\n```\n\nThere are 2 dev areas :\n\n- **C++ code**: run `npm run dev` to watch the modifications and recompile ASAP.\n- **Typescript code**: run `npm run build:tsw` to recompile while watching.\n\nAll tests are done with [mocha](https://github.com/mochajs/mocha).\n\nThe module [debug](https://github.com/visionmedia/debug) is used for printing some debug info.\n\n## Hardware architecture\n\nTo both compile ia32 and x64, run the `npm run build:arch` command.\n\n## TODO\n\nAny idea of new features ? Please tell me and raise an issue. :blush:\n\n- write a loopback example\n- write a nestjs example\n- write a medium article\n- Integrate with passport?\n- Test with 10000 users.\n- UTF8 everywhere\n\nScenario:\n\n- linux trial.\n\n## Thanks\n\nThanks to all the people who wrotes the npm modules required by this project.\n\nAnd a very special thanks to the authors of the [node-sspi](https://github.com/abbr/NodeSSPI) project that helped me writing this one. I considere node-sspi to be the father of node-expose-sspi.\n\nThanks also to people raising issues to improve the quality of this module.\n\n## Sponsoring\n\nThis library design aims to be used in production, in private company environment, doing business, using Microsoft Windows.\n\n[To help maintaining it, you can sponsor me with github](https://github.com/sponsors/jlguenego).\n\n## Author\n\nJean-Louis GUENEGO \u003cjlguenego@gmail.com\u003e (http://jlg-consulting.com/)\n\nYou may participate to complete this project. You can improve this doc, or check the code (memory leak, etc.), create new usefull business cases, etc.\n\nContributors are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlguenego%2Fnode-expose-sspi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlguenego%2Fnode-expose-sspi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlguenego%2Fnode-expose-sspi/lists"}