HMAC AWS signature V4 authentication strategy for Passport.

This module lets you authenticate HTTP requests using AWS Signature 4 style HMAC encryption in your Node.js application. This authentication method is typically used to protect RESTful API endpoints.

Inside it is just a wrapper around [aws4] ( It is also inspired from [passport-hmac] (


$ npm install passport-hmac-aws4


Configure Strategy

This strategy requires a verify callback, which accepts three parameters: The request, accessKeyId, 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 accessKeyId.

The `` 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.

passport.use(new HmacStrategy(
  function(accessKeyId, done) {
    User.findOne({ accessKeyId: accessKeyId }, function(err, user) {
      if (err) { return done(err); }
      if (!user) { return done(null, false); }
      return done(null, user, secretAccessKey);

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 will return the request as the first parameter to the supplied callback.
  • badRequestMessage - Optional, defaults to null. If set, will be used in place of the default error messages returned when an error occurs.
  • SignQuery - Optional, defaults to false. If set true, will sign additional standard queries to compare
  • doNotModifyHeaderse - Optional, defaults to true. If set to false, it will include additional headers like Content-Length etc.

Authenticate Requests

Use passport.authenticate(), specifying the 'hmac-aws4' strategy, to authenticate requests.

For example, as route middleware in an Express application:'/profile',
  function(req, res) {


Please refer example directory for how to use it with express


$ npm install
$ npm test



The MIT License

Supported by