Node.js module for user-based authentication

If you're using Node.js to create the server-side components of your web application, you can use our Passport-qnxion module to handle user-based authentication for an application that supports Express. It's presumed that you know how to develop using Node.js, Passport, and Express.

This module allows you to:

To simplify your web application development, you can call the install() from your server-side component to add the required default routes in one step. To see how to use it, see Using install().

Note: An API KEY and API SECRET are required to use this module. To obtain these, you have to use the administration console to create an application entity on the BlackBerry IoT Platform:

Install the module

To get access to this SDK, contact a representative from our sales team. After you get the module, you can install it using npm install passport-qnxion.

Using install()

The install() function adds express.Router() URL handler routes that interact with Passport. These routes provide authentication support to the BlackBerry IoT Platform for your Express application.

To use this function, you pass your Express object and configuration objects (including scope parameters). Here's how you would use install() to pass the API KEY and API SECRET, specify a callback URL to your local server, and specify a scope of email and profile.

var qnxionpp = require('passport-qnxion');

var express = require('express');
var app = express();

app.set('port', '9200');
app.use(session({resave: true, saveUninitialized: true, secret: 'somekey'}));

qnxionpp.install(app, {apiKey:'myAp1K3YfR0mBlackBerryIoT',
                       apiSecret:'myAp1S3cR3tfR0mBlackBerryIoT=',
                       scope:'email profile',
                       callbackURL:'http://mydomain.com/auth/login/callback/'});

The three default routes that are added to your middleware are:

Configure Strategy

The strategy authenticates a user with the BlackBerry IoT Platform account using OAuth 2.0, which we refer to as user-based authentication. The strategy requires an API SECRET, API KEY, callback URL, and a verify callback. For more information about the parameters, see Strategy.

...
...
var qnxionpp = require('passport-qnxion');
var QnxionStrategy = require('passport-qnxion').Strategy;
...
...
passport.use(new QnxionStrategy({
      apiKey: 'myAp1K3YfR0mBlackBerryIoT',
      apiSecret: 'myAp1S3cR3tfR0mBlackBerryIoT=',
      callbackURL: 'http://mydomain.com/auth/login/callback/'
    },
    function(accessToken, refreshToken, profile, done) {
        process.nextTick(function () {
        profile.accessToken = accessToken;
        return done(null, profile);
      });
    }
));
...
...

Set up routes

If you don't call install() function, you can configure your own routes as follows:

If you want to use default routes added by the module, use install(). For example, here's how to set up the login route:


app.get('/auth/login',
  function(req, res, next) {
    // Save callback in a session
    req.session.authCallback = req.headers.referer;
    req.session.save(next);
  },

    passport.authenticate('qnxion', {
    failureRedirect: '/auth/login',
    scope: 'email profile inherit_user'
  })
);

app.get('/callback',
            passport.authenticate('qnxion', {
                                   failureRedirect: '/auth/login/error'
  }),);

Authenticate Requests

You can handle authentication in the /auth/login route. To authenticate, call passport.authenticate(), use qnxion as the strategy, and provide scope and failureRedirect as part of the extended parameters.

The scope parameter is used to indicate the permissions that you want the user to grant your application. For more information about scope, see Details of the Passport-qnxion module.

Here's how you configure the permissions you want the user to grant your application and then delegate the authentication request:


var qnxionpp = require('passport-qnxion');
var QnxionStrategy = require('passport-qnxion').Strategy;
var passport = require('passport');

...
...

passport.use(new QnxionStrategy({
      apiKey: 'myAp1K3YfR0mBlackBerryIoT',
      apiSecret: 'myAp1S3cR3tfR0mBlackBerryIoT=',
      callbackURL: 'http://mydomain.com/auth/login/callback/'
    },
    function(accessToken, refreshToken, profile, done) {
             process.nextTick(function () {
             profile.accessToken = accessToken;
             return done(null, profile);
      });
    }
));
...
...
//In your /auth/login route, you can specify the scope.
 passport.authenticate('qnxion', {
                        failureRedirect: '/auth/login',
                        scope: 'email profile inherit_user'});

Details of the Passport-qnxion module

The Passport-qnxion module allows you to add user-based authentication to your applications. You can choose to configure your own routes or use the default routes.

As part of using the Passport-qnxion, you should pass in scope to specify the permissions you want the user to grant to your application. These permissions appear on the Authorization webpage that's shown to the user authorizing your application. These are the permissions you can specify:

To configure the strategy, you use the following properties:

install()

This function sets up the required routes, allows you to pass in the strategy parameters, and specify the scope in one step. To use this function, pass an Express object and strategy. Optionally, you can use different routes as well. If you don't provide a value for the routeOptions argument, preset routes are used.

The arguments are:

Strategy

This constructor creates an authorization strategy that you can use to authenticate with the BlackBerry IoT Platform using OAuth 2.0.

When you want to authenticate, you must call passport.authenticate() and specify the following parameters:

The arguments are: