hapi-auth-multiple-strategies

Require multiple authentication strategies in hapi.

Installation · Usage · Strategy Options

Follow @marcuspoehls for updates!

^{The Future Studio University supports development of this hapi plugin 🚀}
Join the Future Studio University and Skyrocket in Node.js

Introduction

Add hapi-auth-multiple-strategies in your hapi project to authenticate a request against multiple authentication strategies. Hapi allows you to define multiple auth strategies on a route, but this requires only a single strategy to authenticate the request. In contrast, hapi-auth-multiple-strategies requires all strategies to be successful.

Installation

Add hapi-auth-multiple-strategies as a dependency to your project:

npm i hapi-auth-multiple-strategies

Requirements

hapi v19 (or later) and Node.js v12 (or newer)

This plugin requires hapi v19 (or later) and Node.js v12 or newer.

Compatibility

Major Release	hapi.js version	Node.js version
v3	>=18 hapi	>=12
v2	>=18 hapi	>=8
v1	>=17 hapi	>=8

Usage

Register hapi-auth-multiple-strategies to your hapi server. This will add the multiple-strategies authentication scheme to your hapi server.

await server.register({
  plugin: require('hapi-auth-multiple-strategies')
})

// went smooth like chocolate :)
// now your hapi server supports the 'multiple-strategies' auth scheme

Then declare a new authentication strategy base on the multiple-strategies scheme and pass in all required strategies.

// Assuming you have the following strategies your server
server.auth.strategy('jwt', 'bearer', options);
server.auth.strategy('jwt-refresh', 'token', options);

// create a new strategy that requires both 'jwt' strategies
server.auth.strategy('jwt-all-in', 'multiple-strategies', {
  strategies: ['jwt', 'jwt-refresh']
});

// use the 'jwt-all-in' strategy on your route
server.route({
  method: 'GET',
  path: '/api/logout',
  config: {
    auth: 'jwt-all-in',
    handler: () => 'hey bud, you’re logged out'
  }
});

The jwt-all-in strategy ensures that an incoming request satisfies both strategies, jwt and jwt-refresh.

If a request doesn’t authenticate with one or more of the strategies, it will return unauthenticated.

Authentication Strategy Options

When creating a new authentication strategy using the multiple-strategies scheme, you’re required to pass in an array of the authentication strategy names that are required.

• strategies: (Array), required
  • an array of auth strategy names against a request will be authenticated

Credentials & Scope

Typically the request.auth.credentials is populated with the credentials from a single strategy. When testing multiple strategies, you’ll get the credentials from all strategies.

When a request passes all authentication strategies, the related credentials are assigned to the strategy’s name in request.auth.credentials.

Because hapi authorizes requests via the scope property, you’ll find the aggregated scope from all strategies in the credentials as well.

Here’s a sample result of request.auth.credentials:

{
  jwt: { name: 'Marcus', scope: [ 'admin' ] }
  'jwt-refresh': { username: 'marcus', name: 'Marcus', scope: [ 'user' ] }
  scope: [ 'admin', 'user' ]
});

Enjoy!

Links & Resources

• hapi tutorial series with 100+ tutorials

Contributing

• Create a fork
• Create your feature branch: git checkout -b my-feature
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request 🚀

License

MIT © Future Studio

futurestud.io  ·  GitHub @futurestudio  ·  Twitter @futurestud_io

Changelog

3.0.0 - 2020-01-10

Breaking Changes

• require Node.js v12
  • this change aligns with the hapi ecosystem requiring Node.js v12 with the release of hapi 19