privakey-sign-on

Allows authentication using Privakey to any application in node.js.

Install

npm install privakey-sign-on

Prerequisites

To implement Privakey Authentication, you must first have a Company and a Relying Party:

1. Get the Privakey app.
2. Log in to the Privakey Admin Portal and sign up as a new company.
3. In the Admin Portal, also create a Relying Party. The redirect URI for this sample is "http://localhost:1337/return".

Logging In

To authorize a login, redirect your page to the authorize login of the Privakey identity server. Generate 2 values to use as the state and nonce and store them in the session for verification later.

• The state should be 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.

• The nonce should be a string value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values.

The following code will initiate a login using Code Flow. The clientID and clientSecret should be the values from your Relying Party in the Admin Portal.

var privakeySignOn = require('privakey-sign-on');
var loginUrl;
var issuer = 'https://idp.privakey.com'; // the url to the PrivaKey server

var clientID = '1clientGuid'; // Your client ID from [PrivaKey] (https://privakey.com)
var clientSecret = 'secret'; // Your client secret from [PrivaKey] (https://privakey.com)
var redirectUrl = 'http://localhost:1337/return'; // the url that will be used as the callback of the authentication

var isCodeFlow = true;
var response_type;

if(isCodeFlow)
{
	response_type = 'code';
}
else
{
	response_type = 'id_token';
}

var state = <Generate your state value and store in session>;
var nonce = <Generate your nonce value and store in session>;
var login_hint = req.body.email; // Optional. The email of the PrivaKey user to authenticate as

loginUrl = privakeySignOn.loginUrl(issuer, clientID, redirectUrl, response_type, state, nonce, login_hint);

return res.redirect(loginUrl);

After successfully authenticating with your mobile device, the page will redirect to your redirect url.

Code Flow

If the response type is 'code', then handle the response from the query string which will contain a code (used to get the ID token) and a state variable.

var privakeySignOn = require('privakey-sign-on');
var issuer = 'https://idp.privakey.com';
var client_id = '1clientGuid';
var client_secret = 'secret';
var redirect_uri = 'http://localhost:1337/return';
var nonce = <Retrieve your nonce value from the session>;
var state = <Retrieve your state value from the session>;

if(req.query && req.query.code && req.query.state === state)
{
	privakeySignOn.getIdToken(req.query.code, issuer, client_id, client_secret, redirect_uri, function(result) {
		var token = result;
		// validate id token
		privakeySignOn.verify(token, issuer, client_id, nonce, function(err, result) {
			if(err)
			{
				var title = 'An error occurred during authentication.';
				res.view('login', {'title':title});
				return;
			}

			var title = 'Successful login with subject id: ' + result;
			res.view('login', {'title':title});
		});
	});
}

Note: There is also a function, privakeySignOn.getTokens, which will return both the access and authorization tokens, if you need both of them. getTokens takes the same parameters as privakeySignOn.getIdToken.

Implicit Flow

If the response type is 'id_token', then handle the response from the form post data which will contain the ID token and state variable.

var privakeySignOn = require('privakey-sign-on');
var issuer = 'https://idp.privakey.com';
var client_id = '1clientGuid';

if(req.body && req.body.id_token && req.body.state === state)
{
	var token = req.body.id_token;
	privakeySignOn.verify(token, issuer, client_id, nonce, function(err, result) {
		if(err)
		{
			title = 'An error occurred during authentication.';
			res.view('login', {'title':title});
			return;
		}

		title = 'Successful login with subject id: ' + result;
		res.view('login', {'title':title});
	});
}

Getting User Identifier

You can use the result of the verify function's callback as the Subject Identifier to use to bind to your individual user's account.

Sample

A sample sails.js app is provided in the sample folder. You can configure your client id and secret, for the sample, in the config file found in sample/config/env/development.js.

Be sure to restore dependent node modules of the sample app by running npm update from the sample folder on the command line.

npm update

After updating the npm packages, cd to the assets folder and run bower install to install the required bower dependencies.

To start the app, go to the sample folder directory on the command line and run sails lift. You can browse to the app by going to http://localhost:1337.

sails lift