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

Functions

Typedefs

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