IBM Mobile First Passport Strategies (Bluemix version)

The passport-imf-token-validation (Bluemix version) npm module provides validation strategies for protecting your Node.js apps.

Strategies

ImfBackendStrategy

passport.use(new ImfBackendStrategy(options));

The options parameter is optional. If specified, it can contain:

• cacheSize The cache size, the default value is 10000;
• logger An ibm logger instance, the default value is the default ibm logger which outputs log messages to the console.

The ImfBackendStrategy is used for a backend application that is deployed on IBM Bluemix. It will validate the authorization header from an incoming request against the IMF server url specified in the VCAP_SERVICES variable, where the service name starts with AdvancedMobileAccess, for the appId extracted from VCAP_APPLICATION.

ImfResourceStrategy

passport.use(new ImfResourceStrategy(options));

The options parameter is optional. If specified, it can contain:

• appId Optional. Specifies the application id for which the authorization will be validated.
• applicationIdProvider Optional. Specifies a mechanism to obtain the application id by calling the function applicationIdProvider(request). The ImfResourceStrategy will try to get the application id from the options appId first, then by calling the method applicationIdProvider; if neither of these options are specified, the application id will be obtained from the request url.
• serverUrl Specifies the IBM MobileFirst server URL from which the public key will be retrieved to verify the authorization header.
• cacheSize The cache size, the default value is 10000.
• logger An IBM logger instance. The default value is the default IBM logger, which outputs log messages to the console.

Instead of defining the above optional appId,applicationIdProvider or serverUrl in the options parameter of the ImfResourceStrategy constructor, you can also specify them in the options of the passport.authenticate() method. No matter where these three options are specified, the application id and serverUrl are mandatory, otherwise an error 400 will occur.

Sample

The following sample shows how to use ImfBackendStrategy in a node application:

var express = require('express')
  , passport = require('passport')
  , ImfBackendStrategy = require('passport-imf-token-validation').ImfBackendStrategy;

var options = {};

passport.use(new ImfBackendStrategy());

var app = express();

app.use(passport.initialize());

app.get('/v1/apps/:appid/service', passport.authenticate('imf-backend-strategy', {session: false }),
	function(req, res){
		res.send(200, req.securityContext);
	}
);

app.listen(3000);

To start the sample, issue the following commands:

$ npm install express
$ npm install passport
$ npm install passport-imf-token-validation

Authorization header

The authorization header in the request consist of three parts Bearer, Access Token and Id Token that are separated by a white space: Bearer <Access Token> <Id Token>

For passport-imf-token-validation, <Access Token> is mandatory and <Id Token> is optional. The validation works as follows:

• It will verify the signature of the access token and id token, as well as their exp field.
• It requires that aud be the same as the application id for which the authorization is validated.
• It requires that the authorization header start with Bearer, otherwise a 400 error will be returned, with the response header WWW-Authenticate: Bearer realm="imfAuthentication".
• If the access token or id token is invalid, for example, they have expired or cannot be decodes, validation will return a 401 error, with the response header WWW-Authenticate: Bearer realm="imfAuthentication", error="invalid_token".

IBM MobileFirst security context

After the authorization validation has passed, a security context object is added in the current request. Basically, the security context contains the subject, user, device and the application information. The following is a sample: The securityContext object contains the following fields:

• imf.sub: The subject of the id token or the unique id of the client if there is no id token.
• imf.user: The user value extracted from the id token. If there is no id token, this field holds a blank object.
• imf.device: The device value extracted from the id token. If there is no id token, this field holds a blank object.
• imf.application: The application value extracted from the id token. If there is no id token, this field holds a blank object.

The imf.user field in the security context is extracted as the user object in passport framework.

{"imf.sub":"myclientid",
 "imf.user":{"id":"user-name","authBy":"myrealm","displayName":"display-name"},
 "imf.device":{"id":"device-id","platform":"iOSnative","model":"device-model","osVersion":"device-os"},
 "imf.application":{"id":"ios.bundle.id","version":"1.0"}
}

License

This package contains sample code provided in source code form. The samples are licensed under the under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 and may also view the license in the license.txt file within this package. Also see the notices.txt file within this package for additional notices.