HMAC authentication strategy for Passport
npm install passport-hmac!Codeship
!Code Climate
!Coveralls
!Dependencies
!devDependencies
!License
This module lets you authenticate HTTP requests using AWS Signature 2 style
HMAC encryption
in your Node.js application. This authentication method is
typically used to protect RESTful API endpoints.
By plugging into Passport, HMAC authentication support can be easily and
unobtrusively integrated into any application or framework that supports
Connect-style middleware, including
Express and Koa.
The _identifier_ can be anything you like, for example in AWS the _identifier_
is 'AWS'. This value is not currently used, but in the future it is intended to
be made available as another source of validating the request -- if needed.
The second piece is the _public key_, that typically is provided by the
_identifier_ of the service being authenticated against.
The _signature_ is the final piece and is a
RFC 2104 HMAC-SHA1 of selected parts of
the request. If the request signature calculated by the service matches the
_signature_ provided in the _authentication_ header, the requester will have
shown they have possession of the _identifier_'s secret access key.
Following is psuedogrammer adapted from AWS Signature 2 documentation.
``
Authorization = "identifier" + " " + publicKey + ":" + signature;
signature = Base64( HMAC-SHA1( YourSecretAccessKeyID, UTF-8-Encoding-Of( StringToSign ) ) );
StringToSign = HTTP-Verb + "\n" +
Content-MD5 + "\n" +
Content-Type + "\n" +
Date + "\n";
`
The elements in StrinToSign are positional in nature. The names of the headersContent-Type
are not included, only their values. If a positional header is not present in
the request (for example, or Content-MD5 are meaningless in a
GET request), substitute an empty string for that position.
TODO: implement Time Stamp Requirement
`bash`
$ npm install passport-hmac
#### Configure Strategy
This strategy requires a verify callback, which accepts three parameters: Therequest, publicKey, and a done callback.
The verify callback can be supplied with the request the passReqToCallback
option to true, this sets the request as the first parameter instead of the.
The publicKey is used to lookup a user within the system to find their private
key to compare the _signature_.
The done callback MUST be called at some point and should contain an error,false if a user is not found, or the user and private key if the user was
found.
`js`
passport.use(new HmacStrategy(
function(publicKey, done) {
User.findOne({ publicKey: publicKey }, function(err, user) {
if (err) { return done(err); }
if (!user) { return done(null, false); }
return done(null, user, privateKey);
});
}
));
#### Available options
This strategy takes an optional options hash before the function, e.g.,
new HmacStrategy({/ options /}, callback).
The available options are:
* passReqToCallback - Optional, defaults to false. Setting this to true willbadRequestMessage
return the request as the first parameter to the supplied callback.
* - Optional, defaults to null. If set, will be used in
place of the default error messages returned when an error occurs.
#### Authenticate Requests
Use passport.authenticate(), specifying the 'hmac' strategy, to authenticate
requests.
For example, as route middleware in an Express
application:
`js`
app.post('/profile',
passport.authenticate('hmac'),
function(req, res) {
res.json(req.user);
}
});
TODO: write some Examples
`bash``
$ npm install
$ npm test