Additional documentation for ConsumerStStrategy.

Author: jaredhanson

lib/passport-http-oauth/strategies/consumer.js

@@ -14,6 +14,29 @@ var passport = require('passport')
  * parameter can be located in an `Authorization` header field, the request
  * entity body, or the URL query parameters.
  *
+ * This strategy requires three functions as callbacks, referred to as
+ * `consumer`, `token` and `validate`.
+ *
+ * The `consumer` callback accepts `consumerKey` and must call `done` supplying
+ * a `consumer` and `consumerSecret`.  The strategy will use the secret to
+ * compute the signature, failing authentication if it does not match the
+ * request's signature.  Note that `consumer` is the authenticating entity of
+ * this strategy, and will be set by Passport at `req.user` upon success. If an
+ * exception occured, `err` should be set.
+ *
+ * The `token` callback accepts `requestToken` and must call `done` supplying
+ * a `tokenSecret` and optional `info`.  The strategy will use the secret to
+ * compute the signature, failing authentication if it does not match the
+ * request's signature.  The optional `info` is typically used to carry
+ * additional authorization details associated with the token (the verifier, for
+ * example).  `info` will be set by Passport at `req.authInfo`, where it can be
+ * used by later middleware, avoiding the need to re-query a database for the
+ * same information.  If an exception occured, `err` should be set.
+ *
+ * The `validate` callback is optional, accepting `timestamp` and `nonce` as a
+ * means to protect against replay attacks.
+ *
+ *
  * Note that despite defining a single authentication scheme, OAuth
  * authentication serves two distinct purposes:
  *   1. Authenticating consumers (aka clients) that are requesting access to
@@ -25,8 +48,8 @@ var passport = require('passport')
  * Due to the nature of OAuth, in cases where the consumer is attempting to
  * obtain an access token, the credentials will also contain a callback URL or a
  * previously issued request token and verifier.  This information will be
- * carried through in `req.authInfo` to be handled by other middleware or routes
- * as necessary.
+ * carried through by Passport in `req.authInfo` to be handled by other
+ * middleware or routes as necessary.
  *
  * When the consumer is making a request to the request token endpoint,
  * `authInfo` will contain the following properties:
@@ -46,6 +69,31 @@ var passport = require('passport')
  * and access token URL, as defined by the OAuth specification (aka the
  * temporary credential endpoint and token endpoint in RFC 5849).
  *
+ * Examples:
+ *
+ *     passport.use('consumer', new ConsumerStrategy(
+ *       function(consumerKey, done) {
+ *         Consumer.findByKey({ key: consumerKey }, function (err, consumer) {
+ *           if (err) { return done(err); }
+ *           if (!consumer) { return done(null, false); }
+ *           return done(null, consumer, consumer.secret);
+ *         });
+ *       },
+ *       function(requestToken, done) {
+ *         RequestToken.findOne(requestToken, function (err, token) {
+ *           if (err) { return done(err); }
+ *           if (!token) { return done(null, false); }
+ *           // third argument is optional info.  typically used to pass
+ *           // details needed to authorize the request (ex: `scope`)
+ *           return done(null, token.secret, { verifier: token.verifier });
+ *         });
+ *       },
+ *       function(timestamp, nonce, done) {
+ *         // validate the timestamp and nonce as necessary
+ *         done(null, true)
+ *       }
+ *     ));
+ *
  * References:
  *  - [Temporary Credentials](http://tools.ietf.org/html/rfc5849#section-2.1)
  *  - [Token Credentials](http://tools.ietf.org/html/rfc5849#section-2.3)