Skip to content

Latest commit

 

History

History
143 lines (107 loc) · 7.97 KB

README.md

File metadata and controls

143 lines (107 loc) · 7.97 KB
Raw

NPM version Dependency Status

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'):

  1. 'providers.json'
  2. 'providers.js'
  3. 'providers.development.json'
  4. 'providers.development.js'
  5. 'providers.local.json'
  6. '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)

License

Apache-2.0 © Benjamin Kroeger