Loopback-component-auth NPM

loopback-component-auth

Extends loopback-component-passport to support custom auth schemes (i.e. other than the supported 'ldap', 'local', 'oauth', 'oauth1', 'oauth 1.0', 'openid', 'openid connect' and 'oauth 2.0')

Installation

$ npm install --save loopback-component-auth

(the --save option saves it as dependency in your package.json).

Mount component to your Loopback Application

This module's main export is a function that follows the component contract defined in loopback. With that said, you can configure this components declaratively in component-config.json or require this module in a boot script and call the exported function with your app object as well as options.

Example: configure declaratively

{
  "loopback-component-auth": {
    "serverBaseUrl": "https://secure.my-server.com"
  }
}

Example: configure from boot script

'use strict';

const authComponent = require('loopback-component-auth');
const authOptions = { serverBaseUrl: 'https://secure.my-server.com' };

module.exports = function bootAuthComponent(app) {
  authComponent(app, authOptions);
}

Component Options

Name	Required	Type	Default	Description
appRootDir	`false`	`String`	`path.join(process.cwd(), 'server')`	an absolute path referencing your Loopback Application's root directory (typically `<project>/server`)
enableSessionSupport	`false`	`Boolean`	`false`	is forwarded to the `init` method of `loopback-component-passport`'s `PassportConfigurator`. Will ultimately require `express-session` to be installed
contextRoot	`false`	`String`	`'/auth'`	http junction used to prefix all resources provided by this component (includes routes for providers)
serverBaseUrl	`false`	`String`	`'http://localhost:3000'`	base url used to `url.resolve()` all computed absolute urls to access resources under this component
frontendBaseUrl	`false`	`String`	`serverBaseUrl`, `'http://localhost:3000'`	base url used to `url.resolve()` `successRedirect` and `failureRedirect` urls for non-json providers. When only `serverBaseUrl` is provided, that value is used here as well
models	`false`	`Object`	`{}`	an object literal bundling information about the models described in this table. All models will default to those provided by loopback-component-passport, AccessToken, User
models.userModel	`false`	`String`, `Model`	`'User'`	String or Model instance resolving to a model to access user records. When providing a `String`, model instance will be resolved from `app.registry.getModel('userModel')`
models.userIdentityModel	`false`	`String`, `Model`	`'UserIdentity'`	String or Model instance resolving to a model to access user-identity records. When providing a `String`, model instance will be resolved from `app.registry.getModel('userIdentityModel')`
models.userCredentialModel	`false`	`String`, `Model`	`'UserCredential'`	String or Model instance resolving to a model to access user-credential records. When providing a `String`, model instance will be resolved from `app.registry.getModel('userCredentialModel')`
models.accessTokenModel	`false`	`String`, `Model`	`'AccessToken'`	String or Model instance resolving to a model to access access-token records. When providing a `String`, model instance will be resolved from `app.registry.getModel('accessTokenModel')`

Configuring Providers

When loading this Loopback Component, it will use oniyi-config with { basePath: options.appRootDir + 'authentication', module: 'providers' }. With that said, you can configure all your authentication providers in files located e.g. at 'server/authentication' following the pattern providers.[environment].(json|js). The environment part is optional. Possible values are anything you can set in process.env.NODE_ENV. For file name resolution, process.env.NODE_ENV will be transformed to lower-case.
One special environment is local. It will always be loaded last.

Sample load order (with provess.env.NODE_ENV === 'development'):

'providers.json'
'providers.js'
'providers.development.json'
'providers.development.js'
'providers.local.json'
'providers.local.js'

Note: As files with extension json will always be loaded before files with extension js, you can provide the same file name with different extensions (meaning js will overwrite json files).

Those providers can then be either of the loopback third-party providers or a custom type with your own verify function according to the passport documentation

See server/authentication for an example

{
  "w3-connections": {
    "authScheme": "ibm-connections-basic",
    "module": "passport-ibm-connections-basic",
    "json": true,
    "session": false,
    "authHostname": "w3-connections.ibm.com",
    "openSocial": "/common"
  }
}

Noteworthy

sessions (including passport session middleware) are disabled per default.

Provideroptions

disabled (boolean) - default: false; when set to true, provider will not be registered
link (boolean)
module
strategy (string) - default: "Strategy"; name of the module's exported Property to be used as Passport Strategy
json
session

sheme options

makeLoginCallback (function) - receives single argument of type function (the "done" handler from passport's verify function). Must return function that takes (err, user, identity, token) as arguments and finally calls done(err, user, authInfo) according to the passport documentation. Purpose of the returned function is to serve as callback for UserIdentityModel.login(), which is documented here

strategy options

passReqToCallback
successRedirect (generated for non-json providers only, uses frontendBaseUrl as base url)
failureRedirect (generated for non-json providers only, uses frontendBaseUrl as base url)
domain
scope
failureFlash
authInfo

route options

routeName: any. one route with name 'auth' is always created.

path - - computed to: ${contextRoot}/${providerName}/${routeName}; path to register authenticate or authorize controller
method - (String) - Allows values of 'GET' and 'POST', defaults to 'GET' when provided value doesn't match one of the allowed values case-insensitively; method to register authenticate or authorize controller
bodyParser (string) - required when method === 'POST', must be one the parsers provided by body-parser module
bodyParserOptions (object) - optional; passed to bodyParser['bodyParser'](bodyParserOptions)
middleware (function)