1 | # http-auth
|
2 | [Node.js](http://nodejs.org/) package for HTTP basic and digest access authentication.
|
3 |
|
4 | [![build](https://github.com/http-auth/http-auth/workflows/build/badge.svg)](https://github.com/http-auth/http-auth/actions?query=workflow%3Abuild)
|
5 |
|
6 | ## Installation
|
7 |
|
8 | Via git (or downloaded tarball):
|
9 |
|
10 | ```bash
|
11 | $ git clone git://github.com/http-auth/http-auth.git
|
12 | ```
|
13 | Via [npm](http://npmjs.org/):
|
14 |
|
15 | ```bash
|
16 | $ npm install http-auth
|
17 | ```
|
18 |
|
19 | ## Basic example
|
20 | ```javascript
|
21 | // Authentication module.
|
22 | const auth = require('http-auth');
|
23 | const basic = auth.basic({
|
24 | realm: "Simon Area.",
|
25 | file: __dirname + "/../data/users.htpasswd"
|
26 | });
|
27 |
|
28 | // Creating new HTTP server.
|
29 | http.createServer(basic.check((req, res) => {
|
30 | res.end(`Welcome to private area - ${req.user}!`);
|
31 | })).listen(1337);
|
32 |
|
33 | ```
|
34 | ## Custom authentication
|
35 | ```javascript
|
36 | // Authentication module.
|
37 | const auth = require('http-auth');
|
38 | const basic = auth.basic({
|
39 | realm: "Simon Area."
|
40 | }, (username, password, callback) => {
|
41 | // Custom authentication
|
42 | // Use callback(error) if you want to throw async error.
|
43 | callback(username === "Tina" && password === "Bullock");
|
44 | }
|
45 | );
|
46 |
|
47 | // Creating new HTTP server.
|
48 | http.createServer(basic.check((req, res) => {
|
49 | res.end(`Welcome to private area - ${req.user}!`);
|
50 | })).listen(1337);
|
51 | ```
|
52 |
|
53 | ## [http-proxy](https://github.com/nodejitsu/node-http-proxy/) integration
|
54 | ```javascript
|
55 | // HTTP proxy module.
|
56 | const http = require('http'),
|
57 | httpProxy = require('http-proxy');
|
58 |
|
59 | // Authentication module.
|
60 | const auth = require('http-auth');
|
61 | const basic = auth.basic({
|
62 | realm: "Simon Area.",
|
63 | file: __dirname + "/../data/users.htpasswd", // gevorg:gpass, Sarah:testpass
|
64 | proxy: true
|
65 | });
|
66 |
|
67 | // Create your proxy server.
|
68 | const proxy = httpProxy.createProxyServer({});
|
69 | http.createServer(basic.check((req, res) => {
|
70 | proxy.web(req, res, { target: 'http://127.0.0.1:1338' });
|
71 | })).listen(1337);
|
72 |
|
73 | // Create your target server.
|
74 | http.createServer((req, res) => {
|
75 | res.end("Request successfully proxied!");
|
76 | }).listen(1338, () => {
|
77 | // Log URL.
|
78 | console.log("Server running at http://127.0.0.1:1338/");
|
79 | });
|
80 |
|
81 | // You can test proxy authentication using curl.
|
82 | // $ curl -x 127.0.0.1:1337 127.0.0.1:1337 -U gevorg
|
83 | ```
|
84 |
|
85 | ## Events
|
86 |
|
87 | The auth middleware emits three types of events: **error**, **fail** and **success**. Each event passes the result object (the error in case of `fail`) and the http request `req` to the listener function.
|
88 |
|
89 | ```javascript
|
90 | // Authentication module.
|
91 | const auth = require('http-auth');
|
92 | const basic = auth.basic({
|
93 | realm: "Simon Area.",
|
94 | file: __dirname + "/../data/users.htpasswd"
|
95 | });
|
96 |
|
97 | basic.on('success', (result, req) => {
|
98 | console.log(`User authenticated: ${result.user}`);
|
99 | });
|
100 |
|
101 | basic.on('fail', (result, req) => {
|
102 | console.log(`User authentication failed: ${result.user}`);
|
103 | });
|
104 |
|
105 | basic.on('error', (error, req) => {
|
106 | console.log(`Authentication error: ${error.code + " - " + error.message}`);
|
107 | });
|
108 | ```
|
109 |
|
110 | ## Configurations
|
111 |
|
112 | - `realm` - Authentication realm, by default it is **Users**.
|
113 | - `file` - File where user details are stored.
|
114 | - Line format is **{user:pass}** or **{user:passHash}** for basic access.
|
115 | - Line format is **{user:realm:passHash}** for digest access.
|
116 | - `algorithm` - Algorithm that will be used only for **digest** access authentication.
|
117 | - **MD5** by default.
|
118 | - **MD5-sess** can be set.
|
119 | - `qop` - Quality of protection that is used only for **digest** access authentication.
|
120 | - **auth** is set by default.
|
121 | - **none** this option is disabling protection.
|
122 | - `msg401` - Message for failed authentication 401 page.
|
123 | - `msg407` - Message for failed authentication 407 page.
|
124 | - `contentType` - Content type for failed authentication page.
|
125 | - `skipUser` - Set this to **true**, if you don't want req.user to be filled with authentication info.
|
126 | - `proxy` - Set this to **true**, if you want to use it with [http-proxy](https://github.com/http-party/node-http-proxy).
|
127 |
|
128 | ## Running tests
|
129 |
|
130 | It uses [mocha](https://mochajs.org/), so just run following command in package directory:
|
131 |
|
132 | ```bash
|
133 | $ npm test
|
134 | ```
|
135 |
|
136 | ## Issues
|
137 |
|
138 | You can find list of issues using **[this link](http://github.com/http-auth/http-auth/issues)**.
|
139 |
|
140 | ## Questions
|
141 |
|
142 | You can also use [stackoverflow](http://stackoverflow.com/questions/tagged/http-auth) to ask questions using **[http-auth](http://stackoverflow.com/tags/http-auth/info)** tag.
|
143 |
|
144 | ## Requirements
|
145 |
|
146 | - **[Node.js](http://nodejs.org)** - Event-driven I/O server-side JavaScript environment based on V8.
|
147 | - **[npm](http://npmjs.org)** - Package manager. Installs, publishes and manages node programs.
|
148 |
|
149 | ## Utilities
|
150 |
|
151 | - **[htpasswd](https://github.com/http-auth/htpasswd/)** - Node.js package for HTTP Basic Authentication password file utility.
|
152 | - **[htdigest](https://github.com/http-auth/htdigest/)** - Node.js package for HTTP Digest Authentication password file utility.
|
153 |
|
154 | ## Integrations
|
155 |
|
156 | - **[http-auth-connect](https://github.com/http-auth/http-auth-connect)** - [Connect](https://github.com/senchalabs/connect) integration.
|
157 | - **[http-auth-passport](https://github.com/http-auth/http-auth-passport)** - [Passport.js](http://www.passportjs.org/) integration.
|
158 | - **[http-auth-koa](https://github.com/http-auth/http-auth-koa)** - [Koa framework](http://koajs.com/) integration.
|
159 | - **[http-auth-hapi](https://github.com/http-auth/http-auth-hapi)** - [Hapi framework](https://hapi.dev/) integration.
|
160 |
|
161 | ## Dependencies
|
162 |
|
163 | - **[uuid](https://github.com/broofa/node-uuid/)** - Generate RFC4122(v4) UUIDs, and also non-RFC compact ids.
|
164 | - **[apache-md5](https://github.com/http-auth/apache-md5)** - Node.js module for Apache style password encryption using md5.
|
165 | - **[apache-crypt](https://github.com/http-auth/apache-crypt)** - Node.js module for Apache style password encryption using crypt(3).
|
166 | - **[bcrypt.js](https://github.com/dcodeIO/bcrypt.js)** - Optimized bcrypt in plain JavaScript with zero dependencies.
|
167 |
|
168 | ## License
|
169 |
|
170 | The MIT License (MIT)
|
171 |
|
172 | Copyright (c) Gevorg Harutyunyan
|
173 |
|
174 | Permission is hereby granted, free of charge, to any person obtaining a copy of
|
175 | this software and associated documentation files (the "Software"), to deal in
|
176 | the Software without restriction, including without limitation the rights to
|
177 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
178 | the Software, and to permit persons to whom the Software is furnished to do so,
|
179 | subject to the following conditions:
|
180 |
|
181 | The above copyright notice and this permission notice shall be included in all
|
182 | copies or substantial portions of the Software.
|
183 |
|
184 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
185 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
186 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
187 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
188 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
189 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|