Passport.js integration for hapi
Travelogue is a Hapi plugin that provides modular and unobtrusive authentication to Hapi through Passport. Travelogue supports almost every Passport strategy including Facebook OAuth, Google OpenID, and many others listed here.
Install
$ npm install travelogue yar passport
Usage
Travelogue has been designed to integrate consistently with Passport APIs - allowing developers who have used Passport before to use Travelogue with very few modifications. Thus, most Travelogue apps will follow the same general format outlined below:
var config = hostname: 'localhost' port: 8000 urls: failureRedirect: '/login' successRedirect: '/' facebook: clientID: "..." clientSecret: "..." callbackURL: "http://localhost:8000/auth/facebook/callback" ; var plugins = yar: cookieOptions: password: 'worldofwalmart' // cookie secret isSecure: false // required for non-https applications travelogue: config; var server = confighostname configport;serverpack; serverauth; var Passport = serverpluginstraveloguepassport; // Follow normal Passport rules to add StrategiesPassport;Passport;Passport; // Add your routesserver;// ... serverstart { console;};
Note: Be careful with setting strategy callbackURL
's. If you are testing using localhost:{port}
, make sure this matches the callbackURL exactly AND the designated callback URL in your third-party application settings.
Known Broken/Unsupported Strategies
Check the GitHub Issues area for exisiting issues and to report an issue.
Route Handling
There are three common categories of third-party authentication route handling:
- External Authentication
- Internal Authentication
- Authorization
External Authentication allows the user to authenticate themselves via a third-party service like Facebook or Twitter.
Internal Authentication returns the credentials from External Authentication for verification on the server and ultimately "logs" the user on (saves their session for subsequent visits).
Authorization checks whether or not the user logged-on is allowed to access a specific route or resource.
External Authentication
For most third-party authentication schemes/strategies, External Authentication is done via a single route using the Passport.authenticate(__strategy__)(request)
handler.
This handler typically will redirect the user to the third-party website, authenticate the user, and redirect to the callbackURL
configured for that specific strategy (the Internal Authentication step).
server;
Internal Authentication
For all authentication schemes and strategies, the External Authentication information must be sent back to the server. Thus, one route handler must be specifically catered to the task of retrieving this information and processing it appropriately (using the Passport.authenticate(strategy, options)(request, passthroughHandler)
format).
server;
Authorization
After verifying the identity of a user, the server will need to determine the permissions a user has for specific routes and resources.
In the typical case, once verified and logged-in, the user has full access to a new set of routes. Travelogue provides a shortcut to verify that a user is logged-on via the config.auth
interface.
server;
However, it may be the case that there may be several levels of user access permissions. Just like with Passport, a custom function can be created similar to Passport's typical ensureAuthenticated
.
Conflicts with Other Hapi Auth Schemes
It is possible to use multiple Hapi authentication schemes simultaneously within one application. To prevent conflicts, set the config.auth
to false
in any handler that should NOT use any auth schemes. An example is shown below.
server;
API Reference
While, Travelogue only requires the use of a few functions to configure and set up Passport authentication, it may be important to customize Travelogue's behavior outside the defaults. Therefore, Travelogue exposes several low-level methods. This section contains documentation for all methods and variables (but may be incomplete for the time being).
Settings
Some settings must be passed into the Hapi plugins architecture.
yar
- the options object passed to yarcookieOptions
password
- (Required) secret key used to hash cookieisSecure
- enables TLS/SSL cookies. Defaults to true. Disable for normal http.
travelogue
- the options object passed to travelogueurls
- Urls used by Travelogue/PassportfailureRedirect
- redirect to this relative URL on failed logins. Defaults to '/login'.successRedirect
- redirect to this relative URL on successful logins. Defaults to '/'.
excludePaths
- array of string paths that will not employ travelogue authorization or authentication; these paths will be excluded from Travelogue.
Returns null.
API
Travelogue.passport
Returns an alternative reference to the passport module. Can also be accessed from server.plugins.travelogue.passport
.
Travelogue.middleware
Provides direct access to the passport middlewares specifically created for Hapi.
Returns an object with the following interface:
authenticate
- authentication related functionsinitialize
- initialization related functions
Those functions can be modified to add custom behavior with respect to Passport. Modify at your own risk.
Request-level
Request.session._isAuthenticated()
Returns true if the request is authenticated; false, otherwise.
Request.session._logIn(user, options, next)
Provides a direct interface to setting or modifying the user session data.
user
- (Required) an object that contains user session dataoptions
- the options object (currently unused)next
- (Required) callback function to execute on completion or failure
Returns null.
Request.session._logOut()
Permanently deletes the user session data ( thus unauthenticating the user and clearing out cookies).
Returns null.