The Passport Strategy for IBM MobileFirst™ Foundation Security

The module passport-mfp-token-validation provides IBM MobileFirst Foundation passport strategy to validate the request authorization header that accesses the protected resource.

Versions

For working with specific versions of MobileFirst Foundation, the module should be installed with the specific version:

MobileFirst Foundation V7.0.0

$ npm install [email protected]

MobileFirst Foundation V7.0.1

$ npm install [email protected]

MobileFirst Foundation V8.0.X

$ npm install [email protected]

Sample

    var express = require('express');
    var passport = require('passport-mfp-token-validation').Passport;
    var mfpStrategy = require('passport-mfp-token-validation').Strategy;
    var scope = 'usernamePassword';
    var strategyName = 'mobilefirst-strategy';
    
    var logger = require('winston');
    logger.level = 'debug';
    
    passport.use(new mfpStrategy({
        authServerUrl: 'http://localhost:9080/mfp/api',
        confClientID: 'testclient',
        confClientPass: 'testclient',
        
        // Cache size is optional. The default is 50000.
	    cacheSize: 0,
        
        // The analytics item is optional and only required if you wish
        // to log analytics events to MFP.
        analytics : {
            onpremise: {
                url : 'http://localhost:9080/analytics-service/rest/v3',
                username : 'admin',
                password : 'admin'
            }
        },
        
        // Name is optional. The default is 'mobilefirst-strategy'.
        name: strategyName,
        
        // logger is optional and only required if you wish to define a logger instance.
        // The default value is the winston logger with info level, which outputs log messages to the console.
        logger: logger,
        
        // certificate is optional and only required if the connection to the authorization server uses SSL.
        // certificate: 'certificate.crt'
   }));

    var app = express();
    app.use(passport.initialize());

    app.get('/v1/apps/:appid/service', passport.authenticate(strategyName, {session: false, scope:scope}),
        function(req, res){
            res.status(200).send(req.securityContext);
		}
	);

	app.listen(3000);

Start Sample

$ npm install express
$ npm install passport-mfp-token-validation
$ npm install winston

MFP Strategy

passport.use(new mfpStrategy(options));

The options contains:

• authServerUrl (Mandatory) Specifies the URL of the MobileFirst Server.
• confClientID Required only in case of internal authorization server. Specifies the confidential client ID, which should be defined in MobileFirst Server.
• confClientPass Required only in case of internal authorization server. Specifies the confidential client password, which should be defined in MobileFirst Server.
• cacheSize The maximum number of tokens to be stored in the cache. The default value is 50000. In case of 0, no token is saved in cache. In case of negative number, the default is taken.
• name The strategy's name. The default value is 'mobilefirst-strategy'.
• logger Defines a logger instance. The default value is the IBM® default logger with INFO level, which outputs log messages to the console.
• certificate Specifices the path to the authorization server's SSL certificate. If the connection to the authorization server uses SSL, you need to obtain the SSL certificate from the Authorization server, and put it in a local directory. Use the following command to obtain the certificate: 'openssl s_client -connect AUTH_SERVER_URL:AUTH_SERVER_SSL_PORT | openssl x509 > certificate.crt'.

The analytics.onpremise is optional variable, which contains :

• url The url that specifies the location of the operational analytics server. For example, http://localhost:9080/analytics-service/rest/v3.
• username The username if credentials are required.
• password The password if credentials are required.

MFP authentication

passport.authenticate(strategyName, {session: false, scope:scopes})

The middleware contains:

• strategyName (Mandatory) Specifies the strategy's name. The default value is 'mobilefirst-strategy'.
• session (Mandatory) Must always be false.
• scope Space-separated list of scopes elements that are required for accessing the resource.

Obtaining a Token

The passport-mfp-token-validation module obtains a token for itself from the token endpoint. It must be defined as a confidential client in order to receive a token.

Token Verification

The passport-mfp-token-validation module verifies the authorization header of the request. The authorization header consists of the following elements:

Bearer Access_token

where

• Bearer (Mandatory) Is the required string for the token type, as defined in the OAuth 2.0 specification.
• Access_token (Mandatory) The generated token by MFP OAuth provider.

The passport-mfp-token-validation module sends the access token to MFP introspection endpoint, along with the token of the module itself. The access token is verified by the MFP token endpoint, which sends a response. If the response is verified successfully by the module, an access to the protected resource is granted. In addition, the securityContext object will be a part of the request.

securityContext

After a successful validation, a security context is added to the current request. In addition, it is used for caching and analytics.

The securityContext object contains the following fields:

• active: Specifies Whether the context is active.
• client_id: The client ID. It's composed by the device ID and application ID. There could be several client IDs on one device.
• exp: The expiration time since epoch time.
• mfp-device: The device value. Contains deviceDisplayName, deviceStatus, id, model and os.
• mfp-application: The application value. Contains clientPlatform, id, packageName and version.
• mfp-user: The user value. Contains attributes, authenticatedAt, authenticatedBy, displayName and id.
• mfp-checks: Contains all the checks which the user passed.
• scope: Space-separated string containing the list of the granted scopes names.
• username: The username. It can be created by a security check and it's optional. The default value is an empty string.

More Information

• IBM MobileFirst Foundation (cross-platform) - change the link

• IBM MobileFirst Foundation for iOS (iOS only) - change the link

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.