You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

113 lines
3.1 KiB

  1. # basic-auth
  2. [![NPM Version][npm-image]][npm-url]
  3. [![NPM Downloads][downloads-image]][downloads-url]
  4. [![Node.js Version][node-version-image]][node-version-url]
  5. [![Build Status][travis-image]][travis-url]
  6. [![Test Coverage][coveralls-image]][coveralls-url]
  7. Generic basic auth Authorization header field parser for whatever.
  8. ## Installation
  9. This is a [Node.js](https://nodejs.org/en/) module available through the
  10. [npm registry](https://www.npmjs.com/). Installation is done using the
  11. [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  12. ```
  13. $ npm install basic-auth
  14. ```
  15. ## API
  16. <!-- eslint-disable no-unused-vars -->
  17. ```js
  18. var auth = require('basic-auth')
  19. ```
  20. ### auth(req)
  21. Get the basic auth credentials from the given request. The `Authorization`
  22. header is parsed and if the header is invalid, `undefined` is returned,
  23. otherwise an object with `name` and `pass` properties.
  24. ### auth.parse(string)
  25. Parse a basic auth authorization header string. This will return an object
  26. with `name` and `pass` properties, or `undefined` if the string is invalid.
  27. ## Example
  28. Pass a Node.js request object to the module export. If parsing fails
  29. `undefined` is returned, otherwise an object with `.name` and `.pass`.
  30. <!-- eslint-disable no-unused-vars, no-undef -->
  31. ```js
  32. var auth = require('basic-auth')
  33. var user = auth(req)
  34. // => { name: 'something', pass: 'whatever' }
  35. ```
  36. A header string from any other location can also be parsed with
  37. `auth.parse`, for example a `Proxy-Authorization` header:
  38. <!-- eslint-disable no-unused-vars, no-undef -->
  39. ```js
  40. var auth = require('basic-auth')
  41. var user = auth.parse(req.getHeader('Proxy-Authorization'))
  42. ```
  43. ### With vanilla node.js http server
  44. ```js
  45. var http = require('http')
  46. var auth = require('basic-auth')
  47. var compare = require('tsscmp')
  48. // Create server
  49. var server = http.createServer(function (req, res) {
  50. var credentials = auth(req)
  51. // Check credentials
  52. // The "check" function will typically be against your user store
  53. if (!credentials || !check(credentials.name, credentials.pass)) {
  54. res.statusCode = 401
  55. res.setHeader('WWW-Authenticate', 'Basic realm="example"')
  56. res.end('Access denied')
  57. } else {
  58. res.end('Access granted')
  59. }
  60. })
  61. // Basic function to validate credentials for example
  62. function check (name, pass) {
  63. var valid = true
  64. // Simple method to prevent short-circut and use timing-safe compare
  65. valid = compare(name, 'john') && valid
  66. valid = compare(pass, 'secret') && valid
  67. return valid
  68. }
  69. // Listen
  70. server.listen(3000)
  71. ```
  72. # License
  73. [MIT](LICENSE)
  74. [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/basic-auth/master
  75. [coveralls-url]: https://coveralls.io/r/jshttp/basic-auth?branch=master
  76. [downloads-image]: https://badgen.net/npm/dm/basic-auth
  77. [downloads-url]: https://npmjs.org/package/basic-auth
  78. [node-version-image]: https://badgen.net/npm/node/basic-auth
  79. [node-version-url]: https://nodejs.org/en/download
  80. [npm-image]: https://badgen.net/npm/v/basic-auth
  81. [npm-url]: https://npmjs.org/package/basic-auth
  82. [travis-image]: https://badgen.net/travis/jshttp/basic-auth/master
  83. [travis-url]: https://travis-ci.org/jshttp/basic-auth