Uttori Plugin - Auth Simple

A plugin to add very simple authentication using express-session. A great starting point for any Uttori auth solution.

On /login success, as HTML it will redirect to the provided loginRedirectPath with a 302 status code.

On /login success, as JSON it will return the payload from validateLogin(request.body) and set it on the session as request.session.profile.

On /login error, as HTML it will redirect to the provided loginPath with a 401 status code.

On /login error, as JSON it will return the payload { error: true } with a 401 status code.

Note: When using with browser based fetch or the like, ensure withCredentials is set to true.

Install

npm install --save uttori-plugin-auth-simple

Config

{
    // Registration Events
    events: {
      bindRoutes: ['bind-routes'],
      validateConfig: ['validate-config'],
    },

    // Login Path
    loginPath: '/login',

    // Login Redirect Path
    loginRedirectPath: '/',

    // Login Route Middleware
    loginMiddleware: [],

    // Logout Path
    logoutPath: '/logout',

    // Logout Redirect Path
    logoutRedirectPath: '/',

    // Logout Route Middleware
    logoutMiddleware: [],

    // Validation function that will recieve the request and returns an object to be used as the session payload.
    // If the session is invalid it should return false.
    validateLogin: (request) => {},
}

---

API Reference

Classes

AuthSimple

Uttori Auth (Simple)

Functions

asyncHandler() : function

Typedefs

AuthSimpleConfigEvents : object

AuthSimpleConfig : object

AuthSimple

Uttori Auth (Simple)

Kind: global class

• AuthSimple
  • .configKey ⇒ string
  • .defaultConfig() ⇒ AuthSimpleConfig
  • .validateConfig(config, _context)
  • .register(context)
  • .bindRoutes(server, context)
  • .login(context) ⇒ function
  • .logout(context) ⇒ function

AuthSimple.configKey ⇒ string

The configuration key for plugin to look for in the provided configuration.

Kind: static property of AuthSimple
Returns: string - The configuration key.
Example (AuthSimple.configKey)

const config = { ...AuthSimple.defaultConfig(), ...context.config[AuthSimple.configKey] };

AuthSimple.defaultConfig() ⇒ AuthSimpleConfig

The default configuration.

Kind: static method of AuthSimple
Returns: AuthSimpleConfig - The configuration.
Example (AuthSimple.defaultConfig())

const config = { ...AuthSimple.defaultConfig(), ...context.config[AuthSimple.configKey] };

AuthSimple.validateConfig(config, _context)

Validates the provided configuration for required entries.

Kind: static method of AuthSimple

Param	Type	Description
config	object	A configuration object.
config.configKey	object	A configuration object specifically for this plugin.
_context	object	Unused.

Example (AuthSimple.validateConfig(config, _context))

AuthSimple.validateConfig({ ... });

AuthSimple.register(context)

Register the plugin with a provided set of events on a provided Hook system.

Kind: static method of AuthSimple

Param	Type	Description
context	object	A Uttori-like context.
context.hooks	object	An event system / hook system to use.
context.hooks.on	function	An event registration function.
context.config	object	A provided configuration to use.
context.config.events	object	An object whose keys correspong to methods, and contents are events to listen for.

Example (AuthSimple.register(context))

const context = {
  hooks: {
    on: (event, callback) => { ... },
  },
  config: {
    [AuthSimple.configKey]: {
      ...,
      events: {
        bindRoutes: ['bind-routes'],
      },
    },
  },
};
AuthSimple.register(context);

AuthSimple.bindRoutes(server, context)

Add the login & logout routes to the server object.

Kind: static method of AuthSimple

Param	Type	Description
server	object	An Express server instance.
server.post	function	Function to register route.
context	object	A Uttori-like context.
context.config	object	A provided configuration to use.

Example (AuthSimple.bindRoutes(server, context))

const context = {
  hooks: {
    on: (event, callback) => { ... },
  },
  config: {
    [AuthSimple.configKey]: {
      loginPath: '/login',
      logoutPath: '/logout',
      loginMiddleware: [ ... ],
      logoutMiddleware: [ ... ],
    },
  },
};
AuthSimple.bindRoutes(server, context);

AuthSimple.login(context) ⇒ function

The Express route method to process the login request and provide a response or redirect.

Kind: static method of AuthSimple
Returns: function - - The function to pass to Express.

Param	Type	Description
context	object	A Uttori-like context.
context.config	object	A provided configuration to use.

Example (AuthSimple.login(context)(request, response, next))

server.post('/login', AuthSimple.login(context));

AuthSimple.logout(context) ⇒ function

The Express route method to process the logout request and clear the session.

Kind: static method of AuthSimple
Returns: function - - The function to pass to Express.

Param	Type	Description
context	object	A Uttori-like context.
context.config	object	A provided configuration to use.

Example (AuthSimple.login(context)(request, response, _next))

server.post('/logout', AuthSimple.login(context));

asyncHandler() : function

Kind: global function

AuthSimpleConfigEvents : object

Kind: global typedef
Properties

Name	Type	Description
bindRoutes	Array.<string>	The collection of events to bind to for setting up the login and logout routes.
validateConfig	Array.<string>	The collection of events to bind to for validating the configuration.

AuthSimpleConfig : object

Kind: global typedef
Properties

Name	Type	Default	Description
[events]	AuthSimpleConfigEvents		Events to bind to.
[loginPath]	string	"'/login'"	The path to the login endpoint.
[loginRedirectPath]	string	"'/'"	The path to redirect to after logging in.
[loginMiddleware]	Array.<function()>	[]	The middleware to use on the login route.
[logoutPath]	string	"'/logout'"	The path to the logout endpoint.
[logoutRedirectPath]	string	"'/'"	The path to redirect to after logging out.
[logoutMiddleware]	Array.<function()>	[]	The middleware to use on the logout route.
validateLogin	function		A function that accepts a Request object and validates a users credentials, if they are invalid it should return false.

---

Tests

To run the test suite, first install the dependencies, then run npm test:

npm install
npm test
DEBUG=Uttori* npm test

Contributors

• Matthew Callis

License

• MIT