support Basic and Bearer auth

README.md

@@ -24,6 +24,7 @@ request('http://www.google.com', function (error, response, body) {
 ## Table of contents
 
 - [Forms](#forms)
+- [HTTP Authentication](#http-authentication)
 - [Custom HTTP Headers](#custom-http-headers)
 - [Unix Domain Sockets](#unix-domain-sockets)
 - [**All Available Options**](#requestoptions-callback)
@@ -100,6 +101,81 @@ form.append('custom_file', fs.createReadStream(__dirname + '/unicycle.jpg'), {fi
 
 See the [form-data README](https://github.com/form-data/form-data) for more information & examples.
 
+---
+
+## HTTP Authentication
+
+<!--
+request.get('http://some.server.com/').auth('username', 'password', false);
+// or
+request.get('http://some.server.com/').auth(null, null, true, 'bearerToken');
+// or
+-->
+```js
+request.get('http://some.server.com/', {
+  'auth': {
+    'user': 'username',
+    'pass': 'password',
+    'sendImmediately': false
+  }
+});
+// or
+request.get('http://some.server.com/', {
+  'auth': {
+    'bearer': 'bearerToken'
+  }
+});
+```
+
+If passed as an option, `auth` should be a hash containing values:
+
+- `user` || `username`
+- `pass` || `password`
+- `bearer` (optional)
+
+<!--
+- `sendImmediately` (optional)
+
+The method form takes parameters
+`auth(username, password, sendImmediately, bearer)`.
+
+`sendImmediately` defaults to `true`, which causes a basic or bearer
+authentication header to be sent. If `sendImmediately` is `false`, then
+`request` will retry with a proper authentication header after receiving a
+`401` response from the server (which must contain a `WWW-Authenticate` header
+indicating the required authentication method).
+-->
+
+Note that you can also specify basic authentication using the URL itself, as
+detailed in [RFC 1738](http://www.ietf.org/rfc/rfc1738.txt). Simply pass the
+`user:password` before the host with an `@` sign:
+
+```js
+var username = 'username',
+    password = 'password',
+    url = 'http://' + username + ':' + password + '@some.server.com';
+
+request({url: url}, function (error, response, body) {
+   // Do more stuff with 'body' here
+});
+```
+
+<!--
+Digest authentication is supported, but it only works with `sendImmediately`
+set to `false`; otherwise `request` will send basic authentication on the
+initial request, which will probably cause the request to fail.
+-->
+
+Bearer authentication is supported, and is activated when the `bearer` value is
+available. The value may be either a `String` or a `Function` returning a
+`String`. Using a function to supply the bearer token is particularly useful if
+used in conjunction with `defaults` to allow a single function to supply the
+last known token at the time of sending a request, or to compute one on the fly.
+
+[back to top](#table-of-contents)
+
+---
+
 ## Custom HTTP Headers
 
 HTTP Headers, such as `User-Agent`, can be set in the `options` object.
@@ -241,6 +317,8 @@ These HTTP method convenience functions act just like `request()` but with a def
 - *request.head()*: Defaults to `method: "HEAD"`.
 - *request.options()*: Defaults to `method: "OPTIONS"`.
 
+---
+
 ## Debugging
 
 There are at least <!--three--> two ways to debug the operation of `request`:

index.js

@@ -187,6 +187,22 @@ function setDefaults(defs) {
       // Transfer-Encoding: Chunked (the default) is generally only well-supported downstream
       finalOpts.headers['Content-Length'] = _body.byteLength || _body.length;
     }
+    if (opts.auth) {
+      // if opts.uri specifies auth it will be parsed by url.parse and passed directly to the http module
+      if ('string' !== typeof opts.auth) {
+        opts.auth = (opts.auth.user||opts.auth.username||'') + ':' + (opts.auth.pass||opts.auth.password||'');
+      }
+      if ('string' === typeof opts.auth) {
+        finalOpts.auth = opts.auth;
+      }
+      if (false === opts.sendImmediately) {
+        console.warn("[Warn] setting `sendImmediately: false` is not yet supported. Please open an issue if this is an important feature that you need.");
+      }
+      if (opts.bearer) {
+        // having a shortcut for base64 encoding makes sense, but this? Eh, whatevs...
+        finalOpts.header.Authorization = 'Bearer: ' + opts.bearer;
+      }
+    }
     if (opts.formData) {
       try {
         MyFormData = opts.FormData || require('form-data');
@@ -384,6 +400,7 @@ module.exports._keys = Object.keys(_defaults).concat([
 , 'body'
 , 'json'
 , 'form'
+, 'auth'
 , 'formData'
 , 'FormData'
 ]);