Hawk authentication plugin
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.travis.yml Update travis file and license Nov 15, 2017
CONTRIBUTING.md
LICENSE
README.md
package.json

README.md

hapi-auth-hawk

hapi Hawk authentication plugin

Build Status

Lead Maintainer: Matt Harrison

Hawk authentication

Hawk authentication provides a holder-of-key authentication scheme. The scheme supports payload authentication. The scheme requires the following options:

  • getCredentialsFunc - credential lookup function with the signature [async] function(id) where:
    • id - the Hawk credentials identifier.
    • throws an internal error.
    • returns { credentials } object where:
      • credentials a credentials object passed back to the application in request.auth.credentials. Set to be null or undefined to indicate unknown credentials (which is not considered an error state).
  • hawk - optional protocol options passed to Hawk.server.authenticate().
const Hapi = require('hapi');

const credentials = {
    d74s3nz2873n: {
        key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',
        algorithm: 'sha256'
    }
};

const getCredentialsFunc = function (id) {

    return credentials[id];
};

const start = async () => {

    const server = Hapi.server({ port: 4000 });

    await server.register(require('hapi-auth-hawk'));

    server.auth.strategy('default', 'hawk', { getCredentialsFunc });
    server.auth.default('default');

    server.route({
        method: 'GET',
        path: '/',
        handler: function (request, h) {

            return 'welcome';
        }
    });

    await server.start();

    console.log('Server started listening on %s', server.info.uri);
};

start();

// Ensure process exits on unhandled rejection

process.on('unhandledRejection', (err) => {

    throw err;
});

Bewit authentication

Bewit authentication provides a short-term access to a protected resource by including a token (bewit) in the request query, issued by an authorized party. Bewit is a subset of the Hawk protocol. The scheme can only be used with 'GET' requests and requires the following options:

  • getCredentialsFunc - credential lookup function with the signature async function(id) where:
    • id - the Hawk credentials identifier.
    • throws an internal error.
    • returns { credentials } object where:
      • credentials a credentials object passed back to the application in request.auth.credentials. Set to be null or undefined to indicate unknown credentials (which is not considered an error state).
  • hawk - optional protocol options passed to Hawk.server.authenticateBewit().
const Hapi = require('hapi');

const credentials = {
    d74s3nz2873n: {
        key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',
        algorithm: 'sha256'
    }
};

const getCredentialsFunc = function (id) {

    return credentials[id];
};

const start = async () => {

    const server = Hapi.server({ port: 4000 });

    await server.register(require('.'));

    server.auth.strategy('default', 'bewit', { getCredentialsFunc });
    server.auth.default('default');

    server.route({
        method: 'GET',
        path: '/',
        handler: function (request, h) {

            return 'welcome';
        }
    });

    await server.start();

    console.log('Server started listening on %s', server.info.uri);
};

start();

// Ensure process exits on unhandled rejection

process.on('unhandledRejection', (err) => {

    throw err;
});

To send an authenticated Bewit request, the URI must contain the 'bewit' query parameter which can be generated using the Hawk module:

const Hawk = require('hawk');

const credentials = {
    id: 'd74s3nz2873n',
    key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',
    algorithm: 'sha256'
};

let uri = 'http://example.com:8080/endpoint';
const bewit = Hawk.client.getBewit(uri, { credentials: credentials, ttlSec: 60 });
uri += '?bewit=' + bewit;