passport-privakey
A Passport strategy for authenticating with Privakey.
This module lets you authenticate using Privakey in your Node.js applications. Built on top of Passport, Privakey authentication can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.
Install
$ npm install passport-privakey
About Privakey
Logging in with Privakey is simple and secure. Like a social login (e.g. Sign in with Google), one can use their Privakey Login anywhere that accepts Privakey. Unlike a social login, Privakey is:
- Secure - By having users use a registered Privakey application (available for Android, iOS and Google Chrome) and a PIN, Privakey enables simple, multi-factor login.
- Flexible - If you don't want or need multi-factor login for you application, Privakey can be configured for pin-less and password-less Tap In authentication.
- Private - Privakey respects you and your user's privacy. Login history isn't shared with anybody.
Privakey leverages proprietary authentication schemes on top of standards-based OpenID Connect protocols. Learn more about Privakey at www.privakey.com.
Usage
Configure Strategy
The Privakey authentication strategy leverages the passport-openidconnect strategy to authenticates users, minimizing the amount of configuration required to enable it. To enable Privakey you must instantiate an instance of the passport-privakey strategy with variables configured in the Privakey Relying Party Administration Portal. For more information see Prerequisites.
var passport = require('passport'),
PrivakeyStrategy = require('passport-privakey').Strategy,
// Example of creating a user variable (from meanjs.org stack)
// Must adjust to conform to your applications user controller/model
users = require('../../controllers/users.server.controller');
module.exports = function (config) {
passport.use(new PrivakeyStrategy({
clientID: config.privakey.clientID,
clientSecret: config.privakey.clientSecret,
callbackURL: config.privakey.callbackURL,
scope: 'openid profile email',
passReqToCallback: true
},
function (req, accessToken, refreshToken, profile, done) {
// Set the provider data and include tokens
var providerData = profile._json;
providerData.accessToken = accessToken;
providerData.refreshToken = refreshToken;
// Example: normalize returned Privakey data to be consumed in user model
var providerUserProfile = {
firstName: profile.name.givenName,
lastName: profile.name.familyName,
displayName: profile.displayName,
email: profile._json.email,
username: profile.username,
provider: 'privakey',
providerIdentifierField: 'sub',
providerData: providerData
};
// Save the normalize Privakey profile information
users.saveOAuthUserProfile(req, providerUserProfile, done);
}));
};
Authenticate Requests
Use passport.authenticate(), specifying the 'privakey' strategy, to
authenticate requests.
NOTE: passport-privakey requires a state in order to complete the authenticate process. Be sure to set a state in your req.session if you want to use and manage your own state. If you don't provide a state before calling passport.authenticate(), a state will be generated for you and stored in the session. The state is an "opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie." (openIDConnect spec)
For example, as route middleware in an Express application:
app.get('/auth/privakey',
passport.authenticate('privakey'));
app.get('/auth/privakey/callback',
passport.authenticate('privakey', { failureRedirect: '/login' }),
function(req, res) {
// Successful authentication, redirect home.
res.redirect('/');
});
Example
For a complete, working example, refer to the Privakey MeanJS Example Application.
Prerequisites
Before you can enable Privakey for your application, you will need to get the Privakey Application and sign up to be a Privakey Relying Party.
Register as a Relying Party
- Log into Privakey's User Portal and sign up to be a Relying Party.
You will need to create a Relying Party. Information you'll need to provide, includes:
Friendly Name: This is how the applications name will present on the end-user’s pending authentication page and Privakey Apps.
Logo: Optionally, one can upload a logo that will appear on the pending authentication page presented to users during authentications.
Call Back URI: URI’s to which a user returns with references to their Token. After a successful Authentication on Privakey (See Usage for more details). For a standard Passport implementation this will be: "https://[base_uri]/auth/privakey/callback". Any callback URI defined in your application, must be configured in the Privakey Relying Party administration screens. A Service may have more than one callback URI.
Require PIN?: Privakey Authentications can be configured to require or not require the use of a PIN during authentications. For secure Authentications, the use of a PIN is recommended. However, there may be certain instances where a service may want a more convenient method of user authentication. This is configured for each Callback URI, so a service can leverage both method (for example: requiring a PIN to log in to the account but not requiring a PIN to process a transaction once logged in).
Implicit Flow: Privakey supports two OpenID Connect Protocols; Should be left at the default. More information about these different protocols can be found on OpenID.org. The passport-privakey module assumes Code Flow, as it is a more secure protocol.
For more detailed documentation on Privakey's service, visit Privakey Documentation.
Credits
This module was developed by Joseph Chew (with some assistance by Brian Ross) of Privakey.
Both Joe and Brian are greatly indebted to the following for their contributions to Passport and its numerous strategies: